Vismatrix Documentation
Vismatrix is used to visualize large sparse matrices along with many other optional properties that can be associated with matrices. It is a command-line driven program and all options and data files must be specified as arguments.
Synopsis
usage: vismatrix[options] options: labels [-rl ] [-cl
] [-rcl ] permutations [-rp
] [-cp
] [-rcp ] markers [-rm
|
] [-cm ] [-rcm |
] partitions [-rpart ] [-cpart ] [-rcpart ] colors red,orange,yellow,green,blue,violet [ -colormap ] normalize [-rnorm] [-cnorm] [-rcnorm] sampling and alpha [-dp ] [-alpha ]
The text above is the default help message vismatrix prints when it run from the command line with no options. In angled brackets <> are names of arguments and arguments in square brackets [] are optional.
Controls Summary
Mouse
Left - move
CTRL Left - move cursor
Right - zoom
Keys
h - move to 'home' position
s - show/hide cursor
m - show/hide markers
z - zoom in
Z - zoom out
a - reduce alpha
A - increase alpha
0-9 - display percent (percent = 1/(2^key))
esc - quit
Input Data Matrix
The input data matrix that is to viewed is specified as the first argument, <smat file>. Its file format must be smat. This is the only required argument. Non-zeros will be plotted at colored points (color configurable) and zeros will be left as black space.
Option Conventions
Most options refer to either the rows, columns, or both. These options often take the form -r<option> -c<option> and -rc<option>. For example, row permutation, row labels, and row partitions are specified as -rp -rl and -rpart, respectively.
Row and Column Labels
The rows and columns of the matrix can be labeled with strings of text. This text is visible within vismatrirx by pressing 's' (show cursor) and middle clicking on any row and column. The related options are -rl -cl and -rcl which specify row labels, column labels, and identical row/col labels respectively. Labels should be stored in label file format.
Permutation Vectors
The matrix may be displayed with permuted rows and columns. This is specified with permutation vector files on the command line with options -rp -cp or -rcp which specify the row permutation, column permutation, and identical row/col permutation, respectively. The format for permutation vectors can be found in the formats section.
Markers
Markers can be used to visually mark important rows or columns with colored lines. The significance of such rows and columns is application specific. Markers are specified with -rm -cm and -rcm to indicate markers for rows, columns, and row/column pairs respectively. Rows and columns are indicated with an index number starting from zero. The color of the marker must also be specified. The available colors include red, orange, yellow, green, blue, and violet.
Partitions
The user may visualize partitions that exist in the matrix by specifying a partition file. For example, in the application of data clustering, rows or columns of a matrix can be grouped together by similarity (which can be measured in many ways). and Vismatrix can display these groups by drawing colored dividing lines between partitions. To do this, permutation files must be given that reorder the rows (columns) such that rows (columns) of the matrix that belong to the same group are displayed consecutively. Also a partition file must be given that states the group id of each row (column) in the matrix. With this information, Vismatrix iterates through the rows (columns) of the matrix and indicates when the group id of the rows (columns) change by drawing a dividing color line. NOTE: if the permutation file is not correct (or is not specified), than a large number of divisors could be generated.
Colors
The colors used to plot points are specified by a color map. The default color map assigns the lowest val to blue, intermediate values to green, and the highest value to red. A different color map may be specified with the -colormap option. The color map file given must follow the color map file format.
Normalization
The matrix may be normalized by Vismatrix before display. Vismatrix has three types of normalization built-in: row, column, and row & column normalization. Row (Column) normalization takes each value in the row (column) and divides it by the sum of all values in the row (column).
Graphical notes - alpha values
The alpha values (opacity) for non-zero valued plots may be adjusted using the keys 'A' (increase opacity) and 'a' (decrease opacity). At full alpha (1.0) each non-zero will cause the pixels it is assigned to be at full brightness. In the case of a large matrix that is zoomed out, many plots, possibibly thousands, will be assigned to one pixel. With alpha at 1.0 it will only take one non-zero value among thousands of matrix entries to make the associated pixel fully bright. However, thousands of non-zeros that are sufficently close together will also produce the same effect. The net effect, is that the matrix will look overly filled in with non-zeros at this alpha setting.
To produce a more accurate image, the alpha value should be lowered. This means each plot only contributes a small amount to the final brightness of a pixel. That way a pixel can only achieve full brightness when all of its associated matrix entries are non-zero.
Graphical Notes - Sampling
Some matrices are so large that navigation is difficult because the computer is slowed down by excessive computation. However, not every plot is needed in order to get a sense of the matrix's structure while navigating. This is the motivation behind sampling the matrix with the -dp option and number 0-9 keys. With these features the a small percentage of the non-zeros can be randomly chosen to represent the full matrix.