Expand Matrix Factorizations

expand1 and expand2 construct matrix factors from objects specifying matrix factorizations. Such objects typically do not store the factors explicitly, employing instead a compact representation to save memory.

Usage

expand1(x, which, ...)
expand2(x, ...)

expand (x, ...)

Arguments

x: a matrix factorization, typically inheriting from virtual class MatrixFactorization.
which: a character string indicating a matrix factor.
...: further arguments passed to or from methods.

Value

expand1 returns an object inheriting from virtual class Matrix, representing the factor indicated by which, always without row and column names.

expand2 returns a list of factors, typically with names using conventional notation, as in list(L=, U=). The first and last factors get the row and column names of the factorized matrix, which are preserved in the Dimnames slot of x.

Details

Methods for expand are retained only for backwards compatibility with Matrix < 1.6-0. New code should use expand1 and expand2, whose methods provide more control and behave more consistently. Notably, expand2 obeys the rule that the product of the matrix factors in the returned list should reproduce (within some tolerance) the factorized matrix, including its dimnames.

Hence if x is a matrix and y is its factorization, then

    all.equal(as(x, "matrix"), as(Reduce(`%*%`, expand2(y)), "matrix"))

should in most cases return TRUE.

Methods

The following table lists methods for expand1 together with allowed values of argument which.

`class(x)`	`which`
`Schur`	`c("Q", "T", "Q.")`
`denseLU`	`c("P1", "P1.", "L", "U")`
`sparseLU`	`c("P1", "P1.", "P2", "P2.", "L", "U")`
`sparseQR`	`c("P1", "P1.", "P2", "P2.", "Q", "Q1", "R", "R1")`
`BunchKaufman`, `pBunchKaufman`	`c("U", "DU", "U.", "L", "DL", "L.")`
`Cholesky`, `pCholesky`	`c("P1", "P1.", "L1", "D", "L1.", "L", "L.")`
`CHMsimpl`, `CHMsimpl`	`c("P1", "P1.", "L1", "D", "L1.", "L", "L.")`

Methods for expand2 and expand are described below. Factor names and classes apply also to expand1.

