Package 'bixverse.gpu'

Description

GPU counterpart of bixverse::bbknn_sc(), implementing the batch-balanced k-nearest neighbour algorithm from Polański, et al. One nearest neighbour index is built per batch and queried by every cell, so each cell gets neighbours_within_batch neighbours from every batch. The UMAP connectivity calculations that reduce spurious connections then run on the CPU, shared with the CPU implementation.

Usage

bbknn_gpu_sc(
  object,
  batch_column,
  no_neighbours_to_keep = 5L,
  embd_to_use = "pca",
  no_embd_to_use = NULL,
  bbknn_params = params_sc_bbknn_gpu(),
  seed = 42L,
  .verbose = TRUE
)

Arguments

Details

Only the per-batch searches move to the device, and they are the part that scales with batch count: BBKNN builds one index per batch and queries each with all cells, so the work grows as n_cells * n_batches. With a handful of batches on a small object the CPU is fine. The GPU starts to matter once you have many samples.

Results match the CPU path exactly with knn_method = "exhaustive", since both are exact and recompute distances against the same embedding. The approximate backends break ties differently and will not.

Value

The object with the added kNN matrix based on BBKNN and the graph based on the returned connectivities of the algorithm.

References

Polański, et al., Bioinformatics, 2020

Description

GPU counterpart of bixverse::bonsai_sc(). Sanity, which turns the raw counts into posterior log fold changes with error bars and is most of the runtime on the CPU, runs on the WGPU backend. Genes are streamed through it in chunks and only the ones passing Bonsai's signal-to-noise filter are kept. The tree search and the layout run on the CPU, as they do in bixverse.

The device computes in f32, so the posteriors match the CPU run to within the resolution of Sanity's variance grid rather than bit for bit, and a gene sitting right at the signal-to-noise threshold can end up on the other side.

Usage

bonsai_gpu_sc(
  object,
  hvg = NULL,
  bonsai_params = bixverse::params_sc_bonsai(),
  .verbose = TRUE
)

Arguments

Value

A BonsaiTree S3 object, see bixverse::bonsai_sc().

References

de Groot, et al., Nat. Biotechnol., 2026; Breda, et al., Nat. Biotechnol., 2021.

Description

This function will run sparse, randomised SVD while running several of the large matrix multiplications on GPU for improved speed. This also means you will have to provide the necessary VRAM for your data set. This version only works on the "rna" modality.

Usage

