Matrix Library

The library handles row-major data arrays of char, unsigned char, short, unsigned short, int, insigned int, float, and double.

Functions Operate on Whole Matrix

Function Parameters and Type Acceptable Matrix Type Remarks
matrix(typename[, nrow, ncol) string, number, number. all Creates a matrix. The typename can be char, uchar, short, ushort, int, uint, float, or double.
matrix(a, b[, c...]) numbers all Creates a double matrix with one row and columns of the number of parameters.
:clone(src) matrix all Resizes caller and copies data from src. The function can be used to transfer data from one type of matrix to another efficiently.
:confine(min, max) number, number all (over flow un-checked) Confines elements of the matrix in the range.
:fill(initial, step) number, number all (over flow un-checked) Fills the matrix with numbers with the first = initial, the second = initial + step, and etc.
:min()   all Returns the smallest number in the the matrix.
:max()   all Returns the largest number in the matrix.
:sum()   all Returns the sum of elements in the matrix.
:print([ format[, filename[, mode]]]) string, string, string all Prints matrix data to stdout or to the file. The default mode is appending. Use "w" to set the mode to overwrite.
: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.
:ptr([offset])   all Returns a array with a user object containing matrix pointer in [0], the number of data in [1], and the element size in [2].
:resize(nrow, ncol) number, number all Resizes the matrix.
:reshape(nrow, ncol) number, number all Reshapes the matrix.
:rand([seed]) number float or double Fills the matrix with random numbers of 0 to 1.
:readtext(filename) string float and double Returns a float or double type matrix with rows containing numbers converted from number-only lines of string in the file.
:readgshhs(filename, flag[, west, east, south, north[, strip]]) string, string[, number, number, number, number[, strip]] float and double Reads data from a GSHHS file and returns a float or double array of n by 2 with the first column containing the longitude and the second the latitude. The flag must be "land", "lake", "island", or "pond". The range must satisfies west >= 0, west < east, east <= 360, south < north, south >= -90, and north <= 90. If the argument strip > 0, the returned data are lines strips separated by lon =-360 and lat = -360.
:size()   all Returns a array with the number of rows in [0], columns in [1], and total number of data in [2].
:trans()   all Matrix transpose.
:join(src, missing) matrix, number all Returns a matrix as the join of the caller and the source according to their first column. In the new matrix, the first few columns contains a copy of the caller, and rest columns are fill with src if there is a match between their first columns or filled with the missing value otherwise. The caller and src should be sorted by ascending order according to their first column.

Functions Operate on Element-Row-Column

Function Parameters and Type Acceptable Matrix Type Remarks
:at(i) number all Returns the ith element value.
:at(irow, jcol) number, number all Returns the element value at (irow, icol).
:at(irow, icol, val) number, number, number all Sets val to the element at (irow, icol).
:at(idx) matrix (char type) all Extracts elements at indices where idx = 1 and returns a matrix of the same type as mat
:at(idx, val) matrix (char type), number or matrix all Sets val to elements at indices where idx = 1. If val is a matrix, it must be the same type and size as mat, or the size must be larger than the number of none-zero elements of idx.
:block(i, nrow, j, ncol) number, number, number, number all Returns a matrix having a block of data in mat starting at the ith row and the jth column.
:block(i, j, src) number, number, matrix all Replaces a block of data in the caller by data in src, starting at the ith row and the jth column. The size of src determines the numbers of row and column to replace.
:col(i) number all Extract the ith column and returns a matrix.
:col(i, val) number, number of matrix all Sets val to the ith column of the caller. If val is a matrix, it must be the same type as the caller and its number of data must equal the number of rows of the caller.
:row(i) number all Extract the ith row and returns a matrix.
:row(i, val) number, number of matrix all Sets val to the ith row of the caller. If val is a matrix, it must be the same type as the caller and its number of data must equal the number of columns of the caller.
:delete(icol[, flag]) number, string all Deletes the ith column. Deletes the ith row if the optional flag is "r".
:flip([flag]) string all Flips columns by default. Flips rows if the optional flag is "r".
:insert(icol, src[, flag]) number, number or matrix, string all Inserts the src number or matrix to the caller before the ith column. If src is a matrix, it must be the same type as the caller and its number of data must equal the number of rows of the caller. Insertion operates on row if the optional flag is "r".
:select(start, step[, flag]) number, number, string all Selects columns of mat and returns a matrix. Selects rows if the optional flag is "r".
:swap(i, j[, flag]) number, number, string all Swaps the i-jth columns by default. Swaps rows if the optional flag is "r".
:shift(n[, flag]) number, string al Shifts matrix columns to the right (n > 0) or left (n < 0) by n columns. Shifts rows if the optional flag if "r",
: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.
:unique([flag]) [number] all Makes the matrix a unique n by 1 matrix. If flag > 0, sort in ascending order (default), otherwise in descending order.
:parse(irow, str) number, string all Parses numbers in the string to the ith row.

Math

Function Parameters and Type Acceptable Matrix Type Remarks
cos(p) matrix or number float or double Returns cos(p) if p is a number; otherwise applies cos to all elements of the matrix.
acos(p) matrix or number float or double Returns acos(p).
cosh(p) matrix or number float or double Returns cosh(p).
sin(p) matrix or number float or double Returns sin(p).
asin(p) matrix or number float or double Returns asin(p).
sinh(p) matrix or number float or double Returns sinh(p).
tan(p) matrix or number float or double Returns tan(p).
atan(p) matrix or number float or double Returns atan(p).
atan2(p1, p2) matrix, matrix or number float or double Returns atan2(p1, p2).
tanh(p) matrix or number float or double Returns tanh(p).
sqrt(p) matrix or number float or double Returns sqrt(p).
exp(p) matrix or number float or double Returns exp(p).
log(p) matrix or number float or double Returns log(p).
log10(p) matrix or number float or double Returns log10(p).
ceil(p) matrix or number float or double Returns ceil(p).
floor(p) matrix or number float or double Returns floor(p).
abs(p) matrix or number float or double Returns fabs(p).
pow(p1, p2) matrix, matrix or number float or double Returns pow(p1, p2).
cal2jul(p) matrix or number float or double Returns a float or double matrix containing Julian date and time converted from Gregorian calendar year, month, day, hour, minute, second in the first to the sixth columns of the input, which must have at least three columns. Missing hour, minute, and second are treated as zero.
jul2cal(p) matrix or number float or double Returns a float or double matrix with the year, month, day, hour, minute, second in the first to the sixth columns.

Numeric

Function Parameters and Type Acceptable Matrix Type Remarks
:delaunay()   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], the number of triangles in [1], a matrix containing convex hull indices in [2], and the number of points of the convex hull in [3]. This function uses the STRIPACK of ACM (http://www.netlib.org/toms/).
: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.
:inside(px, py) number, number double Returns true if the point (px, py) is inside the polygon defined by the first two columns of mat (the first as x and the second as y); otherwise returns false.
:interpo(gx) matrix double Linear 1D interpolation of the caller on 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.
:interpo(gx, gy) matrix, matrix double Linear 2D interpolation of the caller on grid gx and gy. Data in the caller are treated as on grids of 0 to nrow-1 and 0 to ncol-1. Returns a new matrix of double type.
:interpo(gx, gy, flag) matrix, matrix, number double Interpolates data at random points on a plane (the caller has three columns) or spherical surface (the caller has four columns) to regular grids of gx and gy. Returns a new matrix of double type. If flag=0, the interpolation is linear; otherwise the interpolation is once-continuously differentiable. This function uses the STRIPACK and SRFPACK of ACM (http://www.netlib.org/toms/).
: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.
:nlfit(f, par[, lb, ub]) string, matrix, matrix, matrix double Nonlinear multiple parameter estimation of y=f(x, p1, p2, ...). The caller matrix must have at least two columns, of which the first will be treated as x and the second as y. The caller matrix must be sorted by increment order of x. The number of initial parameters in par must be be <= 20. Optionally, you may provide lb and ub, which must be the same size as par, to constrain parameters within the lower and upper boundary. This function uses nqslq functions of the CCMATH library for 100 times and returns whenever the sum of squared residuals (ssq = (y[i] - f(x[i],par))^2) is < 1.e-15, or two consecutive ssqs are equal, or ssq < 0 (indicating error of singular matrix). The returned array contains the number of calls, the ssq, and the parameter variance matrix in [0], [1], and [2], respectively.
:mlfit(A) matrix double Multi-linear fit of y = a0 + a1*x1 + a2*x2... It returns the estimated measurement of variance ssq/(m-n), where ssq is the sum of squared fit residuals, m is the number of y data and n is the number of parameters. The caller should contain y values and will be modified to have estimated parameters. The first column of design matrix 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.
: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].
:spline(t, flag, a, b, n) numbers double Smoothing by spline interpolation. It returns a matrix of n by 1 in the range of a to b. 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.
:cvspline(a, b, n) numbers double Cross-validation spline interpolation. It returns a matrix of n by 1 in the range of a to b. 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
:smooth(n[, f]) numbers double Distance weighted running average smoothing. The weighting factor is 1/(1+((i-i0)^2+(j-j0)^2)^f). The default f-value is 1.0.
:sgsmooth(m, n) numbers double Savitzky-Golay smoothing of power m and filter window width n for 1D series data. This function uses CCMATH library, but refer to http://www.library.cornell.edu/nr/bookcpdf.html for technical details.

Unary Operators

Operator Left Operand Right Operand Remark
-   char, short, int, float, or double Returns the negative of the original. Element wise negate.
++ all   Element wise increment by 1.
-- all   Element wise decrement by 1.

Binary Operators

Operator Left Operand Right Operand Remark
+, -, *, /, % number or matrix number or matrix Returns a matrix. Element wise add, subtract, multiply, divide, or mod.
+=, -=, *=, /=, %= matrix matrix or number The more efficient equivalent of +, -, *, /, and %
==, !=, >, >=, <, <= matrix or number matrix or number Element wise comparison. Returns a char-type matrix with element of 1 for true and 0 for false.
&&, || char matrix char matrix Logical and/or comparison. Returns a char-type matrix with element of 1 for true and 0 for false.