OpenMx (version 2.3.1)

mxMatrix: Create MxMatrix Object

Description

This function creates a new MxMatrix object.

Usage

mxMatrix(type = "Full", nrow = NA, ncol = NA, 
    free = FALSE, values = NA, labels = NA, lbound = NA, 
    ubound = NA, byrow = getOption('mxByrow'), dimnames = NA, name = NA, 
    condenseSlots=getOption('mxCondenseMatrixSlots'))

Arguments

type

A character string indicating the matrix type, where type indicates the range of values and equalities in the matrix. Must be one of: Diag, Full, Iden, Lower, Sdiag,

nrow

Integer; the desired number of rows. One or both of nrow and ncol is required when values, free, labels, lbound, and ubound arguments ar

ncol

Integer; the desired number of columns. One or both of nrow and ncol is required when values, free, labels, lbound, and ubound arguments

free

A vector or matrix of logicals for free parameter specification. A single TRUE or FALSE will set all allowable variables to free or fixed, respectively.

values

A vector or matrix of numeric starting values. By default, all values are set to zero.

labels

A vector or matrix of characters for variable label specification.

lbound

A vector or matrix of numeric lower bounds. Default bounds are specified with an NA.

ubound

A vector or matrix of numeric upper bounds. Default bounds are specified with an NA.

byrow

Logical; defaults to value of global option 'mxByRow'. If FALSE (default), the values, free, labels, lbound, and ubound

dimnames

List. The dimnames attribute for the matrix: a list of length 2 giving the row and column names respectively. An empty list is treated as NULL, and a list of length one as row names. The list can be named, and the list names will be used as names for the

name

An optional character string indicating the name of the MxMatrix object.

condenseSlots

Logical; defaults to value of global option 'mxByRow' If TRUE, then the resulting MxMatrix will "condense" its labels, free

Value

• Returns a new MxMatrix object, which consists of a values matrix of numeric starting values, a free matrix describing free parameter specification, a labels matrix of labels for the variable names, and lbound and ubound matrices of the lower and upper parameter bounds. This MxMatrix object can be used as an argument in the mxAlgebra(), mxBounds(), mxConstraint() and mxModel() functions.

Details

The mxMatrix function creates MxMatrix objects, which consist of five matrices and a type argument. The values matrix is made up of numeric elements whose usage and capabilities in other functions are defined by the free matrix. If an element is specified as a fixed parameter in the free matrix, then the element in the values matrix is treated as a constant value and cannot be altered or updated by an objective function when included in an mxRun function. If an element is specified as a free parameter in the free matrix, the element in the value matrix is considered a starting value and can be changed by an objective function when included in an mxRun function. Element labels beginning with 'data.' can be used if the MxMatrix is to be used in an MxModel object that has a raw dataset (i.e., an MxData object of type="raw"). Such a label instructs OpenMx to use a particular column of the raw dataset to fill in the value of that element. For historical reasons, the variable contained in that column is called a "definition variable." For example, if an MxMatrix element has the label 'data.x', then OpenMx will use the first value of the data column named "x" when evaluating the fitfunction for the first row, and will use the second value of column "x" when evaluating the fitfunction for the second row, and so on. After the call to mxRun(), the values for elements labeled with 'data.x' are returned as the value from the first (i.e., first before any automated sorting is done) element of column "x" in the data.

Objects created by the mxMatrix() function are of a specific type, which specifies the number and location of parameters in the labels matrix and the starting values in the values matrix. Input values, free, and labels matrices must be of appropriate shape and have appropriate values for the matrix type requested. Nine types of matrices are supported:

ll{ Diag matrices must be square, and only elements on the principal diagonal may be specified as free parameters or take non-zero values. All other elements are required to be fixed parameters with a value of 0. Full matrices may be either rectangular or square, and all elements in the matrix may be freely estimated. This type is the default for the mxMatrix() function. Iden matrices must be square, and consist of no free parameters. Matrices of this type have a value of 1 for all entries on the principal diagonal and the value 0 in all off-diagonal entries. Lower matrices must be square, with a value of 0 for all entries in the upper triangle and no free parameters in the upper triangle. Sdiag matrices must be square, with a value of 0 for all entries in the upper triangle and along the diagonal. No free parameters in the upper triangle or along the diagonal. Symm matrices must be square, and elements in the principle diagonal and lower triangular portion of the matrix may be free parameters of any value. Elements in the upper triangular portion of the matrix are constrained to be equal to those in the lower triangular portion, such that the value and parameter specificiation of the element in row i and column j is identical to to the value and specification of the element in row j and column i. Stand matrices are symmetric matrices (see 'Symm') with 1's along the main diagonal. Unit matrices may be either rectangular or square, and contain no free parameters. All elements in matrices of this type have a value of 1 for all elements. Zero matrices may be either rectangular or square, and contain no free parameters. All elements in matrices of this type have a value of 0 for all elements. }

When type is Lower or Symm, then the arguments to free, values, labels, lbound, or ubound may be vectors of length $N * (N + 1) / 2$, where N is the number of rows and columns of the matrix. When type is Sdiag or Stand, then the arguments to free, values, labels, lbound, or ubound may be vectors of length $N * (N - 1) / 2$.

References

The OpenMx User's guide can be found at http://openmx.psyc.virginia.edu/documentation.

See Also

MxMatrix for the S4 class created by mxMatrix. More information about the OpenMx package may be found here.

Examples

# Create a 3 x 3 identity matrix

idenMatrix <- mxMatrix(type = "Iden", nrow = 3, 
    ncol = 3, name = "I")

# Create a full 4 x 2 matrix from existing 
# value matrix with all free parameters

vals <- matrix(1:8, nrow = 4)
fullMatrix <- mxMatrix(type = "Full", values = vals, 
    free = TRUE, name = "foo")
 
# Create a 3 x 3 symmetric matrix with free off-
# diagonal parameters and starting values

symmMatrix <- mxMatrix(type = "Symm", nrow = 3, ncol = 3,
    free = c(FALSE, TRUE, TRUE, FALSE, TRUE, FALSE),
    values = c(1, .8, .8, 1, .8, 1),
    labels = c(NA, "free1", "free2", NA, "free3", NA),
    name = "bar")

# Create an mxMatrix from a character matrix.  All numbers are
# interpreted as fixed and non-numbers are interpreted as free
# parameters.

matrixFromChar <- function(inputm, name=NA) {
  inputmFixed <- suppressWarnings(matrix(
    as.numeric(inputm),nrow = nrow(inputm), ncol = ncol(inputm)))
  inputmCharacter <- inputm
  inputmCharacter[!is.na(inputmFixed)] <- NA
  mxMatrix(nrow=nrow(inputm), ncol=ncol(inputm),
           free=!is.na(inputmCharacter),
           values=inputmFixed,
           labels=inputmCharacter,
           dimnames=dimnames(inputm), name=name)
}