Contact: zeng @ zegraph.com Last update: 20 January 2010

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

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

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

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

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

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

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

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

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

.convolve(G) | matrix | double | Returns a matrix containing the convolution of the caller with G, i.e., sum(Ci*Gj) for i=0 to n and j=0 to m, where m is G's size and n is C's size minus m. |

.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.e32 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. Valuse less than -1.e32 in the caller are treated as missing values. 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. |