Skip to contents

Utility Functions

utility_functions.Rd

Utility functions for MARSS functions in the MARSS-package. These are not exported but can be accessed using the MARSS::: prefix.

Usage

vector.all.equal(x)
convert.model.mat(param.matrix)
fixed.free.to.formula(fixed,free,dim)
fully.spec.x(Z, R)
Imat(x)
is.blockdiag(x)
is.design(x, strict=TRUE, dim=NULL, zero.rows.ok=FALSE, zero.cols.ok=FALSE)
is.diagonal(x, na.rm=FALSE)
is.equaltri(x)
is.fixed(x, by.row=FALSE)
is.identity(x, dim=NULL)
is.timevarying(MLEobj)
is.solvable(A,y=NULL)
is.validvarcov(x, method="kem")
is.wholenumber(x, tol = .Machine$double.eps^0.5)
is.unitcircle(x, tol = .Machine$double.eps^0.5)
is.zero(x)
makediag(x, nrow=NA)
marssMODEL.to.list(MODELobj)
matrix.power(x, n)
mystrsplit(x)
parmat(MLEobj, elem = c("B", "U", "Q", "Z", "A", "R", "x0", "V0", "G", "H", "L"), 
    t = 1, dims = NULL, model.loc = "marss")
pinv(x)
pcholinv(x, chol = TRUE)
pchol(x) 
rwishart(nu, V)
sub3D(x,t=1)
takediag(x)
unvec(x, dim=NULL)
vec(x)

Arguments

x, A, y

A matrix (or vector for 'makediag' or string for 'mystrsplit'.).

Z, R

Z matrix and R matrix

na.rm

How to treat NAs in the block diag test.

dim, dims

Matrix dimensions. Some functions will take the vec of a matrix. In this case, the optional dim arg specifies the matrix dimensions.

fixed

A fixed matrix per the MARSS specification for fixed matrix syntax.

free

A free matrix per the MARSS specification for free matrix syntax.

nrow

Number of rows.

tol

Tolerance.

method

kem or BFGS. Used to add extra test for MARSSoptim().

t

The time index or third dimension of a 3D matrix

nu, V

Parameters of a Wishart distribution.

param.matrix

The list matrix version of a time-invariant MARSS model.

n

An integer for the power function.

zero.rows.ok, zero.cols.ok

Means the design matrix can have all zero rows or columns.

strict

Specifies whether the design matrix must be only 0s and 1s.

by.row

For is.fixed, reports whether is.fixed by row rather than for the whole matrix.

chol

For pcholinv, use chol2inv(chol()) if TRUE otherwise use solve().

MLEobj

A marssMLE object.

MODELobj

A marssMODEL object.

elem

The parameter matrix of a marss model to return.

model.loc

Whether to use the marss or model marssMODEL in the marssMLE object.

Details

  • is... tests for various matrix properties. isDiagonal() from the Matrix package is used to test numeric matrices for diagonality. is.diagonal() is only used to determine if list matrices (that combine numeric and character values) are diagonal. is.zero tests for near zeroness and gives TRUE for is.zero((.5-.3)-(.3-.1)) unlike ==0.

  • is.timevarying(MLEobj) returns a list of which parameters are time-varying.

  • vec(x) creates a column vector from a matrix per the standard vec math function.

  • unvec(c,dim) takes the vector c and creates a matrix with the specified dimensions.

  • Imat(nrow) returns the identity matrix of dimension nrow.

  • fixed.free.to.formula takes a fixed and free pair and constructs a list matrix (or array if time-varying) with formulas in each matrix element.

  • marssMODEL.to.list uses fixed.free.to.formula on all the elements of a marssMODEL to create a list that can be passed to MARSS() as the model argument.

  • convert.model.mat takes a list matrix with formulas in each element and converts to a fixed/free pair.

  • sub3D returns a 2D matrix after subsetting a 3D matrix on the third (time) dimension. Ensures that R always returns a matrix.

  • mystrsplit is a customized string splitter used by convert.model.mat.

  • rwishart generates random draws from a wishart distribution.

  • matrix.power is a faster way to get the n-th power of a matrix.

  • pinv is the pseudoinverse based on singular value decomposition PInv=UD^+V' where a diagonal matrix with non-zero diagonal values of D (from svd) replaced with 1/D.

  • pcholinv is the inverse based on the Cholesky decomposition but modified to allow 0s on the diagonal of x (with corresponding 0 row/column). These appear as 0 row/columns in the returned inverse.

  • pchol returns the Cholesky decomposition but modified to allow 0s on the diagonal of x (with corresponding 0 row/column).

  • is.solvable returns information on the solvability of the linear system y=Ax using the SVD decomposition.

  • vector.all.equal tests if the all the elements in a vector, matrix, or array are all equal. Works on list matrices too.

  • parmat constructs the parameter matrix with both the fixed and free values from the vectorized form in a marssMLE object. Users should use coef.

  • fully.spec.x returns a list with 0 and 1 showing which x are fully specified by data when R has zeros on the diagonal. Used by MARSSkfss().

Value

See above.

Author

Eli Holmes and Eric Ward, NOAA, Seattle, USA.