Skip to contents

Run Consensus Non-negative Matrix Factorization on SingleCellExperiment objects

Source: R/runConsensusNMF.R
runConsensusNMF.Rd

Performs consensus NMF (cNMF) by running multiple NMF iterations and combining results to identify stable gene expression programs. This approach increases robustness and accuracy compared to single NMF runs.

Usage

runConsensusNMF(
  x,
  k_range = 5:15,
  n_runs = 100,
  assay = "logcounts",
  name = "cNMF",
  subset_row = NULL,
  tol = 1e-05,
  maxit = 100,
  L1 = c(0, 0),
  seed = NULL,
  verbose = TRUE,
  n_cores = 1,
  ...
)

Arguments

x

A SingleCellExperiment or SpatialExperiment object

k_range

Integer vector, range of K values to test (default 5:15)

n_runs

Integer, number of NMF runs per K value (default 100)

assay

Character or integer, which assay to use (default "logcounts")

name

Character, name for storing results (default "cNMF")

subset_row

Vector specifying which features to use

tol

Numeric, tolerance for convergence (default 1e-5)

maxit

Integer, maximum iterations per run (default 100)

L1

Numeric vector of length 2, L1 regularization for [w, h] (default c(0,0))

seed

Integer, random seed for reproducibility

verbose

Logical, whether to print progress (default TRUE)

n_cores

Integer, number of cores for parallel processing (default 1)

...

Additional arguments passed to RcppML::nmf

Value

The input object with cNMF results stored in metadata(x)$cNMF and optimal usage matrix in reducedDims

Examples

# Single-cell example
library(scuttle)
sce <- mockSCE(ngenes = 500, ncells = 200)
sce <- logNormCounts(sce)
sce <- runConsensusNMF(sce, k_range = 5:10, n_runs = 20)
#> Running consensus NMF with k_range=5:10, n_runs=20
#> Processing k=5 (1/6)
#>   Stability: 0.001, Silhouette: 0.38
#> Processing k=6 (2/6)
#>   Stability: 0.001, Silhouette: 0.489
#> Processing k=7 (3/6)
#>   Stability: 0, Silhouette: 0.486
#> Processing k=8 (4/6)
#> Warning: Density filtering removed too many spectra, using all spectra
#>   Stability: 0.123, Silhouette: 0.882
#> Processing k=9 (5/6)
#>   Stability: 0.001, Silhouette: 0.478
#> Processing k=10 (6/6)
#>   Stability: 0.001, Silhouette: 0.454
#> Selected optimal k=8 based on combined method
#>   Stability: 0.123
#>   Silhouette: 0.882
#>   Reproducibility: 1
#> Consensus NMF completed. Optimal k=8
#> Results stored in metadata(x)$cNMF$cNMF
#> Optimal usage stored in reducedDim(x, 'cNMF')

# Access consensus results
geps <- getConsensusGEPs(sce)
usage <- getGEPUsage(sce)