calculate_pca_gpu_sc(
  object,
  no_pcs,
  pca_params = bixverse::params_sc_pca(),
  hvg = NULL,
  seed = 42L,
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Value

The function will add the PCA factors, loadings and singular values to the object cache in memory.

Description

GPU counterpart of bixverse::consensus_nmf_sc(). Runs n_runs HALS restarts on the device, pools their components, drops unstable ones by local density, k-means clusters the survivors and refits the partner factor against the per-cluster median.

Prefer this over stabilised_nmf_gpu_sc(), which picks the lowest-loss restart. Use nmf_k_sweep_gpu_sc() first if you do not already know k.

Usage

consensus_nmf_gpu_sc(
  object,
  k,
  cell_ids = NULL,
  gene_ids = NULL,
  preprocessing = "none",
  use_second_layer = TRUE,
  nmf_hals_params = bixverse::params_nmf_hals(),
  nmf_consensus_params = bixverse::params_nmf_consensus(),
  n_runs = 30L,
  seed = 42L,
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Details

Only the restarts move to the GPU. The pooling, the density filter, the k-means and the silhouette all run on the CPU, shared with the bixverse implementation, so the speed-up tracks how much of the run the solves own.

The restart factors are dense and all held at once, so budget for n_runs times k times the cell count on top of the counts themselves.

If the density filter leaves fewer than k components, or a cluster comes out empty, the run errors rather than returning a partial answer. Raise density_threshold (2 switches the filter off) or increase n_runs.

Value

A ConsensusNmfResult object, the same class bixverse::consensus_nmf_sc() returns.

References

Kotliar et al., eLife, 2019

Description

GPU counterpart of bixverse::fast_cluster_sc(). Runs k-means on the chosen embedding, builds a kNN graph on the centroids, applies Louvain clustering and propagates the memberships back to the cells. Optionally runs a grid over multiple seeds and returns stability statistics.

Only the k-means coarsening runs on the WGPU backend. The centroid kNN, the optional sNN pass and the Louvain runs stay on the CPU, so the speedup tracks how much of the run k-means owns. That share grows with the cell count and with n_centroids. There is no km_type argument: the GPU k-means is full-batch Lloyd's and has no mini-batch path.

Usage

fast_cluster_gpu_sc(
  object,
  embd_to_use = "pca",
  no_embd_to_use = NULL,
  resolutions = c(2, 1, 0.5),
  n_centroids = NULL,
  fc_params = params_sc_fast_cluster_gpu(),
  snn = TRUE,
  return_kmeans = FALSE,
  grid_search = FALSE,
  no_seeds = 10L,
  seed = 42L,
  .verbose = TRUE
)

Arguments

Value

SingleCellFastClusters S3 object with:

memberships

data.table with cell_idx and one column per resolution (⁠res_<value>⁠).

stats

data.table of grid statistics, or NULL.

k_means_cluster

Integer vector of k-means assignments, or NULL.

centroids

Numeric matrix of centroids, or NULL.

resolutions

Resolutions used.

with cell_indices stored as an attribute (0-indexed).

Description

GPU counterpart of bixverse::fast_mnn_sc(), implementing the fast mutual nearest neighbour correction from Haghverdi, et al. Batches are merged one after the other: MNN pairs between the merged block and the next batch give correction vectors, which are smoothed with a tricube kernel and applied to every cell of that batch.

Usage

fast_mnn_gpu_sc(
  object,
  batch_column,
  no_embd_to_use = NULL,
  fastmnn_params = params_sc_fastmnn_gpu(),
  seed = 42L,
  .verbose = TRUE
)

Arguments

Details

Only the neighbour searches move to the device: both MNN directions and the tricube search, three index builds per merge. Those dominate the run time on the CPU path. Centring, MNN pairing and the tricube correction are shared with the CPU implementation.

The PCA stored in the object is corrected as is. If you want the PCA on batch-aware HVGs, as bixverse::fast_mnn_sc() can recompute it, run bixverse::find_hvg_batch_aware_sc() and the PCA first.

Results match the CPU path with knn_method = "exhaustive" on both sides, since both searches are exact. The approximate backends will not match.

Value

The object with a "mnn_gpu" embedding added. If the batch column only has one batch, the object is returned as is with a warning.

References

Haghverdi, et al., Nat Biotechnol, 2018

Description

This function generates kNN data using GPU-accelerated algorithms via the bixverse.gpu package, then turns it into an sNN igraph for downstream clustering. See generate_gpu_knn_sc() for the three searches on offer. This function lives in a separate package from the CPU-based find_neighbours_sc() so that users without GPU hardware do not need to install the GPU dependencies.

Usage

find_neighbours_gpu_sc(
  object,
  embd_to_use = "pca",
  no_embd_to_use = NULL,
  modality = c("rna", "adt"),
  knn_method = c("nndescent", "exhaustive", "ivf"),
  nn_params = params_nn_gpu(),
  k = 15L,
  snn_params = params_sc_neighbours(),
  seed = 42L,
  gpu_method = lifecycle::deprecated(),
  ivf_params = lifecycle::deprecated(),
  dist_metric = lifecycle::deprecated(),
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Value

The object with added kNN matrix and sNN graph in the selected modality slot.

Description

This function generates a SingleCellNearestNeighbour object using GPU-accelerated kNN algorithms via the bixverse.gpu package. Three methods are available: "exhaustive" performs an exact brute-force search on the GPU; "ivf" builds an inverted file index that partitions the embedding space into Voronoi cells and probes only a subset at query time; and "nndescent" builds a dense NNDescent graph and prunes it into a CAGRA navigational graph, which is then either beam searched or handed back as the descent left it (params_nn_gpu(extract_knn = TRUE), faster, lower recall). This function is the GPU counterpart of generate_knn_sc().

Usage

generate_gpu_knn_sc(
  object,
  embd_to_use = "pca",
  cells_to_use = NULL,
  no_embd_to_use = NULL,
  modality = c("rna", "adt"),
  knn_method = c("nndescent", "exhaustive", "ivf"),
  nn_params = params_nn_gpu(),
  k = 15L,
  seed = 42L,
  gpu_method = lifecycle::deprecated(),
  ivf_params = lifecycle::deprecated(),
  dist_metric = lifecycle::deprecated(),
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Value

Initialised sc_knn with the kNN data.

Description

This function generates a kNN graph based on a given numeric matrix. Three different GPU-accelerated versions are available

• "exhaustive" - Exact nearest neighbour search via GPU.

• "ivf" - Inverted file index that leverages k-means clustering and probing a few of the clusters via GPU-accelerated distance calculations.

• "nndescent" - A CAGRA style nearest neighbour search on the GPU.

Usage

generate_knn_graph_gpu(
  data,
  k,
  knn_method = c("nndescent", "exhaustive", "ivf"),
  nn_params = params_nn_gpu(),
  seed = 42L,
  extract_knn = lifecycle::deprecated(),
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Value

A nearest neighbours class object with 1-indexed neighbour indices and distances. Euclidean distances are true L2, not squared.

Description

GPU counterpart of bixverse::generate_seacells_sc(). Both Frank-Wolfe solves, the B-gradient argmin and the per-cell A columns, run on the WGPU backend. Kernel construction, archetype initialisation, the ⁠K^2 B⁠ bookkeeping, the RSS evaluation and the aggregation into pseudo-bulk counts stay on the CPU, so the speedup tracks how much of the run the two solves own. That share grows with n_sea_cells. Each solve falls back to its CPU sibling for that iteration if no GPU workgroup tier covers k.

Params, result class and downstream code are identical to the CPU version.

Usage

generate_seacells_gpu_sc(
  object,
  seacell_params = bixverse::params_sc_seacells(),
  embd_to_use = "pca",
  no_embd_to_use = NULL,
  cells_to_use = NULL,
  regenerate_knn = FALSE,
  target_size = 1e+05,
  seed = 42L,
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Value

A bixverse::MetaCells() with the data generated by this meta cell aggregation method.

References

Persad, et al. Nat Biotechnol, 2023

Description

Reports whether a usable WGPU adapter is present. Every function in this package needs one, and without it the Rust side aborts rather than returning an error, so this is the way to branch before calling into it.

The probe initialises the same client the GPU functions use, so a TRUE means they will genuinely run rather than that a device merely exists. It is cached for the session, and the client is left warm, so the first real call afterwards skips the setup cost.

Usage

gpu_available()

Value

Boolean. TRUE when a WGPU adapter could be initialised.

Examples

if (gpu_available()) {
  # ... GPU path
}

Description

A GPU-accelerated version of Harmony v2 by Patikas et al., 2026, implemented in Rust. Performs batch correction on PCA embeddings and stores the result as a "harmony_gpu" embedding in the object. Only a single batch covariate is supported on the GPU path.

Usage

harmony_v2_gpu_sc(
  object,
  batch_column,
  modality = c("rna", "adt"),
  harmony_params = params_sc_harmony_v2_gpu(),
  seed = 42L,
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Value

The object with a "harmony_gpu" embedding added. If no PCA embeddings are found, returns the object unchanged with a warning.

Description

bixverse.gpu ships a skill that teaches coding agents how to use the package: which GPU function replaces which bixverse step, the knobs that differ, what does not run on the GPU and the traps. This copies it out of the installed package to where your agent looks for it. It complements the bixverse skill, see bixverse::install_agent_skill().

The skill is versioned with the package, so re-run this after upgrading bixverse.gpu to keep the agent in sync with the code.

Usage

install_agent_skill_gpu(
  dest = NULL,
  agent = c("claude", "codex", "generic"),
  overwrite = FALSE
)

Arguments

Details

The reference files are plain markdown and work anywhere. Only the entry file differs between agents:

• "claude" writes SKILL.md with the YAML frontmatter Claude Code uses to decide when to load the skill. Discovery is automatic.

• "codex" and "generic" write AGENTS.md with the frontmatter stripped, since no other agent reads it. There is no auto-discovery, so point the agent at the directory yourself.

Value

The path the skill was written to, invisibly.

Examples

## Not run: 
# Claude Code, into ~/.claude/skills, auto-discovered
install_agent_skill_gpu()

# Codex, into ~/.codex/skills as AGENTS.md
install_agent_skill_gpu(agent = "codex")

# refresh after a package upgrade
install_agent_skill_gpu(overwrite = TRUE)

## End(Not run)

Description

Performs k-means clustering as a GPU-accelerated form. In its current form uses the cubecl with wgpu backend.

Usage

k_means_cluster_gpu(
  data,
  k,
  kmeans_params = params_kmeans_gpu(),
  seed = 42L,
  .verbose = TRUE
)

Arguments

Value

A KMeansClusterGPU class with assignments and centroids.

Description

Load a parametric UMAP as a qs2 file

Usage

load_parametric_umap(path)

Arguments

Value

The ParametricUmapModel.

Description

Reports whether this build carries the MLX backend. MLX is Apple Silicon only and opt-in at install time, since mlx-c is a system library the package cannot ship: install mlx-c (⁠brew install mlx-c⁠, or point MLX_C_PREFIX at an install prefix) and reinstall with BIXVERSE_GPU_MLX=true. Functions with an MLX path take backend = "mlx".

Usage

mlx_available()

Value

Boolean. TRUE when the package was built with the MLX backend.

Examples

if (mlx_available()) {
  # ... backend = "mlx"
}

Description

GPU counterpart of bixverse::nebula_sc(). Stage two of NEBULA, the per-gene penalised fits, runs on the WGPU backend in f32 and is finished on the host in f64. Cell ordering, gene batching, the dispersion shrinkage and the Wald test are the CPU code. Expect estimates close to the CPU ones, not identical to them.

REML is not implemented on the device, so params_nebula_gpu() does not carry it. Everything else, the design handling, the result class and the downstream code, is identical to the CPU version.

Usage

nebula_gpu_sc(
  object,
  subject_col,
  design,
  coef = NULL,
  contrast = NULL,
  genes_to_use = NULL,
  cells_to_use = NULL,
  offset = NULL,
  nebula_params = params_nebula_gpu(),
  .verbose = TRUE
)

Arguments

Value

A ScNebula class, see bixverse:::new_sc_nebula_res(), with

• results - data.table. One row per gene that survived NEBULA's expression filter, with the Wald test and both overdispersions.

• coefficients - Numeric matrix of genes x coefficients.

• se - Numeric matrix of genes x coefficients.

• params - List. The parameters the run used.

References

He, et al., Commun Biol, 2021

Description

GPU counterpart of bixverse::nmf_sc(). Runs one HALS NMF on a chosen subset of cells and genes. The counts are uploaded once and the whole HALS loop runs on the WGPU backend; the NNDSVD initialisation stays on the CPU.

For SingleCells the counts are streamed from the Rust binary files, for MetaCells the in-memory sparse counts are used. Params, result class and downstream code are identical to the CPU version.

A single run is here for parity rather than speed. The GPU pays off when the same matrix serves many solves, so reach for consensus_nmf_gpu_sc() or nmf_k_sweep_gpu_sc() if you want the speed-up.

Usage

nmf_gpu_sc(
  object,
  k,
  cell_ids = NULL,
  gene_ids = NULL,
  preprocessing = "none",
  use_second_layer = TRUE,
  nmf_hals_params = bixverse::params_nmf_hals(),
  seed = 42L,
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Value

An NmfResult object, the same class bixverse::nmf_sc() returns.

Description

GPU counterpart of bixverse::nmf_k_sweep_sc(). Runs the consensus step across a range of ranks and reports stability against reconstruction error, keeping no factors. Pick the last k before stability falls away while the error curve is still coming down, then fit there with consensus_nmf_gpu_sc().

Usage

nmf_k_sweep_gpu_sc(
  object,
  k_range,
  cell_ids = NULL,
  gene_ids = NULL,
  preprocessing = "none",
  use_second_layer = TRUE,
  nmf_hals_params = bixverse::params_nmf_hals(),
  nmf_consensus_params = bixverse::params_nmf_consensus(),
  n_runs = 30L,
  seed = 42L,
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Details

This is the shape the GPU path is really for. The counts upload once and serve all length(k_range) * n_runs solves, where the CPU pays full memory traffic over the matrix for every one of them. The scratch is sized once at the largest rank in k_range.

It is a diagnostic, so it leaves the object alone and hands the result back directly. plot() on it gives you the two curves.

Value

An NmfKSweepResult, which is a data.table with one row per k.

References

Kotliar et al., eLife, 2019

Description

Performs parametric UMAP dimensionality reduction using a neural network encoder trained on the GPU via wgpu.

Usage

parametric_umap(
  data,
  n_dim = 2L,
  k = 15L,
  min_dist = 0.1,
  spread = 1,
  knn_method = c("kmknn", "hnsw", "annoy", "nndescent", "balltree", "exhaustive"),
  nn_params = manifoldsR::params_nn(),
  parametric_umap_params = params_parametric_umap(),
  use_gpu = TRUE,
  seed = 42L,
  .verbose = TRUE
)

Arguments

Value

A ParametricUmapModel object containing the embedding matrix and the trained encoder model.

Description

Default parameters for GPU k-means

Usage

params_kmeans_gpu(
  k_means_iter = 50L,
  k_means_init = NULL,
  metric = c("euclidean", "cosine"),
  fixed = FALSE,
  quantise = FALSE
)

Arguments

Value

A named list with the following elements:

• k_means_iter - Integer. Number of k-means iterations. Defaults to 50L.

• k_means_init - String or NULL. Initialisation method. One of "random", "parallel", or "plusplus". If NULL, determined on the Rust side. Defaults to NULL.

• metric - String. The distance metric. One of c("euclidean", "cosine"). Defaults to "euclidean".

• fixed - Boolean. Shall the algorithm be run for a fixed number of iterations, without checking for convergence. Defaults to FALSE.

• quantise - Boolean. Whether to quantise data to fp16 before clustering. This can improve performance in circumstances where it is memory bound. Defaults to FALSE.

Description

GPU sibling of bixverse::params_knn_defaults(). The GPU indices take a different knob set: there is no Annoy and no HNSW on the device, so what survives is exhaustive, IVF and NN-descent.

Usage

params_knn_gpu_defaults()

Details

NN-descent builds a CAGRA graph and, with extract_knn = TRUE, hands that graph back rather than beam searching over it. Note that this saves the query, not the build: the descent itself dominates, and its build degree tracks k. NN-descent is therefore a low-k tool on the GPU. Above k of roughly 30 both exhaustive and IVF beat it, and by k = 200 they beat it by more than an order of magnitude.

Value

A named list with the following elements:

• k - Integer. Number of neighbours. 0L hands the choice to Rust, which uses sqrt(n_cells) * 0.5 and then adjusts for the simulated doublets. Defaults to 15L.

• knn_method - String. The GPU index to use. One of c("exhaustive", "ivf", "nndescent"). Defaults to "exhaustive".

• ann_dist - String. Manhattan is not supported by the GPU kernels. One of c("euclidean", "cosine"). Defaults to "euclidean".

• n_list - Integer or NULL. IVF only. Number of clusters. NULL gives sqrt(n). Defaults to NULL.

• n_probe - Integer or NULL. IVF only. Clusters to probe. NULL gives sqrt(n_list). Defaults to NULL.

• graph_k - Integer or NULL. NN-descent only. Node degree of the graph after pruning. NULL gives 30, widened to cover k when extract_knn is set. Defaults to NULL.

• k_build - Integer or NULL. NN-descent only. Build degree before pruning. NULL gives max(k, floor(1.5 * k)). Defaults to NULL.

• n_tree - Integer or NULL. NN-descent only. Trees seeding the descent. Defaults to NULL.

• delta - Numeric. NN-descent only. Termination criterium for the descent. Defaults to 0.001.

• rho - Numeric or NULL. NN-descent only. Sampling rate for the descent. Defaults to NULL.

• refine_knn - Integer or NULL. NN-descent only. 2-hop refinement sweeps after the descent. Buys graph quality at a linear cost. NULL gives 0. Defaults to NULL.

• beam_width - Integer or NULL. NN-descent only. Beam width when querying. Ignored when extract_knn is set. Defaults to NULL.

• max_beam_iters - Integer or NULL. NN-descent only. Beam search iterations. Ignored when extract_knn is set. Defaults to NULL.

• n_entry_points - Integer or NULL. NN-descent only. Entry points when querying. Ignored when extract_knn is set. Defaults to NULL.

• extract_knn - Boolean. NN-descent only. Hand back the graph the descent built instead of beam searching over it. Defaults to FALSE.

Description

GPU counterpart to bixverse::params_nebula(). Same knobs and defaults, minus reml: the device fit does not implement it. Stage two of NEBULA, the per-gene penalised fits, runs in f32 on the device and is finished on the host in f64, so the estimates sit close to the CPU ones rather than on them.

Usage

params_nebula_gpu(
  nebula_method = c("ln", "hl"),
  min_sigma = 1e-04,
  min_phi = 1e-04,
  max_sigma = 10,
  max_phi = 1000,
  cutoff_cell = 20,
  kappa = 800,
  cpc = 0.005,
  mincp = 5L,
  min_subjects = 0L,
  eps = 1e-06,
  gene_batch_size = 1000L,
  shrink_dispersion = TRUE
)

Arguments

Value

A named list with the following elements:

• nebula_method - String. Which variant to run. NEBULA downgrades "ln" to "hl" below 30 cells per subject, as the R package does. One of c("ln", "hl"). Defaults to "ln".

• min_sigma - Numeric. Lower bound on the subject-level overdispersion. Defaults to 1e-04.

• min_phi - Numeric. Lower bound on the cell-level overdispersion. Defaults to 1e-04.

• max_sigma - Numeric. Upper bound on the subject-level overdispersion. Defaults to 10.0.

• max_phi - Numeric. Upper bound on the cell-level overdispersion. Defaults to 1000.0.

• cutoff_cell - Numeric. Refit both overdispersions when the product of the cells per subject and the estimated phi falls below this. Defaults to 20.0.

• kappa - Numeric. Threshold on NEBULA's kappa_obs above which the subject-level overdispersion from stage one is trusted as is. Defaults to 800.0.

• cpc - Numeric. Drop a gene whose mean count per cell is at most this. Defaults to 0.005.

• mincp - Integer. Drop a gene expressed in fewer than this many cells. Defaults to 5L.

• min_subjects - Integer. Drop a gene that fewer than this many subjects express, a subject expressing it when its own mean count per cell is above cpc. cpc and mincp pool every cell, so one subject can carry a gene through on its own. 0 switches the check off, as in the nebula package. Defaults to 0L.

• eps - Numeric. Absolute stopping tolerance for the optimiser. Defaults to 1e-06.

• gene_batch_size - Integer. Genes read and fitted per batch. Bounds how much of the store is resident at once and changes nothing about the answer, since NEBULA is gene-independent. Defaults to 1000L.

• shrink_dispersion - Boolean. Shrink the cell-level overdispersions towards an empirical Bayes prior once the sweep is done. Defaults to TRUE.

References

He, et al., Commun Biol, 2021

Description

Wrapper function to generate GPU nearest neighbour parameters

Usage

params_nn_gpu(
  dist_metric = c("euclidean", "cosine"),
  n_list = NULL,
  n_probes = NULL,
  node_degree_final = NULL,
  k_build = NULL,
  n_tree = NULL,
  delta = 0.001,
  rho = NULL,
  beam_width = NULL,
  max_beam_iters = NULL,
  n_entry_points = NULL,
  extract_knn = FALSE
)

Arguments

Value

A named list with the following elements:

• dist_metric - String. The distance metric to use. One of c("euclidean", "cosine"). Defaults to "euclidean".

• n_list - Integer or NULL. IVF GPU: Number of clusters to use. If NULL, will default to sqrt(n). Defaults to NULL.

• n_probes - Integer or NULL. IVF GPU: Number of clusters to probe. If NULL, will default to sqrt(n_list). Defaults to NULL.

• node_degree_final - Integer or NULL. Final node degree of the CAGRA navigational graph. If NULL, defaults to 30 on the Rust side. Defaults to NULL.

• k_build - Integer or NULL. Number of k-neighbours during the NNDescent build phase before CAGRA pruning. If NULL, defaults to 1.5 * node_degree_final on the Rust side. (Cannot be smaller than node_degree_final) Defaults to NULL.

• n_tree - Integer or NULL. CAGRA GPU: Number of trees for graph build. Automatically if NULL. Defaults to NULL.

• delta - Numeric. CAGRA GPU: Early termination parameter for NN descent. Defaults to 0.001.

• rho - Numeric or NULL. CAGRA GPU: Sample rate parameter for NN descent. Defaults to NULL.

• beam_width - Integer or NULL. CAGRA GPU: Beam width for beam search. If not provided will be set to max(c(k, node_degree_final, 16L)) * 2. Defaults to NULL.

• max_beam_iters - Integer or NULL. CAGRA GPU: Maximum number of beam search iterations. If not provided, defaults to 3 * beam_width. Defaults to NULL.

• n_entry_points - Integer or NULL. CAGRA GPU: Number of entry points for beam search. If not provided, defaults to 8L. Defaults to NULL.

• extract_knn - Boolean. CAGRA GPU: Skip the beam search and take the graph the NNDescent left it. Faster, slightly lower recall. Ignored by the other two searches. Defaults to FALSE.

Description

Wrapper function to generate parametric UMAP parameters

Usage

params_parametric_umap(
  local_connectivity = 1,
  bandwidth = 1e-05,
  mix_weight = 1,
  hidden_layers = c(128L, 64L, 32L),
  lr = 0.001,
  corr_weight = 0,
  n_epochs = 500L,
  batch_size = 256L,
  neg_sample_rate = 5L
)

Arguments

Value

A named list with the following elements:

• local_connectivity - Numeric. Number of nearest neighbours assumed to be at distance zero. Defaults to 1.0.

• bandwidth - Numeric. Convergence tolerance for smooth kNN distance binary search. Defaults to 1e-05.

• mix_weight - Numeric. Balance between fuzzy union and directed graph during symmetrisation. Defaults to 1.0.

• hidden_layers - Integer vector. Hidden layer sizes for the MLP encoder. Defaults to c(128L, 64L, 32L).

• lr - Numeric. Learning rate for the neural network optimiser. Defaults to 0.001.

• corr_weight - Numeric. Coefficient for the negative Pearson correlation loss that encourages similar distances in embedding and original space. Defaults to 0.0.

• n_epochs - Integer. Number of training epochs. Defaults to 500L.

• batch_size - Integer. Training batch size. Defaults to 256L.

• neg_sample_rate - Integer. Number of negative samples per positive edge. Defaults to 5L.

Description

GPU counterpart to bixverse::params_sc_bbknn(). Same BBKNN knobs, but the kNN block is the GPU one, see params_knn_gpu_defaults().

Usage

params_sc_bbknn_gpu(
  neighbours_within_batch = 3L,
  set_op_mix_ratio = 1,
  local_connectivity = 1,
  trim = NULL,
  knn = list()
)

Arguments

Details

Two keys of the GPU kNN block do nothing here and are rejected rather than silently ignored. k is set by neighbours_within_batch, and extract_knn only applies to a self-query, whereas BBKNN builds one index per batch and queries each with every cell.

Value

A named list with the following elements:

• neighbours_within_batch - Integer. Number of neighbours to consider per batch. Defaults to 3L.

• set_op_mix_ratio - Numeric. Mixing ratio between union (1.0) and intersection (0.0). Defaults to 1.0.

• local_connectivity - Numeric. UMAP connectivity computation parameter, how many nearest neighbours of each cell are assumed to be fully connected. Defaults to 1.0.

• trim - Integer or NULL. Trim the neighbours of each cell to these many top connectivities. May help with population independence and improve the tidiness of clustering. If NULL, it defaults to 10 * neighbours_within_batch. Defaults to NULL.

• The elements of params_knn_gpu_defaults(), overridden by knn, spliced in at this position.

References

Polański, et al., Bioinformatics, 2020

Description

GPU counterpart to bixverse::params_sc_fast_cluster(). The mini-batch k-means knobs are gone (the GPU k-means is full-batch Lloyd's) and the k-means block comes from the GPU parameters instead. Two knobs the CPU wrapper never exposed, same_weight and multi_level_louvain, are available here. The k-means distance is taken from knn$ann_dist, so the coarsening and the centroid graph agree on the geometry. There is no separate metric argument, and "manhattan" is not supported by the GPU k-means.

Usage

params_sc_fast_cluster_gpu(
  k_means_iter = 50L,
  k_means_init = NULL,
  fixed = TRUE,
  quantise = FALSE,
  same_weight = FALSE,
  full_snn = FALSE,
  pruning = NULL,
  snn_similarity = c("jaccard", "rank"),
  cell_mediated = FALSE,
  n_anchors = 5L,
  louvain_iters = 10L,
  multi_level_louvain = TRUE,
  knn = list(k = 5L)
)

Arguments

Value

A named list with the following elements:

• k_means_iter - Integer. Maximum number of k-means iterations. Defaults to 50L.

• k_means_init - String or NULL. Initialisation method. One of "random", "parallel" or "plusplus". If NULL, picked on the Rust side based on the number of centroids. Defaults to NULL.

• fixed - Boolean. Shall k-means run for a fixed number of iterations, without checking for convergence. Defaults to TRUE.

• quantise - Boolean. Shall the data buffer be held at fp16 on the GPU. Halves the buffer and helps when the assignment kernels are memory bound. Defaults to FALSE.

• same_weight - Boolean. If TRUE, all kNN edges get weight 1.0. Otherwise edges with a reverse counterpart are double counted. Defaults to FALSE.

• full_snn - Boolean. Shall the full shared nearest neighbour graph be generated, including edges between centroids that are not neighbours. Defaults to FALSE.

• pruning - Numeric or NULL. Weights below this threshold are set to 0 when generating the sNN graph. If NULL, defaults to 1 / ceiling(k * 0.8). Defaults to NULL.

• snn_similarity - String. Jaccard computes the Jaccard index between neighbour sets; rank weights edges by the best combined rank of a shared neighbour. Both are normalised to ⁠[0, 1]⁠. One of c("jaccard", "rank"). Defaults to "jaccard".

• cell_mediated - Boolean. Build the centroid graph from the cells instead of a kNN search over the centroids: every cell links its n_anchors nearest centroids, so two centroids are connected when cells sit near both. If TRUE, snn and the sNN settings are ignored. Defaults to FALSE.

• n_anchors - Integer. Number of nearest centroids each cell links to in the cell-mediated graph. Clamped to the number of centroids. Defaults to 5L.

• louvain_iters - Integer. Number of Louvain iterations. Defaults to 10L.

• multi_level_louvain - Boolean. Shall multi-level Louvain be applied. Defaults to TRUE.

• The elements of the base list, overridden by knn, spliced in at this position.

Description

GPU counterpart to bixverse::params_sc_fastmnn(). Same fastMNN knobs minus the PCA ones, since the GPU path corrects the PCA already stored in the object. The kNN block is the GPU one, see params_knn_gpu_defaults(), with k and ann_dist defaulting to the CPU values.

Usage

params_sc_fastmnn_gpu(ndist = 3, cos_norm = TRUE, knn = list())

Arguments

Details

extract_knn is rejected rather than silently ignored: every search in fastMNN is a cross-query between two sets of cells, and extraction only applies to a self-query. k = 0L is rejected as well, since fastMNN has no data-driven fallback for it.

Value

A named list with the following elements:

• ndist - Numeric. Number of median distances for the tricube kernel bandwidth. Defaults to 3.0.

• cos_norm - Boolean. Apply cosine normalisation before computing distances. Defaults to TRUE.

• The elements of params_knn_gpu_defaults(), overridden by knn, spliced in at this position.

References

Haghverdi, et al., Nat Biotechnol, 2018

Description

Default parameters for Harmony v2 GPU batch correction

Usage

params_sc_harmony_v2_gpu(
  k = NULL,
  sigma = 0.1,
  theta = 2,
  lambda = 1,
  max_iter_kmeans = 4L,
  max_iter_harmony = 10L,
  epsilon_kmeans = 0.001,
  epsilon_harmony = 0.01,
  window_size = 3L,
  alpha = 0.2,
  tau = 0,
  batch_proportion_cutoff = 1e-05,
  use_dynamic_lambda = FALSE,
  csr_cube_count = 256L,
  k_means_iter = 10L,
  k_means_init = NULL,
  fixed = FALSE,
  quantise = FALSE
)

Arguments

Value

A named list with the following elements:

• k - Integer or NULL. Number of clusters for k-means clustering. If not provided, it will be automatically determined as min(round(N / 30), 100). Defaults to NULL.

• sigma - Numeric vector. Per-cluster diversity weights. Either a single value (broadcast to all clusters) or a vector of length k. Defaults to 0.1.

• theta - Numeric vector. Per-variable diversity penalty. Must be a single value; only one batch covariate is supported on the GPU path. Defaults to 2.0.

• lambda - Numeric vector. Ridge regression penalty for the linear model. Typically a single value. Ignored when use_dynamic_lambda = TRUE. Defaults to 1.0.

• max_iter_kmeans - Integer. Maximum number of k-means Jacobi sweeps per Harmony round. Defaults to 4L.

• max_iter_harmony - Integer. Maximum number of Harmony outer iterations. Defaults to 10L.

• epsilon_kmeans - Numeric. Convergence threshold for k-means clustering. Defaults to 0.001.

• epsilon_harmony - Numeric. Convergence threshold for Harmony. Defaults to 0.01.

• window_size - Integer. Number of previous iterations to consider when checking convergence. Defaults to 3L.

• alpha - Numeric. Scaling factor for dynamic lambda estimation. Must be in (0, 1). Only relevant when use_dynamic_lambda = TRUE. Defaults to 0.2.

• tau - Numeric. Scaling factor for theta based on batch size. A value of 0 disables batch-size scaling of theta. Defaults to 0.0.

• batch_proportion_cutoff - Numeric. Cutoff for pruning batches with small proportions during ridge regression. Defaults to 1e-05.

• use_dynamic_lambda - Boolean. If TRUE, lambda is estimated dynamically per cluster instead of using the fixed lambda value. Defaults to FALSE.

• csr_cube_count - Integer. Number of parallel thread groups used when building the level-CSR index on the GPU. Adjust for your hardware if needed. Defaults to 256L.

• k_means_iter - Integer. Maximum number of k-means iterations for the initial centroid computation. Defaults to 10L.

• k_means_init - String or NULL. Initialisation strategy for k-means. Defaults to NULL.

• fixed - Boolean. If TRUE, centroids are fixed after initialisation. Defaults to FALSE.

• quantise - Boolean. If TRUE, quantises intermediate values to f16 during k-means. Defaults to FALSE.

Description

GPU counterpart to bixverse::params_scrublet(). Two differences from the CPU list. The pca sub-list is gone: the GPU SVD is always randomised, so svd_solver has nothing to switch and no_pcs is a plain argument. And the kNN block is backend dependent, see knn_backend.

Usage

params_scrublet_gpu(
  sim_doublet_ratio = 1.5,
  expected_doublet_rate = 0.1,
  stdev_doublet_rate = 0.02,
  n_bins_histogram = 100L,
  manual_threshold = NULL,
  no_pcs = 30L,
  normalisation = list(),
  hvg = list(),
  knn_backend = c("gpu", "cpu"),
  knn = list(k = 0L)
)

Arguments

Details

Leave knn_method alone unless you have a reason. "exhaustive" is the default and is the right answer for Scrublet on the GPU arm.

Scrublet queries at a high k by construction: the count is taken over an embedding (1 + sim_doublet_ratio) * n_cells rows tall, and k = 0L then scales k by the same factor, so a 20k-cell run searches at k around 175. Exhaustive barely notices k, since the scan is the cost and k only sizes the top-k selection. NN-descent notices a lot: its build degree tracks k, so the descent does more work per node as k climbs. "ivf" is the one worth trying: it was the quickest of the three across that sweep and holds a Pearson above 0.99 against exhaustive.

Recall matters more here than elsewhere. The doublet score is a neighbour count, so a backend that drops neighbours biases every score downwards.

Value

A flat named list with all GPU Scrublet parameters.

References

Wolock, et al., Cell Syst, 2020

Description

Wrapper function to generate t-SNE parameters (GPU version)

Usage

params_tsne_gpu(
  lr = NULL,
  n_epochs = 1000L,
  early_exag_iter = 250L,
  early_exag_factor = 12,
  late_exag_factor = NULL,
  theta = 0.5,
  n_interp_points = 3L,
  max_depth = 7L,
  init = c("pca", "spectral", "random"),
  randomised = TRUE
)

Arguments

Value

A named list with the following elements:

• lr - Numeric or NULL. Learning rate. If NULL (the default), the Rust backend sets it to max((n_samples / 12), 200), following the N-dependent heuristic of Belkina et al. (2019). Defaults to NULL.

• n_epochs - Integer. Number of optimisation epochs. Defaults to 1000L.

• early_exag_iter - Integer. Number of early exaggeration iterations. Defaults to 250L.

• early_exag_factor - Numeric. Early exaggeration factor. Defaults to 12.0.

• late_exag_factor - Numeric or NULL. If you wish to also use late exaggerations. Can be useful on large data sets (set it to 2.0 to 4.0). Defaults to NULL.

• theta - Numeric. Barnes-Hut approximation angle. Lower values increase accuracy at the cost of speed. Defaults to 0.5.

• n_interp_points - Integer. Number of interpolation points per grid cell for FFT acceleration ("fft", "fft_3k" and "fft_3k_gpu"). Defaults to 3L.

• max_depth - Integer. Maximum Barnes-Hut tree depth for the quick-and-dirty optimiser ("bh_qd"). Smaller is faster and coarser; qdtsne recommends 7 to 10. No effect on the other optimisers. Defaults to 7L.

• init - String. Embedding initialisation method. One of c("pca", "spectral", "random"). Defaults to "pca".

• randomised - Boolean. Use randomised SVD for PCA initialisation. Defaults to TRUE.

References

Belkina, et al., Nat. Commun., 2019

Description

Wrapper function to generate UMAP parameters (GPU version)

Usage

params_umap_gpu(
  local_connectivity = 1,
  bandwidth = 1e-05,
  mix_weight = 1,
  lr = 1,
  n_epochs = NULL,
  neg_sample_rate = 5L,
  gamma = 1,
  optimiser = c("adam_gpu", "adam_parallel", "sgd", "adam"),
  init = c("spectral", "pca", "random"),
  randomised = FALSE
)

Arguments

Value

A named list with the following elements:

• local_connectivity - Numeric. Number of nearest neighbours assumed to be at distance zero. Defaults to 1.0.

• bandwidth - Numeric. Convergence tolerance for smooth kNN distance binary search. Defaults to 1e-05.

• mix_weight - Numeric. Balance between fuzzy union and directed graph during symmetrisation. Defaults to 1.0.

• lr - Numeric. Learning rate. Defaults to 1.0.

• n_epochs - Integer or NULL. Number of optimisation epochs. Defaults to NULL.

• neg_sample_rate - Integer. Number of negative samples per positive sample. Defaults to 5L.

• gamma - Numeric. Repulsion strength. Defaults to 1.0.

• optimiser - String. The optimiser for the embedding. One of c("adam_gpu", "adam_parallel", "sgd", "adam"). Defaults to "adam_gpu".

• init - String. Embedding initialisation method. One of c("spectral", "pca", "random"). Defaults to "spectral".

• randomised - Boolean. Use randomised SVD for PCA initialisation. Defaults to FALSE.

Description

Predict embeddings for new data using a trained parametric UMAP model

Usage

## S3 method for class 'ParametricUmapModel'
predict(object, newdata, ...)

Arguments

Value

A numerical matrix with dimensions samples x n_dim.

Description

GPU-accelerated pairwise column correlations. Has the options of Pearson and Spearman correlation coefficient calculations.

Usage

rs_cor_gpu(x, spearman, backend = "wgpu", verbose)

Arguments

Value

The correlation matrix

Description

GPU-accelerated pairwise column co-variance calculation.

Usage

rs_cov_gpu(x, backend = "wgpu", verbose)

Arguments

Value

The covariance matrix

Description

GPU equivalent of bixverse::rs_mnn, implementing the fast mutual nearest neighbour correction from Haghverdi, et al. The MNN searches and the tricube neighbour search run on the WGPU backend; everything else is shared with the CPU implementation.

Usage

rs_fast_mnn_gpu(embd, batch_labels, fastmnn_params, seed, verbose)

Arguments

Value

The batch-corrected embedding, cells x dimensions, in the input cell order.

Description

Probes for a WGPU adapter by initialising the same client every GPU function in this package goes through, so a TRUE here means those functions will actually run rather than that a device merely exists. The result is cached for the session and the client stays warm, so the first real call after a successful probe skips the setup cost.

Usage

rs_gpu_available()

Value

Boolean. TRUE when a WGPU adapter could be initialised.

Description

Builds a kNN graph from an embedding matrix on the wgpu backend. Three searches are available: an exact brute-force scan, an IVF index that probes a subset of Voronoi cells, and a CAGRA-style NNDescent graph that is either beam searched or handed back as the descent left it.

Euclidean distances come back as true L2, not squared.

Usage

rs_gpu_knn(embd, k, knn_method, nn_params, seed, backend = "wgpu", verbose)

Arguments

Value

A named list with:

• indices - Integer matrix of shape cells x k with 0-based neighbour indices.

• dist - Numeric matrix of shape cells x k with distances to the neighbours.

• dist_metric - Character. The distance metric used.

Description

Advertising plane operations is not enough: the paravirtualised GPU of a macOS VM, as on the macos-15-intel GitHub runners, reports planes of 4 to 64 lanes but silently drops every dispatch that uses one. This launches a single plane reduction and checks the answer. The result is cached for the session.

Usage

rs_gpu_plane_ops()

Value

Boolean. TRUE when a GPU adapter is present and a plane reduction on it returns the plane width.

Description

This function implements the GPU-accelerated version 2 Harmony algorithm from Patikas, et al., 2026. Only a single batch covariate is supported.

Usage

rs_harmony_v2_gpu(
  pca,
  harmony_params,
  batch_labels,
  seed,
  backend = "wgpu",
  verbose
)

Arguments

Value

The batch-corrected Harmony (v2) embedding space.

Description

A GPU-accelerated k-means version leveraging the wgpu backend via cubecl.

Usage

rs_kmeans_gpu(data, dist, n_centroids, kmeans_params, seed, verbose)

Arguments

Value

A list with

• centoids - The centroids matrix (centroids x features)

• assignments - The cluster assignments of the data. (1-indexed.)

Description

Trains a neural network encoder to learn a mapping from the input space to a low-dimensional embedding that preserves the UMAP graph structure. Supports both GPU (wgpu) and CPU (burn flex CPU) backends. For small to medium data sets (fewer than ~10k samples or narrow hidden layers), the CPU backend is typically faster owing to GPU kernel dispatch overhead.

Usage

rs_parametric_umap(
  data,
  n_dim,
  k,
  min_dist,
  spread,
  parametric_params,
  seed,
  verbose,
  use_gpu
)

Arguments

Value

A named list with two elements: embedding (numerical matrix of dimensions samples x n_dim) and model (external pointer to the trained encoder for use with rs_parametric_umap_predict).

Description

Runs forward inference through the trained encoder network. The prediction automatically uses whichever backend (GPU or CPU) the model was trained on.

Usage

rs_parametric_umap_predict(model, data)

Arguments

Value

Numerical matrix of dimensions samples x n_dim with the predicted embeddings.

Description

Wraps the tSNE implementation in manifolds-rs. "fft_3k_gpu" runs the optimiser on the GPU; "bh", "bh_qd", "fft" and "fft_3k" keep it on the CPU. This version takes a pre-computed kNN graph, please see new_nearest_neighbour().

Usage

rs_tsne_from_knn_gpu(
  embd,
  knn_data,
  n_dim,
  perplexity,
  approx_type,
  tsne_params,
  seed,
  use_high_precision,
  backend = "wgpu",
  verbose
)

Arguments

Value

The tSNE embeddings.

Description

Wraps the tSNE implementation in manifolds-rs. The kNN search runs on the GPU. "fft_3k_gpu" runs the optimiser on the GPU as well; "bh", "bh_qd", "fft" and "fft_3k" keep it on the CPU.

Usage

rs_tsne_gpu(
  embd,
  n_dim,
  perplexity,
  approx_type,
  tsne_params,
  seed,
  use_high_precision,
  backend = "wgpu",
  verbose
)

Arguments

Value

The tSNE embeddings.

Description

This is the wrapper function into the Rust interface for UMAP and takes a pre-computed kNN graph, skipping the graph build. GPU acceleration applies to the optimisation.

Usage

rs_umap_from_knn_gpu(
  embd,
  knn_data,
  n_dim,
  min_dist,
  spread,
  k,
  umap_params,
  seed,
  use_high_precision,
  backend = "wgpu",
  verbose
)

Arguments

Value

The UMAP embeddings.

Description

This is the wrapper function into the Rust interface for GPU-accelerated UMAP. Leverages GPU acceleration in the kNN search and also in the optimisation.

Usage

rs_umap_gpu(
  embd,
  n_dim,
  min_dist,
  spread,
  k,
  umap_params,
  seed,
  use_high_precision,
  backend = "wgpu",
  verbose
)

Arguments

Value

The UMAP embeddings.

Description

Save a parametric UMAP as a qs2 file

Usage

save_parametric_umap(model, path)

Arguments

Value

Saves the file to the provided path.

Description

GPU counterpart of bixverse::scenic_grn_sc(). Runs multi-output tree regression on the WGPU backend and returns a ScenicGrn object. Dispatches on SingleCells (disk-backed .bin counts) or MetaCells (in-memory sparse) from the bixverse package. GBM is not supported on GPU; use the CPU version for learner_type = "grnboost2".

If genes_to_take is NULL, the CPU bixverse::scenic_gene_filter_sc() is used to shortlist targets (cheap min-counts / min-cells scan).

Usage

scenic_grn_sc_gpu(
  object,
  tf_ids,
  scenic_params = bixverse::params_scenic(),
  wave_byte_budget = 4 * 1024^3,
  genes_to_take = NULL,
  cells_to_take = NULL,
  streaming = NULL,
  random_seed = 42L,
  .verbose = TRUE
)

Arguments

Value

A ScenicGrn object with the gene x TF importance matrix.

References

Aibar et al., Nat Methods, 2017.

Description

GPU counterpart of bixverse::scrublet_sc(). Three stages run on the WGPU backend: the randomised sparse SVD of the observed cells, the projection of the simulated doublets into that PC space, and the kNN over the combined embedding. HVG selection, doublet simulation, the kNN classifier and the Otsu threshold stay on the CPU, so the speedup tracks how much of the run the SVD and the kNN own. That share grows with cell count: the combined embedding is (1 + sim_doublet_ratio) * n_cells rows tall and an exhaustive kNN over it is quadratic.

Usage

scrublet_gpu_sc(
  object,
  scrublet_params = params_scrublet_gpu(),
  seed = 42L,
  streaming = NULL,
  cells_to_use = NULL,
  group_by = NULL,
  return_combined_pca = FALSE,
  return_pairs = FALSE,
  .verbose = TRUE
)

Arguments

Details

Scores do not match the CPU bit for bit. The SVD is randomised on both sides but draws a different sketch, and the GPU indices break neighbour ties differently. Expect a correlation around 0.99 rather than equality, and a handful of borderline calls to flip because Otsu's threshold is a step function of the histogram bins.

Value

A ScrubletRes S3 object, identical in shape to the CPU one, with the following items:

• predicted_doublets - Boolean vector indicating which observed cells were predicted as doublets (TRUE = doublet, FALSE = singlet).

• doublet_scores_obs - Numerical vector with the likelihood of being a doublet for the observed cells.

• doublet_scores_sim - Numerical vector with the likelihood of being a doublet for the simulated cells.

• doublet_errors_obs - Numerical vector with the standard errors of the scores for the observed cells.

• z_scores - Z-scores for the observed cells. Represents: score - threshold / error.

• threshold - Used threshold.

• detected_doublet_rate - Fraction of cells that are called as doublet.

• detectable_doublet_fraction - Fraction of simulated doublets with scores above the threshold.

• overall_doublet_rate - Estimated overall doublet rate.

• pca - Optional PCA embeddings across the original cells and simulated doublets.

• pair_1 - Optional index of the parent cell 1 of the simulated doublets.

• pair_2 - Optional index of the parent cell 2 of the simulated doublets.

The 0-indexed cell indices are attached as the cell_indices attribute. Grouped runs additionally carry grouped and group_by_col attributes and a cell_groups element.

References

Wolock, et al., Cell Syst, 2020

Description

GPU counterpart of bixverse::stabilised_nmf_sc(). Runs n_runs HALS NMF with random initialisations seeded by seed + i. The nmf_init field in nmf_hals_params is ignored; random init is always used.

The counts upload once and serve every restart, but the restarts themselves run one after the other on the single device, where the CPU version spreads them across cores. On a small matrix the CPU can still win.

Usage

stabilised_nmf_gpu_sc(
  object,
  k,
  cell_ids = NULL,
  gene_ids = NULL,
  preprocessing = "none",
  use_second_layer = TRUE,
  nmf_hals_params = bixverse::params_nmf_hals(),
  n_runs = 30L,
  seed = 42L,
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Value

A StabilisedNmfResult object, the same class bixverse::stabilised_nmf_sc() returns.

Description

Performs t-SNE dimensionality reduction on the input data. The kNN search runs on the GPU. With the default "fft_3k_gpu" the optimiser runs on the GPU as well, so the whole embedding stays on the device; the other approximations optimise on the CPU.

Usage

tsne_gpu(
  data,
  knn = NULL,
  n_dim = 2L,
  perplexity = 20,
  approx_type = c("fft_3k_gpu", "bh", "bh_qd", "fft", "fft_3k"),
  knn_method = c("ivf", "exhaustive", "nndescent"),
  nn_params = params_nn_gpu(),
  tsne_params = params_tsne_gpu(),
  seed = 42L,
  use_high_precision = NULL,
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Details

The number of neighbours is derived from perplexity on the Rust side following the usual 3 * perplexity convention.

Value

A numerical matrix with dimensions samples x n_dim containing the t-SNE embedding.

Description

GPU-accelerated counterpart to bixverse::tsne_sc(). Runs tsne_gpu() on an embedding pulled from the object. The kNN runs on the GPU; with the default "fft_3k_gpu" the optimiser does too.

t-SNE derives the number of neighbours from perplexity on the Rust side (the usual 3 * perplexity convention). To avoid a silent mismatch with the cached kNN, use_knn defaults to FALSE: every call generates a fresh GPU kNN sized to the requested perplexity. Handy for sweeping perplexities since the kNN is cheap on GPU.

Usage

tsne_gpu_sc(
  object,
  use_knn = FALSE,
  embd_to_use = "pca",
  slot_name = "tsne",
  no_embd_to_use = NULL,
  modality = c("rna", "adt", "wnn"),
  n_dim = 2L,
  perplexity = 20,
  approx_type = c("fft_3k_gpu", "bh", "bh_qd", "fft", "fft_3k"),
  knn_method = c("ivf", "exhaustive", "nndescent"),
  nn_params = params_nn_gpu(),
  tsne_params = params_tsne_gpu(),
  seed = 42L,
  use_high_precision = NULL,
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Value

The object with a "tsne" embedding added. If the requested embedding is missing, returns the object unchanged with a warning.

See Also

tsne_gpu(), bixverse::tsne_sc(), umap_gpu_sc()

Description

Performs UMAP dimensionality reduction on the input data. This function provides a user-friendly interface with input validation before calling the Rust implementation. Leverages GPU-accelerated kNN searches and in the default setting also uses a GPU-accelerated Adam optimiser for the embedding.

Usage

umap_gpu(
  data,
  knn = NULL,
  n_dim = 2L,
  k = 15L,
  min_dist = 0.5,
  spread = 1,
  knn_method = c("nndescent", "exhaustive", "ivf"),
  nn_params = params_nn_gpu(),
  umap_params = params_umap_gpu(),
  seed = 42L,
  use_high_precision = NULL,
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Value

A numerical matrix with dimensions samples x n_dim containing the UMAP embedding.

Description

GPU-accelerated counterpart to bixverse::umap_sc(). Pulls an embedding (defaulting to PCA) off the object, runs umap_gpu() on it (GPU kNN plus GPU Adam optimiser by default), and writes the resulting embedding back into sc_cache$other_embeddings[[slot_name]].

When use_knn = TRUE (the default), the kNN graph already stored on the object is reused via bixverse::sc_knn_to_nearest_neighbours(). Otherwise a fresh GPU kNN is built from the chosen embedding.

Usage

umap_gpu_sc(
  object,
  use_knn = TRUE,
  embd_to_use = "pca",
  slot_name = "umap",
  no_embd_to_use = NULL,
  modality = c("rna", "adt", "wnn"),
  n_dim = 2L,
  k = 15L,
  min_dist = 0.5,
  spread = 1,
  knn_method = c("nndescent", "exhaustive", "ivf"),
  nn_params = params_nn_gpu(),
  umap_params = params_umap_gpu(),
  seed = 42L,
  use_high_precision = NULL,
  backend = c("wgpu", "mlx"),
  .verbose = TRUE
)

Arguments

Value

The object with a "umap" embedding added. If the requested embedding is missing, returns the object unchanged with a warning.

See Also

umap_gpu(), bixverse::umap_sc(), tsne_gpu_sc()