MATSCRIPT

A script interpreter for matrix manipulations, such as:

• Convert matrix files to a different format
• Scale matrices
• Merge matrices
• Transpose matrices
• Get matrix statistics
• Compare matrices

Scripting Syntax

A script file is a ASCII text file containing a series of commands lines that are executed by the MATSCRIPT-program line by line. Each line begins with a command, followed by a sequence of key=value pairs, separated by semicolons. Any lines that begin with the asterisk character (*) are considered comments and are ignored by the MATSCRIPT-program. The scritp file name is passed as an command line argument to the MATSCRIPT-program.

The following commands are supported:

init
The init-command initializes the script interpreter and should be the first command in any MATSCRIPT-script. It takes the following key-value pairs as an argument:

Key	Value
size	Size of the matrices being processed in the script
round	Rounding threshold. When writing matrices to file, all matrix cells with an absolute value less than the threshold get rounded to zero (optional, default equals 0)
row	Header for the Row-column used in text output files (optional, default equals "Row")
column	Header for the Column-column used in text output files (optional, default equals "Column")
log	Log file name (optional, default no logging to file)

read
The read-command reads matrices from a matrix input file. In addition to the key-value pairs specifying the file name and file format, it takes the following key-value pairs as an argument:

Key	Value
id	File identifier that can be used to reference the input file in subsequent command lines
ids	Comma separated list of matrix identifiers that can be used to reference matrices (contained in the input file) in subsequent command lines. The index in the list of identifiers coincides with the index of the matrix in the matrix input file. This (optional) key can thus only be used in the case of index based matrix access. In the case of label based matrix access the matrix-command must be used to specify the matrices in a matrix input file

matrix
The matrix-command specifies a matrix that is read from a matrix input file. It takes the following key-value pairs as an argument:

Key	Value
file	File identifier of the matrix input file the matrix is read from
index	Index of the matrix within the matrix input file. This key cannot be used together with the label key
label	Label of the matrix to be read from the matrix input file. This key cannot be used together with the index key
id	Matrix identifier that can be used to reference the matrix in subsequent command lines
tag	Matrix label to be used when writing the matrix to a matrix output file

transpose
The transpose-command calculates the transposed of a matrix. It takes the following key-value pairs as an argument:

Key	Value
matrix	Identifier of the matrix being transposed
id	Matrix identifier that can be used to reference the transposed matrix in subsequent command lines
tag	Matrix label to be used when writing the transposed matrix to a matrix output file

const
The const-command defines a matrix with constant values. It takes the following key-value pairs as an argument:

Key	Value
id	Matrix identifier that can be used to reference the matrix in subsequent command lines
value	The value of the matrix cells
tag	Matrix label to be used when writing the matrix to a matrix output file

scale
The scale-command multiplies all matrix cells with a fixed factor. It takes the following key-value pairs as an argument:

Key	Value
id	Matrix identifier that can be used to reference the scaled matrix in subsequent command lines
matrix	Matrix identifier of the matrix being scaled
factor	The multiplcation factor applied to all matrix cells
tag	Matrix label to be used when writing the scaled matrix to a matrix output file

round
The round-command rounds all matrix cells. It takes the following key-value pairs as an argument:

Key	Value
id	Matrix identifier that can be used to reference the rounded matrix in subsequent command lines
matrix	Matrix identifier of the matrix to be rounded
digits	The number of decimals places to round to (optional, default equals 0)
tag	Matrix label to be used when writing the rounded matrix to a matrix output file

merge
The merge-command calculates the sum of some matrices. It takes the following key-value pairs as an argument:

Key	Value
id	Matrix identifier that can be used to reference the merged matrix in subsequent command lines
matrices	Comma separated list of the matrix identifiers of the matrices that will be merged
tag	Matrix label to be used when writing the merged matrix to a matrix output file

write
The write-command writes matrices to a matrix output file. In addition to the key-value pairs specifying the file name and file format, it takes the following key-value pairs as an argument:

Key	Value
matrices	Comma separated list of matrix identifiers of the matrices that are written to the output file

stats
The stats command writes matrix statistics to the console. If a log file is specified in the init command, the matrix statistics are also written to the log file. It takes the following key-value pairs as an argument:

Key	Value
rows	Comma separated list of rows to include in the statistics (optional, default equals to all rows)
columns	Comma separated list of columns to include in the statistics (optional, default equals to all columns)
matrices	Comma separated list of matrix identifiers of the matrices to include in the statistics

compare
The compare command writes the sum of absolute differences bewteen two matrices to the console. If a log file is specified in the init command, the sum of absolute differences is also written to the log file. It takes the following key-value pairs as an argument:

Key	Value
rows	Comma separated list of rows to include in the comparison (optional, default equals to all rows)
columns	Comma separated list of columns to include in the comparison (optional, default equals to all columns)
matrices	Matrix identifiers of the two matrices to be compared, separated by a comma

Dependencies

MATSCRIPT uses the following libraries, that have been added as submodules:

• https://github.com/transportmodelling/Utils
• https://github.com/transportmodelling/matio

To use hdf5 based matrix formats (such as omx), the hdf5.dll must accompany the MATSCRIPT executable.