3.7.5.41 Mat

LabTalk Object Type:

External Object

The mat object handles many operations on matrices including conversion between worksheets and matrices, mathematical operations such as inverse, transpose, computing the X and Y projections, multiplication, and data preparation such as gridding.

Please see the m2w, w2m, minverse,mexpand X-Functions for Matrix to Worksheet conversion, Worksheet to Matrix conversion, Inversion of a Matrix and Matrix expansion.

Note: The mat object does not contain matrix sheet properties. Properties for sheets such as sheet dimensions (wks.ncols, wks.nrows), sheet name (wks.name$), and number of objects in a matrixsheet (wks.nmats) are controlled by the wks object. Also view the section on common properties and methods of external objects.

Besides controlling matrixsheets using this mat object and the wks object, you can also use matrix related X-Functions, such as mdim, and msetvalue, to change matrix dimension and set cell values.

Properties:

Property Access Description
mat.edgeView.xeCol$ Read/write
string 		Used with the mat.edgeview( ) method. This is the X column in the mat.edgeview.xeWksName$ worksheet.
mat.edgeView.xeWksName$ Read/write
string 		Used with the mat.edgeview( ) method. This is the worksheet where the X projection is stored.
mat.edgeView.yeCol$ Read/write
string 		Used with the mat.edgeview( ) method. This is the worksheet where the Y projection is stored.
mat.edgeView.yeWksName$ Read/write
string 		Used with the mat.edgeview( ) method. This is the worksheet where the Y projection is stored.
mat.edgeView.zxeCol$ Read/write
string 		Used with the mat.edgeview( ) method. This is the Y column in the mat.edgeview.xeWksName$ worksheet. This column contains the maximum Y along that X.
mat.edgeView.zxsCol$ Read/write
string 		Used with the mat.edgeview( ) method. This is a column in the mat.edgeview.xeWksName$ worksheet. This column contains the sum of all Ys along that X.
mat.edgeView.zyeCol$ Read/write
string 		Used with the mat.edgeview( ) method. This is the X column in the mat.edgeview.xeWksName$ worksheet. This column contains the maximum X along that Y.
mat.edgeView.zysCol$ Read/write
string 		Used with the mat.edgeview( ) method. This is a column in the mat.edgeview.xeWksName$ worksheet. This column contains the sum of all Xs along that Y.
mat.exp2m.cols Read/write
numeric 		When converting a worksheet to a matrix using the mat.exp2m( ) method, this property value controls the number of columns in the matrix. The number of columns in the matrix is determined by the number of columns in the worksheet multiplied by this property value.
mat.expand.col Read/write
numeric 		Column expansion factor when using the mat.expand( ) method.
mat.expand.row Read/write
numeric 		Row expansion factor when using the mat.expand( ) method.
mat.grid.average Read/write, numeric Used in correlation gridding. Average all points in a grid unit: 1 = enable, 0 = disable.
mat.grid.dCluster Read/write
numeric 		Used in correlation gridding. When mat.grid.average is enabled, this property represents the minimum number of cluster points used in a given direction. The maximum value allowed is 5 and the minimum is 3.
mat.grid.gcSize Read/write
numeric 		Size of a grid unit in the X direction. Choosing a smaller size gives better results but increases calculation time.
mat.grid.grSize Read/write
numeric 		Size of a grid unit in the Y direction. Choosing a smaller size gives better results but increases the calculation time.
mat.grid.maxSubpts Read/write
numeric 		The maximum number of points (raw data or grid units) allowed in gridding.
mat.grid.maxUseAll Read/write
numeric 		Used in correlation gridding. When the total number of data points is less than this value, all the data points are used in gridding. This speeds up the gridding process when the total number of points is less than 64 (default value).
mat.grid.minQuadra Read/write
numeric 		Used in correlation gridding. The minimum number of points used in a given direction in correlation gridding when mat.grid.average is disabled. The maximum value is 5 and the minimum value is 3.
mat.grid.nMatCols Read/write
numeric 		Number of columns in the matrix after gridding.
mat.grid.nMatRows Read/write
numeric 		Number of rows in the matrix after gridding.
mat.grid.radius Read/write
numeric 		If the distance between a data point and the gridding point is larger than this value, the contribution of this data point is set to a minimal value.
mat.grid.rule Read/write
numeric 		Used in weighted average gridding. This parameter determines the weight as a function of the distance between a data point and the gridding point: 1 = linear, 2 = power, 3 = logarithmic, 4 = exponential.
mat.grid.smooth Read/write
numeric 		Used in correlation gridding. Smaller values give smoother results.
mat.interpolate Read/write
numeric 		Control whether or not interpolation is used with the mat.profile( ) and the mat.segment( ) methods: 0 = no interpolation, non-zero = interpolation.
mat.interpolatePts Read/write
numeric 		Number of points to use for interpolating with the mat.profile( ) and the mat.segment( ) methods. If set to -1, then the matrix number of columns or rows is used.
mat.matName$ Read/write
string 		Name of the active matrix. Specify the active matrix before executing a mat object method.
mat.profile.angle Read/write
numeric 		Used with the mat.profile( ) method - for a profile along a line with a preset slope. This is the angle with X axis (in radians). The default value is PI/4.
mat.profile.hSection Read/write
numeric 		Used with the mat.profile( ) method. This is the number of points in the horizontal profile.
mat.profile.hwksName$ Read/write
string 		Used with the mat.profile( ) method. This is the worksheet that stores the horizontal profile.
mat.profile.hXCol Read/write
numeric 		Used with the mat.profile( ) method. This is the worksheet column that stores the X horizontal profile.
mat.profile.hZCol Read/write
numeric 		Used with the mat.profile( ) method. This is the worksheet column that stores the Z horizontal profile.
mat.profile.sSection Read/write
numeric 		Used with the mat.profile( ) method. This is the number of points in the slanted profile.
mat.profile.vSection Read/write
numeric 		Used with the mat.profile( ) method. This is the number of points in the vertical profile.
mat.profile.vWksName$ Read/write
string 		Used with the mat.profile( ) method. This is the worksheet that stores the vertical profile.
mat.profile.vYCol Read/write
numeric 		Used with the mat.profile( ) method. This is the worksheet column that stores the Y vertical profile.
mat.profile.vZCol Read/write
numeric 		Used with the mat.profile( ) method. This is the worksheet column that stores the Z vertical profile.
mat.res, mat.resolution Read/write
numeric 		When converting a regular worksheet to a matrix, small variations in the data are allowed. The tolerance for these variations is determined by this property. The default value is 10, which allows up to a 10% variation in the step size in X or Y. If you have very small variations of data, the default value may be too large (the conversion would still go through). Likewise, if you have very large fluctuations in your data, then the default value could be too small (the conversion will fail). Calculate a value appropriate for your data using: (maximum variation from mean step size * 100 / mean step size)
mat.shrink.col Read/write
numeric 		Column shrinkage factor when using the mat.shrink( ) method.
mat.shrink.row Read/write
numeric 		Row shrinkage factor when using the mat.shrink( ) method.
mat.type Read/write
numeric 		Used in conversion from a matrix to a worksheet in the mat.m2xyz( ) method. 0 = X column first, 1 = Y column first.
mat.wksName$ Read/write
string 		Name of the active worksheet. (Used with the mat.profile( ) method. This is the worksheet that stores the slanted profile.)
mat.xCol Read/write
numeric 		The X column number in the worksheet. (Used with the mat.profile( ) method. This is the worksheet column that stores the X slanted profile.)
mat.yCol Read/write
numeric 		The Y column number in the worksheet. (Used with the mat.profile( ) method. This is the worksheet column that stores the Y slanted profile.)
mat.zCol Read/write
numeric 		The Z column number in the worksheet. (Used with the mat.profile( ) method. This is the worksheet column that stores the Z slanted profile.)

