.- help on ^matginv^, ^matcond^, ^matrank^, ^matorth^, ^matnull^, ^matnorm^, ^matmax^, ^matmin^, ^maxsum^, ^matrand^ (STB-39: dm49) .- Contents -------- ^matginv^ Moore-Penrose generalized-inverse ^matrank^ rank (number of independent rows/columns) ^matcond^ condition number ^matorth^ orthogonal basis of column space ^matnull^ orthogonal basis of the null space ^matnorm^ (L2-)norm ^matsum^ row/column/overall sum ^matmax^ row/column/overall maximum ^matmin^ row/column/overall minimum ^matrand^ random matrix All commands share a number of features: - they accept valid matrix expressions, such as the name of a matrix (A), the sum of two matrices (A+B), etc. - if names for output are not specified, the output is displayed. Matrix functions based on the singular value decomposition ---------------------------------------------------------- ^matginv^ matname [^, g^inv^(^name_matrix^)^ ^r^ank^(^name_scalar^)^ ^t^ol^(^#^)^ ^d^isplay ^f^ormat^(^fmt^)^] returns the Moore-Penrose (pseudo-) inverse of the matrix A in a matrix named in ^ginv^. The scalar ^rank^ returns the rank of A. If A is a n x m matrix, its MP-inverse B is m x n, and is the unique solution of (1) ABA = A, (2) BAB = B, (3) AB and BA are orthogonal projections. If A is square and regular, the MP-inverse is the normal matrix inverse. If A is square and singular, Stata's matrix function ^syminv()^ returns a g-inverse [check], a different kind of generalized matrix inverse. The row (column) names of the MP-inverse are the column (row) names of A. See Campbell & Meyer (1979) for details on the applications of g-inverse in statistics, difference equations, etc. ^matcond^ matname [^, c^ond^(^name_scalar^)^ ^d^isplay ^f^ormat^(^fmt^)^] returns the condition number (ratio of largest and smallest singular value) of a matrix in the scalar named in ^cond^. ^matrank^ matname [^, r^ank^(^name_scalar^)^ ^d^isplay ^t^ol^(^#^)^ ^f^ormat^(^fmt^)^] returns the rank (number of independent rows or columns) of a matrix in the scalar named in ^rank^. ^matorth^ matname [^, o^rth^(^name_matrix^)^ ^r^ank^(^name_scalar^)^ ^d^isplay ^t^ol^(^#^)^ ^f^ormat^(^fmt^)^] returns a orthogonal basis of the column space (image) of a matrix in the matrix named in ^orth^, and the rank of the matrix in the scalar named in ^rank^. ^matnull^ matname [^, n^ull^(^name_matrix^)^ ^r^ank^(^name_scalar^)^ ^d^isplay ^t^ol^(^#^)^ ^f^ormat^(^fmt^)^] returns a orthogonal basis of the null space of a matrix in the matrix named in ^null^, and the rank of the matrix in the scalar named in ^rank^. Other matrix functions ---------------------- ^matnorm^ matname [^, n^orm^(^name_scalar^)^ ^d^isplay ^f^ormat^(^fmt^)^] returns the L2-norm of a matrix in a scalar named in ^norm^. ^matmax^ matname [^, r^ow^(^rmatname^)^ ^c^olumn^(^cmatname^)^ ^a^ll^(^amatname^)^ ^d^isplay ^f^ormat^(^fmt^)^] ^matmin^ matname [^, r^ow^(^rmatname^)^ ^c^olumn^(^cmatname^)^ ^a^ll^(^amatname^)^ ^d^isplay ^f^ormat^(^fmt^)^] ^matsum^ matname [^, r^ow^(^rmatname^)^ ^c^olumn^(^cmatname^)^ ^a^ll^(^amatname^)^ ^d^isplay ^f^ormat^(^fmt^)^] computes and/or displays the row-wise, column-wise and over-all maximum, minimum, and sum over the elements of a matrix. More than one operator may be specified simultaneously. These commands default to the column-wise operators. ^matrand^ n m matname [^,^ { ^n^ormal^(^mn var^)^ | ^u^niform^(^lo hi^)^ | ^c^onst^(^lo hi^)^ } ^d^isplay ^f^ormat^(^fmt^)^] creates a n-x-m matrix A (overwriting the named matrix if it already exists) with elements generated independently from : ^normal^ distribution with mean mn and variance var ^uniform^ distribution on the interval [lo hi] ^const^ distribution on the costants lo, lo+1, ..., hi If no distribution is specified, ^matrand^ defaults to u(0 1). Note that A is not optional. Options ------- ^display^ specifies that the computed results are displayed. All programs that are described here, display the results if output names for matrices (scalars) are not specified. ^format(^fmt^)^ specifies a format (e.g., %10.5f, %10.0g) to display matrix results. ^tol(^#^)^ specifies the tolerance for deciding what singular values are `really' zero. See below for details. You typically don't have to set this option. Numerical details ----------------- The main tool used by these programs is the singular value decomposition of the matrix A = USV', where U and V are (column) orthonormal and S is diagonal with positive entries. We heavily lean on Stata's singular value decomposition command (^matrix svd^). Following Matlab, we compute the ^rank^ r(A) of A as the number of singular values that exceed tol, where tol = max(singular values of A) * size(A) * eps where eps is a measure of machine precision. This is also used in computing the MP-inverse (see below) and the column orthogonalization. The ^condition number^ c(A) of A as c(A) = max(singular values of A) / min(singular values of A) If the minimum of the singular values is 0, the condition number is defined as missing. The ^MP-inverse^ of a matrix is computed as V*IS*U, where IS is a diagonal matrix with the reciprocal of the singular values S, or 0 if the singular values are smaller than tol (see above). Stata can only compute the "economy" solution of the SVD, and hence the svd cannot be used directly to obtain the null space of a matrix. To compute the null space of a matrix we therefore use the fact that the null space of matrix A equals the null space of A'A. The latter can be obtained from the spectral decomposition of A'A, using the tolerance to decide what eigenvectors span the null space. The user is warned that this procedure is not numerically optimal for ill-conditioned problems, i.e., for matrices A with a singular value `close' to 0. Examples -------- . ^matrand 5 3 A^ (random matrix A, idd U(0,1)) . ^matrand 5 7 B, n(0 10)^ (random matrix A, iid N(0,1)) . ^matginv A^ (display Moore-Penrose inverse) . ^matginv A, ginv(AI)^ (return Moore-Penrose inverse) . ^matcond A+B^ (display condition number of A+B) . ^matrank A, rank(ra)^ (return rank of matrix A) . ^matsum A, row(rsumA)^ (return row-wise sum of A) Known problems -------------- We would like matmin A[2,.] to return the minimum of the 2nd row of A. The parsing of matmin, and similarly all other matrix programs, is not smart enough to recognize that the comma is part of the matrix expression, and does not delimit the options. Author ------ Jeroen Weesie Utrecht University Netherlands email: weesie@@weesie.fsw.ruu.nl References ---------- Campbell, S. L. and C. D. Meyer, Jr. (1979) Generalized Inverses of Linear Transformations. London: Pitman. The MathWorks, Matlab Reference manual. V4. Cambridge, MA: The Mathworks Inc. Also see -------- STB: STB-39 dm49 Manual: ^[R] matrix^ On-line: help for @matrix@, @varfunc@