Matrix (version 1.5-4)

fastMisc: “Low Level” Coercions and Methods

Description

“Semi-API” functions used internally by Matrix, often to bypass S4 dispatch and avoid the associated overhead. These are exported to provide this capability to expert users. Typical users should continue to rely on S4 generic functions to dispatch suitable methods, by calling, e.g., as(., <class>) for coercions.

Usage

.M2tri(from, ...)
.M2sym(from, ...)
.M2diag(from)
.m2dense(from, code, uplo = "U", diag = "N")
.m2sparse(from, code, uplo = "U", diag = "N")
.dense2m(from)
.sparse2m(from)
.dense2v(from)
.sparse2v(from)
.dense2kind(from, kind)
.sparse2kind(from, kind, drop0 = FALSE)
.dense2g(from, kind = ".")
.sparse2g(from)
.dense2sparse(from, repr = "C")
.sparse2dense(from, packed = FALSE)
.diag2dense(from, code, uplo = "U")
.diag2sparse(from, code, uplo = "U", drop0 = TRUE)
.CR2T(from)
.T2CR(from, Csparse = TRUE)
.CR2RC(from)
.tCR2RC(from)
.diag.dsC(x, Chx = Cholesky(x, LDL = TRUE), res.kind = "diag")
.solve.dgC.chol(a, b, check = TRUE)
.solve.dgC.lu  (a, b, tol = .Machine$double.eps, check = TRUE)
.solve.dgC.qr  (a, b, order = 3L, check = TRUE)

Arguments

from

a Matrix, matrix, or vector.

code

a string whose first three characters specify the class of the result. It should match the pattern "^[.nld](ge|tr|sy|tp|sp)" for .*2dense and "^[.nld][gts][CRT]" for .*2sparse, where "." in the first position is equivalent to "l" for logical arguments and "d" for numeric arguments.

kind

a string (".", "n", "l", or "d") specifying the “kind” of the result. "." indicates that the kind of from should be preserved. "n" indicates that the result should inherit from nMatrix (and so on).

uplo

a string ("U" or "L") indicating whether the result should store the upper or lower triangle of from. The elements of from in the opposite triangle are ignored.

diag

a string ("N" or "U") indicating whether the result (if triangular) should be formally nonunit or unit triangular. In the unit triangular case, the diagonal elements of from are ignored.

drop0

a logical. If TRUE, then nonstructural zeros in from are dropped.

repr

a string ("C", "R", or "T") specifying the storage of the result as CsparseMatrix, RsparseMatrix, or TsparseMatrix.

packed

a logical. If TRUE and from is formally triangular or symmetric, then the result will have “packed” storage and inherit from packedMatrix rather than unpackedMatrix.

Csparse

a logical. If FALSE, then the result will inherit from RsparseMatrix rather than CsparseMatrix.

...

optional arguments passed to isTriangular or isSymmetric.

x

a numeric sparse column-compressed "dgCMatrix".

Chx

optionally the Cholesky(x,..) decomposition of x; if Chx is specified, x is unneeded.

res.kind

a string, one of "trace", "sumLog", "prod", "min", "max", "range", "diag", "diagBack".

a

a numeric symmetric sparse column-compressed "dsCMatrix".

b

a vector or matrix, the “right hand side” \(b\) where we solve \(A x = b\) for \(x\).

check

a logical indicating if the first argument possibly first needs to be coerced to a dgCMatrix; should be set to false for speedup only if it is known to be already of the correct class.

tol

non-negative number, the tolerance for singularity checking in the LU decomposition.

order

only used for .solve.dgC.qr(); integer code in 0:3, determining which “symbolic Cholesky” method in ‘AMD’ is used; see lm.fit.sparse in package MatrixModels.

Details

Functions with names of the form .<A>2<B> implement coercions from virtual class A to the “nearest” non-virtual subclass of virtual class B, where the virtual classes are abbreviated as follows:

M

Matrix, matrix, or vector

m

matrix

v

vector

g

generalMatrix

C

CsparseMatrix

R

RsparseMatrix

T

TsparseMatrix

dense

denseMatrix

sparse

