Contact: zeng  @  zegraph.com     Last update: 8 May 2008

Matrix Library

The library handles row-major data arrays of char, unsigned char, short, unsigned short, int, unsigned int, float, and double. The matrix library was substantially changed after December 2005. Refer to the old version if you do not want to update.

Matrix Creation

Function Parameters and Type Remarks
double([nrow, ncol) integers Creates a matrix of double type. See example-1.
double(a, b, c[, ...]) integers Creates a matrix of double type and fill it with numbers. See example-1.
double(M) matrix Creates a matrix of double type and fill it with numbers in matrix M. See example-1.
Note: A matrix of char, unsigned char, short, unsigned short, int unsigned int, and float can be created similarly by functions of char(), uchar(), short(), ushort(), int(), uint(), and float(); respectively. The old function matrix(typename, nrow, ncol) may also be used. See example-1.

Matrix Manipulation

Function Parameters and Type Acceptable Matrix Type Remarks
.clone(src) matrix all Resizes the caller and copies data from src. The function may be used to transfer data from one type of matrix to another efficiently. See example-2.
.delete(icol[, flag]) number, string all Deletes the ith column. Deletes the ith row if the optional flag is "r". See example-2.
.fill(initial, step) number, number all Fills the matrix with numbers with the first=initial, the second=initial + step, and etc. It will not check over flow. See example-2.
.find(v[,i0, j0]) number, integer, integer all Returns the row and column indices as array (i.e., [irow, icol]) at which the matrix value equals v, which must be integer when the matrix is not float or double type. If the optional i0 and j0 parameters are used, the function starts searching from row i0 and column j0. See example-2.
.flip([flag]) string all Flips columns by default. Flips rows if the optional flag is "r". See example-2.
.insert(icol, src[, flag]) number, number or matrix, string all Inserts src (number or matrix) to the caller before the ith column. If src is a matrix, it must be the same type and has the same number of rows as the caller. Insertion operates on row if the optional flag is "r", in which case src must have the same number of columns as the caller. See example-3.
.prod(src) matrix float or double Saves matrix product of the caller and src in the caller. The number of columns of the caller must equal the number of rows of src. See example-3.
.ptr([offset])   all Returns a array containing matrix pointer in [0], the number of data in [1], and the element byte size in [2]. See example-2.
.replace(index, src) matrix of int, matrix all Replace values at indices with values in src, i.e., caller[index[i]] = src[i]; therefore the dimension of src must be at least the same as that of index. Index values must nut be negative and be smaller than the size of the caller. See example-3.
.resize(nrow, ncol) integer, integer all Resizes the matrix. See example-2.
.reserve(n) integer all Reserves memory for at least n data. See example-2.
.reshape(nrow, ncol) integer, integer all Reshapes the matrix. nrow x ncol must equal the size of the caller. See example-2.
.size()   all Returns a array with the number of rows in [0], columns in [1], and total number of data in [2]. See example-2.
.sort(icol[, flag]) number[, number] all Sorts the matrix according the ith column. If flag > 0, sort in ascending order (default); otherwise in descending order. See example-3.
.trans()   all Matrix transpose. See example-2.
.unique([flag]) [number] all Makes the matrix unique. If flag > 0, unique elements are sorted in ascending order (default), otherwise in descending order. See example-3.

IO

Function Parameters and Type Acceptable Matrix Type Remarks
.csv([ format[, fname[, mode]]]) string, string, string all Prints matrix data to stdout or to the file. The default format string is " %d" for signed integer matrix, " %u" for unsigned integer matrix, and " %f" for real type matrix. The default mode is overwrite. Use "a" to set the mode to as appending. Comma is inserted between numbers. See example-4.
.parse(str) string all Parses numbers in the string. The matrix will be resized according to numbers in the string. See example-4.
.import(ptr) user all Import data from the pointer, which must point to enough number of data of the same type of the caller. See example-4.
.print([ format[, fname[, mode]]]) string, string, string all Similar to csv function, but no comma is inserted between numbers. See example-4.
.readtext(fname) string double Reads data from text file. Any rows in the file that have non-numeric characters will be ignored in parsing. The number of items of the first data row determins the column number of matrix; and the number of data rows deternines the row number of matrix. See example-4.

Math

Function Parameters and Type Acceptable Matrix Type Remarks
cos(p), acos(p), cosh(p), sin(p), asin(p), sinh(p), tan(p), atan(p), tanh(p), sqrt(p), exp(p), log(p), log10(p), ceil(p), floor(p), abs(p) matrix all Returns a double matrix filled with cos(p[i]) and etc. See example-5.
atan2(p1, p2) matrix or number all Returns a double matrix filled with atan2(p1,p2).p1 or p2 or both can be matrix. See example-6.
pow(p1, p2) matrix or number all Returns a double matrix filled with pow(p1,p2). p1 or p2 or both can be matrix. See example-6.
.rand([seed]) number all Fills the matrix with random numbers of 0 to 1. See example-5.
.min()   all Returns the smallest number in the the matrix. See example-5.
.max()   all Returns the largest number in the matrix. See example-5.
.sum()   all Returns the sum of elements in the matrix. See example-5.
.mean()   all Returns the mean of elements in the matrix. See example-5.
.stdev()   all Returns the standard deviation, i.e., sqrt(sum(Ei- mean)/(n-1)), of elements in the matrix. See example-5.
cal2jul(p) matrix all Returns a double matrix containing Julian date and time converted from Gregorian calendar year, month, day, hour, minute, second in the first three to six columns of p, which must have at least three columns. Missing hour, minute, and second are treated as zero. See example-7.
jul2cal(p) matrix all Returns a double matrix with the year, month, day, hour, minute, second in six columns. See example-7.

Unary Operators

Operator Left Operand Right Operand Remark
-   char, short, int, float, or double Returns the negative of the original. Element wise negate. See example-8.
~ all   Returns the transpose of the original. See example-8.
++ all   Element wise increment by 1. Underflow and overflow are nto checked. See example-8.
-- all   Element wise decrement by 1. Underflow and overflow are nto checked. See example-8.

Binary Operators

Operator Left Operand Right Operand Remark
+, -, *, /, % matrix or number matrix or number Returns a matrix. Element wise add, subtract, multiply, divide, or mod. See example-9.
+=, -=, *=, /=, %= matrix matrix or number The more efficient equivalent of +, -, *, /, and %. See example-9.
==, !=, >, >=, <, <= matrix or number matrix or number Element wise comparison. Returns a char-type matrix with element of 1 for true and 0 for false. See example-9.
&&, || matrix matrix or number Logical and/or comparison. Returns a char-type matrix with element of 1 for true and 0 for false. See example-9.
|, & matrix matrix Returns a matrix as the result of vertical/horizontal concatenation of two matrices. See example-9.
<<, >> matrix integer Left/right shift of matrix columns. See example-9.
^ matrix integer Up shift of matrix rows. See example-9.

Access by Index

Operator Array Indexes Remark
A[i] integer Returns the ith value. See example-10.
A[I] char matrix Returns a matrix of the same type containing A's values where I's value is non-zero. I must be the same size as A. See example-10.
A[b:e], A[b.e.s] index range Returns a matrix of the same type containing A's values in the index range of b to e, where b and e are integers indicating begin-index and end-index. If s is specified, the index goes from b to e with step s. See example-10.
A[*] index range The star symbol is a special index range meaning all indexes. See example-10.
A[i,j] integer or index range Returns the value at the index or values in the index range. i and j can be integer, index range (b:e, b:e:s, or *), or char matrix. See example-11.

Assignment by Index

Operator Array Index Right Operand Remark
A[i]=v integer number Sets number to the ith element. See example-12.
A[I]=v char matrix number Sets number to A's elements where I's values are non-zero. Matrix I must be the same size as A. See example-12.
A[b:e]=v, A[b:e:s]=v index range number Sets number to A's elements in the index range. Refer to A[b:e] in access by index for index range. See example-12.
A[*]=v index range number Sets number to A's elements where I's values are non-zero. Matrix I must be the same size as A. See example-12.
A[I]=V char matrix A-type matrix Sets values of V to A's elements where I's values are non-zero. Matrix I must be the same size as A. If V and A has the same size, the assignment is so called mapping, i.e., A[I[i]!=0]=V[i]. Otherwise, V's size must be larger than or equal to I's non-zero counting and the assignment is so called filling, i.e., A[I[i]!=0]=V[I's non-zero count up to i]. See example-13.
A[b:e]=V, A[b:e:s]=V index range A-type matrix Sets values of V to A's elements in the index range. Refer to A[b:e] in access by index for index range. Refer to A[I]=V for mapping and filling assignment. See example-13.
A[*]=V index range A-type matrix Refer to A[b:e]=V. The index range include all indexes of A. See example-13.
A[i,j]=v char matrix or index range number Sets number to A. i and j can be integer, index range (b:e, b:e:s, or *), or char matrix. See example-14.
A[i,j]=V char matrix or index range A-type matrix Sets values of V to A. i and j can be integer, index range (b:e, b:e:s, or *), or char matrix. Refer to A[i]=V, A[I]=V, A[b:e]=V, and A[*]=V for for mapping and filling assignment. See example-15.

Numeric

Function Parameters and Type Acceptable Matrix Type Remarks
.area()   double Assuming data in the matrix are polygon vertices, the function calculates polygon area. Matrix row and column must be greater than 2 and 1, respectively. The area is positive if the polygon winding is anti-clockwise, and negative otherwise. See example-16.
.delaunay([flag]) boolean double Finds Delaunay triangles for random points on a plane (the caller has two columns) or spherical surface (the caller has three columns). Returns an array with a matrix containing indices of triangles in [0] and a matrix containing convex hull indices in [1]. If the flag is true, the data are supposed to be non-intersect polygon vertices (e.g., coastline of island) and the triangulation is constrained by the polgyon.This function uses the STRIPACK of ACM (http://www.netlib.org/toms/). See example-17.
.fft(flag) number double FFT for 1D complex array. The first column of the caller is treated as the real part and the second as the image part. This function uses CCMATH library. The functions returns true for normal exit and or false otherwise. See example-18.
.inside(x, y) numbers double Checks if the point (x, y) is inside the polygon defined by the first two columns of caller (the first as x and the second as y). Returns true or false. See example-16.
.interpo1d(gx) matrix double Linear 1D interpolation of the caller to grid gx. Returns a double matrix of the same size as gx. The first column of the caller is treated as x and the second as y. See example-19.
.interpo2d(gx, gy) matrix, matrix double Linear 2D interpolation of the caller to grid gx and gy. Data in the caller are treated as on regular grids of 0 to nrow-1 and 0 to ncol-1. Returns a new matrix of double type. See example-19.
.interpo2d(gu, gv, gx, gy) matix, matrix, matrix, matrix double Linear 2D interpolation of the caller to grid gx and gy. Data in the caller are treated as on regular grids of gu and gv. Returns a new matrix of double type. See example-19.
.invert([flag]) string double In place inversion of a general real matrix. If the optional flag is "ps", the caller must be symmetric. If the optional flag is "ru", the caller is treated as upper right triangular matrix. This function uses CCMATH library. The function returns true for normal exit and or false if the caller is singular. See example-20.
.nllm(fname, par) string, matrix double

Nonlinear multiple parameter estimation of y=f(x, p1, p2, ...) using Levenberg Marquardt least squares fitting by Joachim Wuttke. It returns an array containing the number of try and the standard deviation of difference, i.e., sqrt(sum((y(i)-f(i))^2)/(n-1))). The caller matrix must have at two columns, of which the first will be treated as x and the second as y. The callback function named fname will be called with the first input being x matrix and the second being estimated paremeter matrix. It must return evaluated y as a matrix. See example-25.

.nlsim(fname, par[,low, high]) string, matrixes double This function is similar to nllm, but uses downhill simplex searching method. Optionally low and hight may be used to contrained par. See example-25.
.mlfit(A) matrix double Multi-linear fit of y = a0 + a1*x1 + a2*x2. The caller should be 1D matrix of size m and will contain coefficients on return. The design matrix A should be m by n matrix with m > n. The first column of A should be 1.0 and other column should contain data of x1, x2, and etc; and its first n rows will be modified to contain parameter variances. This function uses CCMATH library. It returns the estimated measurement of variance ssq/(m-n), where ssq is the sum of squared fit residuals. See example-24.
.svd()   double Conducts Simgular Value Decomposition (A = UDV') of the caller using the svduv() function of the CCMATH library. Returns an array with U in [0], D in [1], and V' in [2]. See example-23.
.spline(t, flag, a, b, n) numbers double Smoothing by spline interpolation. It returns a n by 2 matrix with the first column being x in the range of a to b and the second being smoothed y. The first column of the caller is treated as x and the second as y. Parameter t (0 to 1) is the tension factor. If flag > 0, the spline is open; otherwise is closed. This function uses CCMATH library. See example-22.
.cvsp(a, b, n) numbers double

Cross-validation spline interpolation. It returns a n by 2 matrix with the first column being x in the range of a to b and the second being smoothed y. The first column of the caller is treated as x and the second as y. This function uses the FORTRAN code from http://www.netlib.org/toms/642. See example-22.

.smooth(n[, f]) numbers double Distance weighted running average smoothing with half-windows size of n points. The weighting factor is 1/(1+((i-i0)^2+(j-j0)^2)^f). The default f-value is 1.0. Valuse less than -1.e35 or greater 1.e35 in the caller are treated as missing values. See example-21.
.sgsm(m, n) numbers double Savitzky-Golay smoothing of power m and half filter window width n for 1D series data. That is that the function tries to smooth the caller by polynomial fitting of y=a+bx+cx^2...x^m for every points.It is required that n > m, m > 1, and caller size > 2*n+1. The function uses CCMATH library. See example-21.