RunGGML: Run a GGML GPU operation on a Seurat object

In ggmlR: 'GGML' Tensor Operations for Machine Learning

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 class '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,
  ...
)

## Default S3 method:
RunGGML(
  object,
  op = "embed",
  assay = NULL,
  layer = NULL,
  n_components = 50L,
  reduction_name = "ggml",
  device = "auto",
  genes = NULL,
  cells = NULL,
  ...
)

## S3 method for class '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,
  ...
)

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.

Value

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

Examples

## Not run: 
library(Seurat)
pbmc <- RunGGML(pbmc, op = "embed", n_components = 30)
DimPlot(pbmc, reduction = "ggml")

## End(Not run)

ggmlR documentation built on July 14, 2026, 1:08 a.m.