Contact: zeng  @  zegraph.com      Last update: 10 May 2011 ### 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 , the number of data in , and the element size in . .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 , columns in , and total number of data in . .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  and a matrix containing convex hull indices in . 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 , , and , 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 , D in , and V' in . .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.