Contact: zeng @ zegraph.com Last update: 10 May 2011

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.

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. |

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. |

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. |

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. |

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. |

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. |

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. |

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. |

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. |