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.
double(a, b, c[, ...])	integers	Creates a matrix of double type and fill it with numbers.
double(M)	user	Creates a matrix of double type and fill it with numbers in matrix M.
Note: A matrix of char, unsigned char, shor, unsigned short, int unsigned int, and float can be create similarly by functions of char(), uchar(), short(), ushort(), int(), uint(), and float(); respectively.

Matrix Manipulation

Function	Parameters and Type	Acceptable Matrix Type	Remarks
.clone(src)	matrix	all	Resizes caller and copies data from src. The function may be used to transfer data from one type of matrix to another efficiently.
.delete(icol[, flag])	number, string	all	Deletes the ith column. Deletes the ith row if the optional flag is "r".
.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.
.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.
.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".
.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.
.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)	integer, integer	all	Resizes the matrix.
.reserve(n)	integer	all	Reserves memory for at least n data.
.reshape(nrow, ncol)	integer, integer	all	Reshapes the matrix.
.size()		all	Returns a array with the number of rows in [0], columns in [1], and total number of data in [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.
.trans()		all	Matrix transpose. In place transpose when row and column numbers are equal.
.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.

IO

Function	Parameters and Type	Acceptable Matrix Type	Remarks
.parse(irow, str)	number, string	all	Parses numbers in the string to the ith row.
.import(ptr)	user	all	Import data from the pointer.
.print([ format[, filename[, 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. Use "%d,", "%u,", or "%f," to produce CSV output. The default mode is appending. Use "w" to set the mode to overwrite.
.readtext(filename)	string	double	Returns data 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[, true/false]]	double	Reads data from a GSHHS file to the matrix 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 is true, the returned data are lines strips separated with lon =-360 and lat = -360 marking separation of line segments.
.readgshhs(filename, flag, callback)	string, string, string	double	Reads data from a GSHHS file to the matrix with the first column containing the longitude and the second the latitude and calls the callback function with four parameters of polygon boundary: west, east, south, and north.

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 abs(p).
pow(p1, p2)	matrix, matrix or number	float or double	Returns pow(p1, p2).
.rand([seed])	number	float or double	Fills the matrix with random numbers of 0 to 1.
.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.
.mean()		all	Returns the mean of elements in the matrix.
.stdev()		all	Returns the standard deviation, i.e., sqrt(sum(Ei- mean)/(n-1)), of elements in the matrix.
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
.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.
.clip(x0, y0, width, height)	numbers	double	Assuming data in the matrix are polygon vertices, the function clips the polygon by the rectangle with x0 and y0 being the bottom-left coordinate. Matrix row and column must be greater than 2 and 1, respectively
.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 and the triangulation is constrained by the polgyon.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/matrix, number/matrix	double	Checks if the point/points (px, py) is/are inside the polygon defined by the first two columns of caller (the first as x and the second as y). If px and py are numbers, the function returns true or false. If px and py are matrix, the fucntion returns a matrix of char type marking point indices with true or false.
.interpo(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.
.interpo(gx, gy)	matrix, matrix	double	Linear 2D interpolation of the caller to 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/).
.p2hybrid(Vs, Z, Zs, H)	matrixes	double	This special function interpolates data on pressure levels to hybrid grids and returns results in a matrix. The caller has data on NL pressure levels at NR latitude by NC longitude grids; Vs has the surface data; Z has the geopotential height data; Zs has surface height field; and H has the hybrid grid data, i.e., heights above ground.
.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.
.triangulate([refine, sphere])	number, true/false	double	Returns a matrix containing triangle vertex data from triangulation of polygon vertex data. If refine > 0, triangle edge length will be smaller than the number. If sphere=true, data are expected to be longitude and latitude in degree and edge length is calculated on the spherical surface with radius 1.

Unary Operators

Operator	Left Operand	Right Operand	Remark
-		char, short, int, float, or double	Returns the negative of the original. Element wise negate.
~	all		Returns the transpose of the original.
++	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.
|, &	matrix	matrix	Returns a matrix as the result of vertical/horizontal concatenation of two matrices.
<<, >>	matrix	integer	Left/right shift of matrix columns.
^	matrix	integer	Up shift of matrix rows.

Access by Index

Operator	Array keys	Remark
A[i]	integer	Returns the ith value.
A[I]	char matrix	Returns a matrix of the same type as A containing A's values where I's value is non-zero. I must be the same size as A.
A[i,j]	integers	Returns the value at the index.
A[*,j]	null, integer	Returns the ith column of A. The operator * in [] produces null to specify all rows.
A[i,*]	integer, null	Returns the ith row of A. The operator * in [] produces null to specify all columns.
A[i,I]	integer, char matrix	Returns a matrix of the same type as A containing A's values in the ith row where I's value is non-zero. I must be the same size as A's column.
A[I,j]	char matrix, integer	Returns a matrix of the same type as A containing A's values in the jth column where I's value is non-zero. I must be the same size as A's row.
A[*,I]	null, char matrix	Returns a matrix of the same type as A containing A's columns where I != 0. I must be the same size as A's column. The operator * in [] produces null to specify all rows.
A[I,*]	char matrix, null	Returns a matrix of the same type as A containing A's rows where I != 0. I must be the same size as A's row. The operator * in [] produces null to specify all columns.
A[*,range]	null or, array	Returns a matrix of the same type as A containing A's columns whose indices are given by the array. The operator * in [] produces null to specify all rows. The range is an array of two to three integers specifying the indices of begin, end, and step. The step is 1 if the array has only two numbers. The range may be given by a range expression; for example, A[*,1:11:2], A[*, 0:*], and so on. The range 0:* means from 0 to the last row.
A[range,*]	array, null	Returns a matrix of the same type as A containing A's rows whose indices are given by integers in the array. See A[*,range] for more explanations.
A[range, range]	array, array	Returns a matrix of the same type as A containing a block of A's values. See A[*, range] for more explanations.

Assignment by Index

Operator	Array keys	Right Operand	Remark
A[i] = b	integer	number	Sets the number to the ith element of matrix A
A[I] = v	char matrix	number	Sets the number to A's elements where I's values are non-zero. Matrix I must be the same size as A.
A[I] = V	char matrix	A-type matrix	Sets the 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 are the same size, indexing of A and V is the same; otherwise, the indexing of V is the accumulation of I's non-zero value counting.
A[i,j] = v	integers	number	Sets the value to A's element at the index.
A[*,j] = v	null, integer	number	Sets the number to the jth column of A.The operator * in [] produces null to specify all rows.
A[i,*] = v	integer, null	number	Sets the number to the ith row of A. The operator * in [] produces null to specify all columns.
A[*,j] = V	null,integer	A-type matrix	Sets V to the jth column of A. V must be the same size as A's column. The operator * in [] produces null to specify all rows.
A[i,*] = V	integer, null	A-type matrix	Sets V to the ith row of A. V must be the same size as A's row. The operator * in [] produces null to specify all columns.
A[i,I] = v	integer, char matrix	number	Similar to A[I] = v, but for row.
A[i,I] = V	integer, char matrix	A-type matrix	Similar to A[I] = V, but for row
A[I,j] = v	char matrix, integer	number	Similar to A[I] = v, but for column.
A[I,j] = V	char matrix, integer	A-type matrix	Similar to A[I] = V, but for column
A[*, I] = v	null, char matrix	number	Sets v to A's columns where I have non-zero values. I must be the same size as A's column. The operator * in [] produces null to specify all rows.
A[*, I] = V	null, char matrix	A-type matrix	Sets V to A's columns where I have non-zero values. V must be the same size as A. The operator * in [] produces null to specify all rows.
A[I,*] = v	char matrix, null	number	Sets v to A's rows where I have non-zero values. I must be the same size as A's row. The operator * in [] produces null to specify all columns.
A[I,*] = V	char matrix, null	A-type matrix	Sets v to A's rows where I have non-zero values. V must be the same size as A. The operator * in [] produces null to specify all columns.
A[*,range] = v	null, array	number	Sets the number to A's columns whose indices are specified by the array. The operator * in [] produces null to specify all rows. The range is an array of two to three integers specifying the indices of begin, end, and step. The step is 1 if the array has only two integer. The range may be given by a range expression; for example, A[*,1:11:2], A[*, 0:*], and so on. The range 0:* means from 0 to the last row.
A[range,*] = v	array, null	number	Sets the number to A's rows whose indices are specified by the array. See A[*,range] for more explanations.
A[range,*] = V	array, null	A-type matrix	Sets V to A's rows whose indices are specified by the array. V must have the same shape as B = A[range,*]. See A[*,range] for more explanations.
A[*,range] = V	null, array	A-type matrix	Sets V to A's columns whose indices are specified by the array. V must have the same shape as B = A[*,range]. See A[*,range] for more explanations.
A[range,range] = v	array, array	number	Sets v to A's elements whose indices are specified by the array. See A[*,range] for more explanations.
A[range,range] = V	array, array	number	Sets V to A's elements whose indices are specified by the array. See A[*,range] for more explanations.