H5SparseMatrixSeed-class {HDF5Array} | R Documentation

## H5SparseMatrixSeed objects

### Description

H5SparseMatrixSeed is a low-level helper class for representing a pointer to an HDF5 sparse matrix stored in CSR/CSC/Yale format.

It is a virtual class with two concrete subclasses: CSC_H5SparseMatrixSeed for the Compressed Sparse Column format and CSR_H5SparseMatrixSeed for the Compressed Sparse Row format. The former is used by 10x Genomics (e.g. "1.3 Million Brain Cell Dataset"). `h5ad` files can use one or the other format to store a sparse matrix.

Note that an H5SparseMatrixSeed derivative is not intended to be used directly. Most end users will typically create and manipulate a higher-level H5SparseMatrix object instead. See `?H5SparseMatrix` for more information.

### Usage

    ## --- Constructor function ---

    H5SparseMatrixSeed(filepath, group, subdata=NULL)

    ## --- Accessors --------------

    ## S4 method for signature 'H5SparseMatrixSeed'
    path(object)

    ## S4 method for signature 'H5SparseMatrixSeed'
    dim(x)

    ## S4 method for signature 'H5SparseMatrixSeed'
    dimnames(x)

    ## S4 method for signature 'CSC_H5SparseMatrixSeed'
    chunkdim(x)
    ## S4 method for signature 'CSR_H5SparseMatrixSeed'
    chunkdim(x)

    ## --- Data extraction --------

    ## S4 method for signature 'H5SparseMatrixSeed'
    extract_array(x, index)

    ## S4 method for signature 'H5SparseMatrixSeed'
    extract_sparse_array(x, index)

    ## S4 method for signature 'H5SparseMatrixSeed'
    read_sparse_block(x, viewport)

    ## S4 method for signature 'CSC_H5SparseMatrixSeed'
    extractNonzeroDataByCol(x, j)
    ## S4 method for signature 'CSR_H5SparseMatrixSeed'
    extractNonzeroDataByRow(x, i)

    ## --- Other methods ----------

    ## S4 method for signature 'H5SparseMatrixSeed'
    is_sparse(x)

    ## S4 method for signature 'H5SparseMatrixSeed'
    sparsity(x)

### Arguments

`filepath, group` | See `?H5SparseMatrix` for a description of these arguments.
`subdata` | Experimental. Don't use!
`object, x` | An H5SparseMatrixSeed derivative.
`index` | See `?extract_array` in the DelayedArray package.
`viewport` | See `?read_block` in the DelayedArray package.
`j` | An integer vector containing valid column indices.
`i` | An integer vector containing valid row indices.

### Details

Note that the implementation of CSC_H5SparseMatrixSeed and CSR_H5SparseMatrixSeed objects follows the usual convention of transposing the HDF5 matrix when loading it into R. This means that a CSC_H5SparseMatrixSeed object represents a sparse matrix stored in the CSR format (Compressed Sparse Row) at the HDF5 level, and a CSR_H5SparseMatrixSeed object represents a sparse matrix stored in the CSC format (Compressed Sparse Column) at the HDF5 level.

Finally note that H5SparseMatrixSeed derivatives support a very limited set of methods:

- `path()`: Returns the path to the HDF5 file where the sparse matrix is located.

- `dim()`, `dimnames()`.

- `chunkdim()`, `extract_array()`, `extract_sparse_array()`, `read_sparse_block()`, `is_sparse()`: These generics are defined and documented in the DelayedArrray package.

- `sparsity()`: Returns the number of zero-valued matrix elements in the object divided by its total number of elements (a.k.a. its length).

- `extractNonzeroDataByCol()`: Works on CSC_H5SparseMatrixSeed objects only. Returns a NumericList or IntegerList object parallel to `j`, that is, with one list element per column index in `j`. The row indices of the values are not returned. Furthermore, the values within a given list element can be returned in **any order**. In particular, do NOT assume that they are ordered by ascending row index.

- `extractNonzeroDataByRow()`: Works on CSR_H5SparseMatrixSeed objects only. Returns a NumericList or IntegerList object parallel to `i`, that is, with one list element per row index in `i`. The column indices of the values are not returned. Furthermore, the values within a given list element can be returned in **any order**. In particular, do NOT assume that they are ordered by ascending column index.

In order to have access to the full set of operations that are available for DelayedMatrix objects, an H5SparseMatrixSeed derivative would first need to be wrapped in a DelayedMatrix object, typically by calling the `DelayedArray()` constructor on it.

### Value

`H5SparseMatrixSeed()` returns an H5SparseMatrixSeed derivative (CSC_H5SparseMatrixSeed or CSR_H5SparseMatrixSeed object).

### References

https://en.wikipedia.org/wiki/Sparse_matrix for a description of the CSR/CSC/Yale format (section "Compressed sparse row (CSR, CRS or Yale format)").

### See Also

- H5SparseMatrix objects.

- `h5ls` to list the content of an HDF5 file (`.h5` or `.h5ad`).

### Examples

    showClass("H5SparseMatrixSeed")

[Package HDF5Array version 1.22.1 Index]