Methods:

Method Description
mat.edgeView( ) Plot the maximum values of X along a given Y, and Y along a given X. You can also specify a column (optional) to compute and store the sum of all Y along a particular X and the sum of all X along a particular Y.
mat.exp2m( ) Expand all columns of the active worksheet (mat.wksName$) by a factor and convert it to a matrix (mat.matName$). The expansion factor is determined by mat.exp2m.cols. For example, if the active worksheet has 3 columns and mat.exp2m.cols = 2, the resultant matrix will have 6 columns.
mat.expand( ) Expand the active matrix (mat.matName$). The expansion factor is determined by mat.expand.row and mat.expand.col.
mat.grid(coo) Correlation gridding.
mat.grid(ave) Weighted average gridding.
mat.grid(check) Check and set the consistency and validity of gridding smoothness vs. minimum points per direction.
mat.integrate([varName]) Integrate the matrix by starting from zero. If varName is included, the integration result is stored in varName. If not included, the integration result is output to the Script window.
mat.inv( ) Inverse the active matrix (mat.matName$).
mat.m2w( ) Convert the active matrix (mat.matName$) to a worksheet (mat.wksName$) by the columns and rows directly. The worksheet looks exactly like the original matrix, but the X Y coordinate mapping information is lost.
mat.m2xyz( ) Convert the active matrix (mat.matName$) to a worksheet (mat.wksName$). This method creates a worksheet with X, Y and Z columns. The cell values of the matrix are converted to a Z column. The corresponding X and Y column values in the worksheet are set by the X and Y coordinate mapping information in the matrix.
mat.multiply(matrix1, matrix2) Multiply matrix1 by matrix2. Mat.matName$ stores the name of the target matrix. If this matrix is matrix1 or matrix2, the input matrix is overwritten.
mat.profile(x1, y1) Provides three profiles:
  1. The horizontal profile y = y1.
  2. The vertical profile x = x1.
  3. The profile along a line with a preset slope passing through (x1, y1). Set the angle with the X axis in radians using the mat.profile.angle property. The default angle is PI/4.

