# pack-methods: Representation of Packed and Unpacked Dense Matrices In Matrix: Sparse and Dense Matrix Classes and Methods

 pack-methods R Documentation

## Representation of Packed and Unpacked Dense Matrices

### Description

`pack()` coerces dense symmetric and dense triangular matrices from unpacked format (storing the full matrix) to packed format (storing only one of the upper and lower triangles). `unpack()` performs the reverse coercion. The two formats are formalized by the virtual classes `"packedMatrix"` and `"unpackedMatrix"`.

### Usage

``````pack(x, ...)
## S4 method for signature 'dgeMatrix'
pack(x, symmetric = NA, upperTri = NA, ...)
## S4 method for signature 'lgeMatrix'
pack(x, symmetric = NA, upperTri = NA, ...)
## S4 method for signature 'ngeMatrix'
pack(x, symmetric = NA, upperTri = NA, ...)
## S4 method for signature 'matrix'
pack(x, symmetric = NA, upperTri = NA, ...)

unpack(x, ...)
``````

### Arguments

 `x` A dense symmetric or dense triangular matrix. For `pack()`:typically an `"unpackedMatrix"` or a standard `"matrix"`, though `"packedMatrix"` are allowed and returned unchanged. For `unpack()`:typically a `"packedMatrix"`, though `"unpackedMatrix"` are allowed and returned unchanged. `symmetric` logical (including `NA`) optionally indicating whether `x` is symmetric (or triangular). `upperTri` (for triangular `x` only) logical (including `NA`) indicating whether `x` is upper (or lower) triangular. `...` further arguments passed to or from other methods.

### Details

`pack(x)` checks matrices `x` not inheriting from one of the virtual classes `"symmetricMatrix"` `"triangularMatrix"` for symmetry (via `isSymmetric()`) then for upper and lower triangularity (via `isTriangular()`) in order to identify a suitable coercion. Setting one or both of `symmetric` and `upperTri` to `TRUE` or `FALSE` rather than `NA` allows skipping of irrelevant tests for large matrices known to be symmetric or (upper or lower) triangular.

Users should not assume that `pack()` and `unpack()` are inverse operations. Specifically, `y <- unpack(pack(x))` may not reproduce an `"unpackedMatrix"` `x` in the sense of `identical()`. See the examples.

### Value

For `pack()`:

a `"packedMatrix"` giving the condensed representation of `x`.

For `unpack()`:

an `"unpackedMatrix"` giving the full storage representation of `x`.

### Examples

``````
showMethods("pack")
(s <- crossprod(matrix(sample(15), 5,3))) # traditional symmetric matrix
(sp <- pack(s))
mt <- as.matrix(tt <- tril(s))
(pt <- pack(mt))
stopifnot(identical(pt, pack(tt)),
dim(s ) == dim(sp), all(s  == sp),
dim(mt) == dim(pt), all(mt == pt), all(mt == tt))

showMethods("unpack")
(cp4 <- chol(Hilbert(4))) # is triangular
tp4 <- pack(cp4) # [t]riangular [p]acked
str(tp4)
(unpack(tp4))
stopifnot(identical(tp4, pack(unpack(tp4))))

z1 <- new("dsyMatrix", Dim = c(2L, 2L), x = as.double(1:4), uplo = "U")
z2 <- unpack(pack(z1))
stopifnot(!identical(z1, z2), # _not_ identical
all(z1 == z2)) # but mathematically equal
cbind(z1@x, z2@x) # (unused!) lower triangle is "lost" in translation
``````

Matrix documentation built on May 29, 2024, 1:20 a.m.