Virtual Class of Symmetric Matrices in Package Matrix

The virtual class of symmetric matrices, "symmetricMatrix", from the package Matrix contains numeric and logical, dense and sparse matrices, e.g., see the examples with the “actual” subclasses.

The main use is in methods (and C functions) that can deal with all symmetric matrices, and in as(*, "symmetricMatrix").

Slots

Dim, Dimnames: inherited from virtual class Matrix. See comments below about symmetry of Dimnames.
factors: a list of MatrixFactorization objects caching factorizations of the matrix. Typically, it is initialized as an empty list and updated “automagically” whenever a factorization is computed.
uplo: a character string, either "U" or "L" indicating that only entries in the upper or lower triangle are referenced.

Extends

Class "Matrix", directly.

Methods

dimnames: signature(object = "symmetricMatrix"): returns symmetric dimnames, even when the Dimnames slot only has row or column names. This allows to save storage for large (typically sparse) symmetric matrices.
isSymmetric: signature(object = "symmetricMatrix"): returns TRUE trivially.

There's a C function symmetricMatrix_validate() called by the internal validity checking functions, and also from getValidity(getClass("symmetricMatrix")).

Validity and `dimnames`

The validity checks do not require a symmetric Dimnames slot, so it can be list(NULL, <character>), e.g., for efficiency. However, dimnames() and other functions and methods should behave as if the dimnames were symmetric, i.e., with both list components identical.

Examples

## An example about the symmetric Dimnames:
sy <- sparseMatrix(i= c(2,4,3:5), j= c(4,7:5,5), x = 1:5, dims = c(7,7),
                   symmetric=TRUE, dimnames = list(NULL, letters[1:7]))
sy # shows symmetrical dimnames
#> 7 x 7 sparse Matrix of class "dsCMatrix"
#>   a b c d e f g
#> a . . . . . . .
#> b . . . 1 . . .
#> c . . . . . 3 .
#> d . 1 . . 4 . 2
#> e . . . 4 5 . .
#> f . . 3 . . . .
#> g . . . 2 . . .
sy@Dimnames  # internally only one part is stored
#> [[1]]
#> NULL
#> 
#> [[2]]
#> [1] "a" "b" "c" "d" "e" "f" "g"
#> 
dimnames(sy) # both parts - as sy *is* symmetrical
#> [[1]]
#> [1] "a" "b" "c" "d" "e" "f" "g"
#> 
#> [[2]]
#> [1] "a" "b" "c" "d" "e" "f" "g"
#> 
showClass("symmetricMatrix")
#> Virtual Class "symmetricMatrix" [package "Matrix"]
#> 
#> Slots:
#>                                               
#> Name:       uplo   factors       Dim  Dimnames
#> Class: character      list   integer      list
#> 
#> Extends: "Matrix"
#> 
#> Known Subclasses: 
#> Class "nsyMatrix", directly
#> Class "nspMatrix", directly
#> Class "lsyMatrix", directly
#> Class "lspMatrix", directly
#> Class "dsyMatrix", directly
#> Class "dspMatrix", directly
#> Class "nsCMatrix", directly
#> Class "nsRMatrix", directly
#> Class "nsTMatrix", directly
#> Class "lsCMatrix", directly
#> Class "lsRMatrix", directly
#> Class "lsTMatrix", directly
#> Class "dsCMatrix", directly
#> Class "dsRMatrix", directly
#> Class "dsTMatrix", directly
#> Class "dpoMatrix", by class "dsyMatrix", distance 2
#> Class "dppMatrix", by class "dspMatrix", distance 2
#> Class "corMatrix", by class "dsyMatrix", distance 3
#> Class "copMatrix", by class "dspMatrix", distance 3

## The names of direct subclasses:
scl <- getClass("symmetricMatrix")@subclasses
directly <- sapply(lapply(scl, slot, "by"), length) == 0
names(scl)[directly]
#>  [1] "nsyMatrix" "nspMatrix" "lsyMatrix" "lspMatrix" "dsyMatrix" "dspMatrix"
#>  [7] "nsCMatrix" "nsRMatrix" "nsTMatrix" "lsCMatrix" "lsRMatrix" "lsTMatrix"
#> [13] "dsCMatrix" "dsRMatrix" "dsTMatrix"

## Methods -- applicaple to all subclasses above:
showMethods(classes = "symmetricMatrix")
#> Function: - (package base)
#> e1="symmetricMatrix", e2="missing"
#> 
#> Function: Cholesky (package Matrix)
#> A="symmetricMatrix"
#> 
#> Function: Schur (package Matrix)
#> x="symmetricMatrix"
#> 
#> 
#> Function "as.matrix.coo":
#>  <not an S4 generic function>
#> 
#> Function "as.matrix.csc":
#>  <not an S4 generic function>
#> 
#> Function "as.matrix.csr":
#>  <not an S4 generic function>
#> 
#> Function "as.matrix.ssc":
#>  <not an S4 generic function>
#> 
#> Function "as.matrix.ssr":
#>  <not an S4 generic function>
#> 
#> Function "asJSON":
#>  <not an S4 generic function>
#> 
#> Function "backsolve":
#>  <not an S4 generic function>
#> Function: chol (package base)
#> x="symmetricMatrix"
#> 
#> Function: chol2inv (package base)
#> x="symmetricMatrix"
#> 
#> Function: coerce (package methods)
#> from="Matrix", to="symmetricMatrix"
#> from="dgCMatrix", to="symmetricMatrix"
#>     (inherited from: from="Matrix", to="symmetricMatrix")
#> from="dgTMatrix", to="symmetricMatrix"
#>     (inherited from: from="Matrix", to="symmetricMatrix")
#> from="diagonalMatrix", to="symmetricMatrix"
#> from="dpoMatrix", to="symmetricMatrix"
#> from="dsCMatrix", to="symmetricMatrix"
#> from="dsRMatrix", to="symmetricMatrix"
#> from="dsTMatrix", to="symmetricMatrix"
#> from="dsyMatrix", to="symmetricMatrix"
#> from="lgeMatrix", to="symmetricMatrix"
#>     (inherited from: from="Matrix", to="symmetricMatrix")
#> from="lsCMatrix", to="symmetricMatrix"
#> from="lsTMatrix", to="symmetricMatrix"
#> from="lspMatrix", to="symmetricMatrix"
#> from="lsyMatrix", to="symmetricMatrix"
#> from="matrix", to="symmetricMatrix"
#> from="ngeMatrix", to="symmetricMatrix"
#>     (inherited from: from="Matrix", to="symmetricMatrix")
#> from="nsCMatrix", to="symmetricMatrix"
#> from="nsTMatrix", to="symmetricMatrix"
#> 
#> Function: dimnames (package base)
#> x="symmetricMatrix"
#> 
#> Function: dimnames<- (package base)
#> x="symmetricMatrix", value="NULL"
#> x="symmetricMatrix", value="list"
#> 
#> 
#> Function "forwardsolve":
#>  <not an S4 generic function>
#> 
#> Function "model.guess":
#>  <not an S4 generic function>
#> 
#> Function "model.matrix":
#>  <not an S4 generic function>
#> 
#> Function "model.response":
#>  <not an S4 generic function>
#> 
#> Function "model.xexact":
#>  <not an S4 generic function>