Skip to contents

Sweep k for consensus NMF on the GPU over single cell or meta cell data

nmf_k_sweep_gpu_sc.Rd

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,
  .verbose = TRUE
)

Arguments

object

SingleCells or MetaCells class from bixverse.

k_range

Integer vector. The ranks to evaluate. Every entry at least 2 and at most 128, see NMF_GPU_MAX_RANK.

cell_ids

Optional character. Cell ids (or meta cell ids) to restrict the NMF to. If NULL, uses bixverse::get_cells_to_keep() for SingleCells and all meta cells for MetaCells.

gene_ids

Optional character. Gene ids to restrict the NMF to. If NULL, uses bixverse::get_hvg() on the object.

preprocessing

String. One of c("none", "sd", "sqrt_sd").

use_second_layer

Boolean. If TRUE, runs NMF on the normalised counts (recommended); if FALSE, on the raw counts.

nmf_hals_params

List, see bixverse::params_nmf_hals(). The nmf_init field is ignored, restarts always use random initialisation.

nmf_consensus_params

List, see bixverse::params_nmf_consensus().

n_runs

Integer. Number of restarts. At least 2.

seed

Integer. Random seed for initialisation.

.verbose

Boolean or integer. Controls verbosity. FALSE -> quiet, TRUE or 1L -> normal verbosity, 2L -> detailed verbosity.

Value

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

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.

References

Kotliar et al., eLife, 2019