expand2: signature(x = "CHMsimpl"): expands the factorization \(A = P_{1}' L_{1} D L_{1}' P_{1} = P_{1}' L L' P_{1}\) as list(P1., L1, D, L1., P1) (the default) or as list(P1., L, L., P1), depending on optional logical argument LDL. P1 and P1. are pMatrix, L1, L1., L, and L. are dtCMatrix, and D is a ddiMatrix.
expand2: signature(x = "CHMsuper"): as CHMsimpl, but the triangular factors are stored as dgCMatrix.
expand2: signature(x = "p?Cholesky"): expands the factorization \(A = L_{1} D L_{1}' = L L'\) as list(L1, D, L1.) (the default) or as list(L, L.), depending on optional logical argument LDL. L1, L1., L, and L. are dtrMatrix or dtpMatrix, and D is a ddiMatrix.
expand2: signature(x = "p?BunchKaufman"): expands the factorization \(A = U D_{U} U' = L D_{L} L'\) where \(U = \prod_{k = 1}^{b_{U}} P_{k} U_{k}\) and \(L = \prod_{k = 1}^{b_{L}} P_{k} L_{k}\) as list(U, DU, U.) or list(L, DL, L.), depending on x@uplo. If optional argument complete is TRUE, then an unnamed list giving the full expansion with \(2 b_{U} + 1\) or \(2 b_{L} + 1\) matrix factors is returned instead. \(P_{k}\) are represented as pMatrix, \(U_{k}\) and \(L_{k}\) are represented as dtCMatrix, and \(D_{U}\) and \(D_{L}\) are represented as dsCMatrix.
expand2: signature(x = "Schur"): expands the factorization \(A = Q T Q'\) as list(Q, T, Q.). Q and Q. are x@Q and t(x@Q) modulo Dimnames, and T is x@T.
expand2: signature(x = "sparseLU"): expands the factorization \(A = P_{1}' L U P_{2}'\) as list(P1., L, U, P2.). P1. and P2. are pMatrix, and L and U are dtCMatrix.
expand2: signature(x = "denseLU"): expands the factorization \(A = P_{1}' L U\) as list(P1., L, U). P1. is a pMatrix, and L and U are dtrMatrix if square and dgeMatrix otherwise.
expand2: signature(x = "sparseQR"): expands the factorization \(A = P_{1}' Q R P_{2}' = P_{1}' Q_{1} R_{1} P_{2}'\) as list(P1., Q, R, P2.) or list(P1., Q1, R1, P2.), depending on optional logical argument complete. P1. and P2. are pMatrix, Q and Q1 are dgeMatrix, R is a dgCMatrix, and R1 is a dtCMatrix.
expand: signature(x = "CHMfactor"): as expand2, but returning list(P, L). expand(x)[["P"]] and expand2(x)[["P1"]] represent the same permutation matrix \(P_{1}\) but have opposite margin slots and inverted perm slots. The components of expand(x) do not preserve x@Dimnames.
expand: signature(x = "sparseLU"): as expand2, but returning list(P, L, U, Q). expand(x)[["Q"]] and expand2(x)[["P2."]] represent the same permutation matrix \(P_{2}'\) but have opposite margin slots and inverted perm slots. expand(x)[["P"]] represents the permutation matrix \(P_{1}\) rather than its transpose \(P_{1}'\); it is expand2(x)[["P1."]] with an inverted perm slot. expand(x)[["L"]] and expand2(x)[["L"]] represent the same unit lower triangular matrix \(L\), but with diag slot equal to "N" and "U", respectively. expand(x)[["L"]] and expand(x)[["U"]] store the permuted first and second components of x@Dimnames in their Dimnames slots.
expand: signature(x = "denseLU"): as expand2, but returning list(L, U, P). expand(x)[["P"]] and expand2(x)[["P1."]] are identical modulo Dimnames. The components of expand(x) do not preserve x@Dimnames.

Examples

showMethods("expand1", inherited = FALSE)
#> Function: expand1 (package Matrix)
#> x="BunchKaufman"
#> x="CHMsimpl"
#> x="CHMsuper"
#> x="Cholesky"
#> x="Schur"
#> x="denseLU"
#> x="pBunchKaufman"
#> x="pCholesky"
#> x="sparseLU"
#> x="sparseQR"
#> 
showMethods("expand2", inherited = FALSE)
#> Function: expand2 (package Matrix)
#> x="BunchKaufman"
#> x="CHMsimpl"
#> x="CHMsuper"
#> x="Cholesky"
#> x="Schur"
#> x="denseLU"
#> x="pBunchKaufman"
#> x="pCholesky"
#> x="sparseLU"
#> x="sparseQR"
#> 
set.seed(0)

(A <- Matrix(rnorm(9L, 0, 10), 3L, 3L))
#> 3 x 3 Matrix of class "dgeMatrix"
#>           [,1]       [,2]        [,3]
#> [1,] 12.629543  12.724293 -9.28567035
#> [2,] -3.262334   4.146414 -2.94720447
#> [3,] 13.297993 -15.399500 -0.05767173
(lu.A <- lu(A))
#> LU factorization of Formal class 'denseLU' [package "Matrix"] with 4 slots
#>   ..@ x       : num [1:9] 13.298 0.95 -0.245 -15.4 27.35 ...
#>   ..@ perm    : int [1:3] 3 3 3
#>   ..@ Dim     : int [1:2] 3 3
#>   ..@ Dimnames:List of 2
#>   .. ..$ : NULL
#>   .. ..$ : NULL
(e.lu.A <- expand2(lu.A))
#> $P1.
#> 3 x 3 sparse Matrix of class "pMatrix"
#>           
#> [1,] . | .
#> [2,] . . |
#> [3,] | . .
#> 
#> $L
#> 3 x 3 Matrix of class "dtrMatrix" (unitriangular)
#>             [,1]        [,2]        [,3]
#> [1,]  1.00000000           .           .
#> [2,]  0.94973303  1.00000000           .
#> [3,] -0.24532527  0.01347465  1.00000000
#> 
#> $U
#> 3 x 3 Matrix of class "dtrMatrix"
#>              [,1]         [,2]         [,3]
#> [1,]  13.29799263 -15.39950042  -0.05767173
#> [2,]            .  27.34970743  -9.23089760
#> [3,]            .            .  -2.83696967
#> 
stopifnot(exprs = {
    is.list(e.lu.A)
    identical(names(e.lu.A), c("P1.", "L", "U"))
    all(sapply(e.lu.A, is, "Matrix"))
    all.equal(as(A, "matrix"), as(Reduce(`%*%`, e.lu.A), "matrix"))
})

## 'expand1' and 'expand2' give equivalent results modulo
## dimnames and representation of permutation matrices;
## see also function 'alt' in example("Cholesky-methods")
(a1 <- sapply(names(e.lu.A), expand1, x = lu.A, simplify = FALSE))
#> $P1.
#> 3 x 3 sparse Matrix of class "pMatrix"
#>           
#> [1,] . | .
#> [2,] . . |
#> [3,] | . .
#> 
#> $L
#> 3 x 3 Matrix of class "dtrMatrix" (unitriangular)
#>             [,1]        [,2]        [,3]
#> [1,]  1.00000000           .           .
#> [2,]  0.94973303  1.00000000           .
#> [3,] -0.24532527  0.01347465  1.00000000
#> 
#> $U
#> 3 x 3 Matrix of class "dtrMatrix"
#>              [,1]         [,2]         [,3]
#> [1,]  13.29799263 -15.39950042  -0.05767173
#> [2,]            .  27.34970743  -9.23089760
#> [3,]            .            .  -2.83696967
#> 
all.equal(a1, e.lu.A)
#> [1] "Component “P1.”: Attributes: < Component “margin”: Mean relative difference: 0.5 >"    
#> [2] "Component “P1.”: Attributes: < Component “perm”: Mean relative difference: 0.6666667 >"

## see help("denseLU-class") and others for more examples