Matrices (Mathematics) - singa-bio/singa GitHub Wiki

Matrices are mathematical constructs that contains multiple values. They represent a rectangular array of numbers organized in rows and columns. SiNGA differentiates between labeled and unlabeled matrices. A matrix is a Ring and MultiDimensional.

1,00 5,00 6,00 9,00 8,00 7,00
3,00 1,00 6,00 8,00 5,00 7,00
2,00 7,00 5,00 8,00 8,00 3,00
5,00 8,00 6,00 4,00 8,00 3,00
1,00 5,00 9,00 7,00 8,00 2,00

A classical rectangular unlabeled Matrix

Labeled matrices are useful to map indices with values. For example a substitution matrix like BLOSUM and PAM can be used to find the exchange probability of two amino acids.

   C1 C2 C3 C4
R1  1  2  3  4
R2  5  6  7  8
R3  9 10 11 12
R4 13 14 15 16

A classical labeld map

How to generate a matrix

There are some possibilities to initiate a matrix in this package. It is possible to create a identity matrix with generateIdentityMatrix(size) or a matrix of ones with generateMatrixOfOnes(rowsize, columnsize). Additionally, matrices can be instantiated using arrays.

Matrix matrix = new RegularMatrix(new double[][]{{2, 1, -1}, {-3, -1, 2}, {-2, 1, 2}});

It is often necessary to read a Matrix from a file. The matrices must be written in the correct csv format:

1;5;6;9;8;7
3;1;6;8;5;7
2;7;5;8;8;3
5;8;6;4;8;3
1;5;9;7;8;2

example of a CSV file for unlabeled matrices

;C1;C2;C3
R1;1;2;3
R2;4;5;6
R3;7;8;9

example of a CSV file for labeled matrices

The method .readUnlabeledMatrixFromCSV("your_path/your_file", delimiter) is intended for reading unlabeled matrices. For labeled matrices use .readLabeledMatrixFromCSV("your_path/your_file", delimiter). The standard delimiter is ,. If you want to use another delimiter you can define it the parameters of the method. In the following example the delimiter ; was used.

Path path =  Paths.get("your_path/your_file.csv");
Matrix matrix = Matrices.readUnlabeledMatrixFromCSV(path,";");

read a unlabeled matrix from text file.

LabeledMatrix labeledMatrix =  Matrices.readLabeledMatrixFromCSV(labeledPath, ";");

read a labeled matrix from text file.

Work with matrices

Regular matrices

In the class RegularMatrix, methods are implemented which, fulfill simple mathematical operations on matrices. The following table lists some methods:

Method	Function
`as`	Converts this matrix into a specific implementation. This only works if the "form" of this class is suitable to be converted. The new matrix is a copy of the old one.
`hadamardMultiply`	The Hadamard multiplication is the element-wise multiplication of two matrices. This operation takes two matrices of the same dimensions, and produces another matrix where each element ij is the product of elements ij of the original two matrices.
`getElements`	Returns all elements of this matrix as an two-dimensional array.
`getRow` or `getColumn`	Returns the selected row or column as a vector
`add`	Adds two matrices of the same dimension.
`transpose`	The transposition of this m-by-n matrix is a new matrix n-by-m formed by turning columns into rows and vice versa.

Labeled matrices

In the class LabeledRegularMatrix, methods are implemented to work with labeled matrices. Here it is possible to manipulate the labels or get any information based on the labels.

Method	Function
`setRowLabel`	Assign a label to a row.
`getRowLabel`	Returns the row label currently assigned to the given row index.
`getRowByLabel`	Returns the row with the matching label.
`getValueFromPosition`	Returns a value using the position given by a Pair of Integers.
`getStringRepresentation`	Returns a string representation of the labelled matrix such that a CSV compatible format is achieved.

Algorithms

SVD (singular-value decomposition)

The singular-value decomposition (SVD) is a factorization of a real or complex matrix. With this algorithm it is possible to determine the singular values. These characterize the properties of the matrix. The algorithms is applyable to quatric and non-quaternary matrices. The class SVDecomposition provides the algorithm.

QR-Decomposition

QR decomposition is the decomposition of a matrix A into the product of two matrices Q and R. Q is an orthogonal matrix and R is an upper triangular matrix, such that A = Q * R .

The class QRDecomposition implements the modified Gram-Schmidt Algorithm.

 Matrix qrExample = new RegularMatrix(new double[][]{{2, 1, -1}, {-3, -1, 2}, {-2, 1, 2}});
 QRDecomposition qrDecomposition = QRDecomposition.calculateQRDecomposition(qrExample);
 qrDecomposition.getMatrixQ();
 qrDecomposition.getMatrixR();

Q-Matrix

0,49 -0,73 -0,49
0,41 -0,30  0,86
0,77  0,62 -0,15`

R-Matrix

4,12 0,73 -2,91
0,00 1,57  0,71
0,00 0,00  0,15

Eigenvalue decomposition

Here a matrix is decomposed and displayed into its eigenvalues and eigenvectors. This only works with diagonal matrices. The class EigenvalueDecomposition provides the algorithm.