ggml_extract: Extract a feature-by-cell matrix from a single-cell container

Description

Pulls an expression matrix out of a Seurat object, a SingleCellExperiment, a sparse dgCMatrix or a plain matrix, returning a dense numeric matrix with features in rows and cells in columns — the layout the GPU engine expects. Optional genes/cells subsetting happens before any sparse-to-dense materialisation.

Usage

ggml_extract(x, assay = NULL, layer = "data", genes = NULL, cells = NULL, ...)
# S3 method for matrix
ggml_extract(x, assay = NULL, layer = "data", genes = NULL, cells = NULL, ...)
# S3 method for dgCMatrix
ggml_extract(
  x,
  assay = NULL,
  layer = "data",
  genes = NULL,
  cells = NULL,
  keep_sparse = FALSE,
  ...
)
# S3 method for Seurat
ggml_extract(
  x,
  assay = NULL,
  layer = "data",
  genes = NULL,
  cells = NULL,
  keep_sparse = FALSE,
  ...
)
# S3 method for SingleCellExperiment
ggml_extract(
  x,
  assay = NULL,
  layer = "logcounts",
  genes = NULL,
  cells = NULL,
  keep_sparse = FALSE,
  ...
)

Value

A dense numeric matrix, features x cells.

Arguments

x: A Seurat, SingleCellExperiment, dgCMatrix or matrix object.
assay: Assay to read from. Seurat: defaults to the object's default assay. Ignored for bare matrices.
layer: Layer / slot to read. Seurat v5: a layer name (default "data"); Seurat v4: mapped to the slot argument of GetAssayData. Ignored for bare matrices.
genes: Optional character/integer vector selecting feature rows.
cells: Optional character/integer vector selecting cell columns.
...: Passed to methods.
keep_sparse: If TRUE, return the (subset) dgCMatrix without densifying. Only the LogNormalize path (op = "normalize") sets this, since it transforms the stored non-zeros in place; every other op leaves it FALSE and gets a dense matrix as before.

Details

For a SingleCellExperiment the layer argument names an assay (default "logcounts", the log-normalised matrix); it is read with SummarizedExperiment::assay().