16 May 2014 mcxmap 14-137
mcxmap — permute or remap the indices of graphs and matrices.
mcxmap -imx fname (input)[-o fname (output)] [-make-map (output map file name)] [-make-mapc (output map file name)] [-make-mapr (output map file name)] [-cmul a (coefficient)] [-cshift b (translate)] [-rmul c (coefficient)] [-rshift d (translate)] [-mul e (coefficient)] [-shift f (translate)] [-map fname (row/col map file)] [-rmap fname (row map file)] [-cmap fname (column map file)] [-mapi fname (row/col map file (use inverse))] [-rmapi fname (row map file (use inverse))] [-cmapi fname (column map file (use inverse))] [-tab fname (read (and map) tab file)]
This utility relabels graphs or matrices. Its main use is in applying a map file to a given matrix or graph. A map file contains a so called map matrix in mcl format that has some special properties (given further below). The functionality of mcxmap can also be provided by mcx, as a mapped matrix (i.e. the result of applying a map matrix to another matrix) is simply the usual matrix product of a matrix and a map matrix. However, mcx will construct a new matrix and leave the original matrix to be mapped alone. When dealing with huge matrices, considerable gains in efficiency memory-wise and time-wise can be achieved by doing the mapping in-place. This is what mcxmap does. In the future, its functionality may be embedded in mcx with new mcx operators.
The special properties of a map matrix are
The column domain and row domain are of the same cardinality.
Each column has exactly one entry.
Each row domain index occurs in exactly one column.
These properties imply that the matrix can be used as a map from the column domain onto the row domain. An example map matrix is found in the EXAMPLES Section.
Different ways to specify map files.
Generate a map that maps the specified domain onto the appropriate canonical domain and write the map matrix to file.
These options have affect if neither a column map file nor column canonification is specified. If any of the first two options is used, column indices i are mapped to a*i+b.
These options have affect if neither a row map file nor row canonification is specified. If any of the first two options is used, indices i are mapped to c*i+d.
If a map file is specified for a given domain, neither a map file nor canonification is specified. If any of the first two options is used, the indices i will be mapped to e*i+f.
This option requires the -map option. mcxmap will output the mapped tab definition.
The matrix below has two canonical domains which are identical. It denotes a map of the canonical domain onto itself, in which node 0 is relabeled to 8, node 1 is relabeled to 5, et cetera.
Stijn van Dongen.
mcxio, mcx, mcxsubs, and mclfamily for an overview of all the documentation and the utilities in the mcl family.