RunGGML.SingleCellExperiment: Run a GGML GPU operation on a Seurat object

Description

High-level, Seurat-style entry point: extracts the expression matrix from the object, runs the requested operation on the GGML backend (Vulkan GPU with CPU fallback) and writes the result back into the object. Returns the updated object, so it slots into a %>% / |> pipeline next to Seurat::RunPCA(). Methods exist for Seurat and SingleCellExperiment objects (and a .default for bare matrices).

Usage

# S3 method for SingleCellExperiment
RunGGML(
  object,
  op = "embed",
  assay = NULL,
  layer = NULL,
  n_components = 50L,
  reduction_name = "ggml",
  device = "auto",
  genes = NULL,
  cells = NULL,
  reduction = NULL,
  dims = NULL,
  ...
)
RunGGML(
  object,
  op = "embed",
  assay = NULL,
  layer = NULL,
  n_components = 50L,
  reduction_name = "ggml",
  device = "auto",
  genes = NULL,
  cells = NULL,
  reduction = NULL,
  dims = NULL,
  ...
)
# S3 method for default
RunGGML(
  object,
  op = "embed",
  assay = NULL,
  layer = NULL,
  n_components = 50L,
  reduction_name = "ggml",
  device = "auto",
  genes = NULL,
  cells = NULL,
  ...
)
# S3 method for Seurat
RunGGML(
  object,
  op = "embed",
  assay = NULL,
  layer = NULL,
  n_components = 50L,
  reduction_name = "ggml",
  device = "auto",
  genes = NULL,
  cells = NULL,
  reduction = NULL,
  dims = NULL,
  ...
)

Value

For a Seurat object, the updated object with a new reduction. For a bare matrix, a ggml_result.

Arguments

object: A Seurat or SingleCellExperiment object, or a bare feature-by-cell matrix/dgCMatrix (the .default method returns a ggml_result instead of an object).
op: Operation name; see ggml_ops_registry. Default "embed".
assay: Assay to read (Seurat); defaults to the object's default assay.
layer: Layer/slot to read; default "data".
n_components: Number of components for "embed" (PCA). Default 50.
reduction_name: Name of the reduction slot to create. Default "ggml".
device: "auto" (default), "vulkan" or "cpu".
genes, cells: Optional feature/cell subsets passed to extraction.
reduction: Optional name of an existing reduction to use as the input feature space (e.g. "pca" for "umap" / "neighbors"), instead of an assay layer. Seurat: Embeddings(); SCE: reducedDim().
dims: Optional integer vector selecting columns of reduction.
...: Additional parameters forwarded to the engine. A notable one is chunk_size: for op = "scale" and op = "embed" (PCA), passing an integer streams the sparse input in blocks of that many cells, densifying one block at a time so the full dense features-by-cells matrix (tens of GB at scale) is never held. Results are identical to the non-chunked path. op = "normalize" is already sparse, so chunk_size is a no-op there.

Details

Supported operations include "embed" (PCA), "normalize", "scale", "umap", "neighbors" and "largest_gene" (per-cell highest-expressed gene QC metric); see ggml_ops_registry.

Examples

Run this code

if (FALSE) {
library(Seurat)
pbmc <- RunGGML(pbmc, op = "embed", n_components = 30)
DimPlot(pbmc, reduction = "ggml")
}

Run the code above in your browser using DataLab