CsparseMatrix, RsparseMatrix, or TsparseMatrix

tri

triangularMatrix

sym

symmetricMatrix

diag

diagonalMatrix

Abbreviations should be seen as guides, rather than as an exact description of behaviour. For example, .m2dense and .m2sparse accept vectors in addition to matrices.

.CR2T and .T2CR coerce between TsparseMatrix and the union of CsparseMatrix and RsparseMatrix.

.CR2RC and .tCR2RC coerce between CsparseMatrix and RsparseMatrix. Conceptually, the latter performs the coercion on the transpose of its argument. That is, .tCR2RC(from) is equivalent to but much more efficient than .CR2RC(t(from)) and t(.CR2RC(from)).

.M2tri, .M2sym, and .M2diag can be seen as drop-in replacements for as(., "*Matrix"), but allowing users to pass optional arguments to the structure-checking functions.

.diag.dsC(x)

computes (or uses if Chx is specified) the \(LDL'\) Cholesky decomposition of x, returning diverse diagonal / determinant related statistics, for different result kinds, see res.kind in ‘Arguments’ above.

.solve.dgC.*()

Note that .solve.dgC.lu(a, ..) needs a square matrix a and it and .solve.dgC.qr(a, ..) solve sparse \(n \times n\) matrix systems directly.

.solve.dgC.qr() and .solve.dgC.chol() may both be used to solve sparse least squares problems.

Examples

D. <- diag(x = c(1, 1, 2, 3, 5, 8))
D.0 <- Diagonal(x = c(0, 0, 0, 3, 5, 8))
S. <- toeplitz(as.double(1:6))
C. <- new("dgCMatrix", Dim = c(3L, 4L),
          p = c(0L, 1L, 1L, 1L, 3L), i = c(1L, 0L, 2L), x = c(-8, 2, 3))

stopifnot(identical(.M2tri( D.), as(D., "triangularMatrix")),
          identical(.M2sym( D.), as(D., "symmetricMatrix")),
          identical(.M2diag(D.), as(D., "diagonalMatrix")),
          identical(.sparse2kind(C., "l"),
                    as(C., "lMatrix")),
          identical(.dense2kind(.sparse2dense(C.), "l"),
                    as(as(C., "denseMatrix"), "lMatrix")),
          identical(.diag2sparse(D.0, "ntC"),
                    .dense2sparse(.diag2dense(D.0, "ntp"), "C")),
          identical(.dense2g(.diag2dense(D.0, "dsy")),
                    .sparse2dense(.sparse2g(.diag2sparse(D.0, "dsT")))),
          identical(S.,
                    .sparse2m(.m2sparse(S., ".sR"))),
          identical(S. * lower.tri(S.) + diag(1, 6L),
                    .dense2m(.m2dense(S., ".tr", "L", "U"))),
          identical(.CR2RC(C.), .T2CR(.CR2T(C.), FALSE)),
          identical(.tCR2RC(C.), .CR2RC(t(C.))))

A <- tcrossprod(C.)/6 + Diagonal(3, 1/3); A[1,2] <- 3; A
stopifnot(exprs = {
    is.numeric( x. <- c(2.2, 0, -1.2) )
    all.equal(.solve.dgC.lu(A, c(1,0,0), check=FALSE),
              Matrix(x.))
    all.equal(x., .solve.dgC.qr(A, c(1,0,0), check=FALSE))
})

## Solving sparse least squares:

X <- rbind(A, Diagonal(3)) # design matrix X (for L.S.)
Xt <- t(X)                 # *transposed*  X (for L.S.)
(y <- drop(crossprod(Xt, 1:3)) + c(-1,1)/1000) # small rand.err.
str(solveCh <- .solve.dgC.chol(Xt, y, check=FALSE)) # Xt *is* dgC..
stopifnot(exprs = {
    all.equal(solveCh$coef, 1:3, tol = 1e-3)# rel.err ~ 1e-4
    all.equal(solveCh$coef, drop(solve(tcrossprod(Xt), Xt %*% y)))
    all.equal(solveCh$coef, .solve.dgC.qr(X, y, check=FALSE))
})