The profiles are stored in the following worksheets:

  1. Horizontal: mat.profile.hwksname, mat.profile.hXcol, mat.profile.hZcol.
  2. Vertical: mat.profile.vwksname, mat.profile.vYcol, mat.profile.vZcol.
  3. Slanted: mat.wksname, mat.xcol, mat.ycol, mat.zcol.

The number of points in each profile can be accessed from mat.profile.hsection, mat.profile.vsection, and mat.profile.ssection. Specify use of interpolation with the mat.interpolate and the mat.interpolatePts properties.

mat.segment(x1, y1, x2, y2) Find the profile between (x1, y1) and (x2, y2). The results are written to mat.wksName$. Control whether interpolation is used with the mat.interpolate and the mat.interpolatePts properties.
mat.shrink( ) Shrink the active matrix (mat.matName$). The shrinkage factor is determined by mat.shrink.row and mat.shrink.col.
mat.w2m( ) Convert the active worksheet (mat.wksName$) to a matrix (mat.matName$) by the columns and rows directly. The matrix looks exactly like the original worksheet.
mat.xyz2m( ) Convert the active worksheet (mat.wksName$) to a matrix (mat.matName$). This method creates a matrix with cell values from the Z column. The X and Y coordinate mapping information in the matrix is from the corresponding X and Y column values in the worksheet.

Examples:

This script converts a matrix to a worksheet using the matrix to regular XYZ format. The mat.type property determines the type of data transfer from the worksheet to the matrix. When mat.type = 0 or not specified (default), data copying follows the "X First" rule, i.e., the X axis of the matrix is the independent axis. When mat.type is any integer greater than zero, data copying follows the "Y First" rule. 

 //Create a matrix
win -t mat;
//Set the dimensions to 10X10
matrix -ps DIM 10 10;
//Fill the cells of the matrix
(%H) = Data(1,100,1);
mat.matname$ = %H;
//Create an XYZ worksheet
win -t wks xyz;
mat.wksname$ = %H;
mat.type = 1;
//Convert the matrix to regular XYZ format
mat.m2xyz();

Note: %H is used only if the name of the window to be specified is the active window. Otherwise, specify the name of the window enclosed in double quotes, such as "data1" and "matrix1".

This script converts a worksheet to a matrix using the regular XYZ to matrix format. X, Y, and Z columns for the matrix are specified within the worksheet. The X column contains the independent data. The Y column contains the dependent data. The Z column contains data that are to be placed in the corresponding cells in the matrix. 

mat.wksname$ = %H;
mat.xcol = 1;
mat.ycol = 2;
mat.zcol = 3;
//Create a new matrix
win -t mat;
mat.matname$ = %H;
//Convert the XYZ data to a matrix
mat.xyz2m();

This script converts a matrix to a worksheet using the column-row format. The resultant worksheet is exactly the same as the matrix. 

mat.matname$ = %H;
//Create a new worksheet
win -t wks;
mat.wksname$ = %H;
//Convert the matrix directly to a worksheet
mat.m2W();

This script converts a worksheet to a matrix by correlation gridding. 

mat.grid.nmatcols = 32;
mat.grid.nmatrows = 32;
mat.grid.grsize = 4;
mat.grid.gcsize = 4;
mat.grid.average = 0;
mat.grid.minquadra = 3;
mat.grid.radius = 2;
mat.grid.dcluster = 3;
mat.grid.smooth = .8;
mat.xcol = 1;
mat.ycol = 2;
mat.zcol = 3;
mat.wksname$ = %H;
sum(wcol(mat.xcol));
xmax = sum.max;
xmin = sum.min;
limit -r xmin xmax 8;
sum(wcol(mat.ycol));
ymax = sum.max;
ymin = sum.min;
limit -r ymin ymax 8;
win -t m;
matrix -ps x xmin xmax;
matrix -ps y ymin ymax;
mat.matname$ = %H;
mat.grid(coo);
English | Deutsch | 日本語