Run consensus NMF (cNMF) to discover gene expression programs

Wraps the dylkot/cNMF pipeline (Kotliar et al. 2019) through reticulate: prepare (high-variance gene selection + normalization), factorize (the heavy NMF replication step), combine, and the k_selection_plot diagnostic. cNMF is inherently a two-stage, human-in-the-loop method: run this function, inspect the k-selection plot it writes, choose the number of programs k, then call GetCNMFPrograms to extract the consensus result for that K.

cNMF is a Python package, not an R dependency. Install it once (pip install cnmf) and point this function at the environment with conda_env or python.

Usage

RunCNMF(
  seurat_object,
  assay = NULL,
  name = "cnmf",
  output_dir = NULL,
  k_range = 5:15,
  n_iter = 100L,
  num_highvar_genes = 2000L,
  genes_use = NULL,
  batch.by = NULL,
  seed = 14L,
  n_workers = 1L,
  conda_env = NULL,
  python = NULL,
  resume = FALSE,
  caffeinate = FALSE,
  show_plot = TRUE
)

Arguments

seurat_object: A Seurat object containing raw counts.
assay: Character or NULL. Assay to pull counts from. NULL uses the default assay.
name: Character. Run name; cNMF writes all output under output_dir/name/. Default "cnmf".
output_dir: Character or NULL. Output directory. Walks up to the output_dir stored by PrepObject when NULL.
k_range: Integer vector. Candidate numbers of programs (K) to factorize across. Default 5:15.
n_iter: Integer. NMF replicates per K. Default 100L. Higher is more robust and much slower.
num_highvar_genes: Integer. Number of overdispersed genes cNMF selects for factorization. Default 2000L. Ignored when genes_use is supplied.
genes_use: Character vector or NULL. Optional precomputed gene set to restrict the input to (bypasses cNMF's own high-variance selection). Ignored when batch.by is set.
batch.by: Character vector or NULL. One or more meta.data columns to correct for batch effects before factorization. When supplied, cNMF's Preprocess Harmony-corrects the counts on these variables, learns program usages on the corrected data, and re-fits spectra on the uncorrected TP10K data (Kotliar batch-correction workflow). Requires the Python package harmonypy in the environment. NULL (default) runs without batch correction.
seed: Integer. Random seed for reproducibility. Default 14L.
n_workers: Integer. Number of cNMF worker processes to run the factorize step in parallel. Default 1L (single, in-process). When > 1, the env's cnmf command is launched once per worker and the (K x iteration) jobs are split across them; set this to the number of cores you can spare. Each worker writes a <name>.factorize.worker_<i>.log in output_dir.
conda_env: Character or NULL. Name of the conda environment that has cnmf installed.
python: Character or NULL. Path to a Python interpreter with cnmf installed (alternative to conda_env).
resume: Logical. If TRUE, reuse work already on disk: a completed factorization (skip prepare/factorize/combine), and on the batch-correction path the existing Harmony-corrected files (skip the expensive correction step, e.g. to recover a run that crashed after Harmony). Default FALSE.
caffeinate: Logical. Prevent the machine from sleeping during the run (macOS). Default FALSE.
show_plot: Logical. Display the k-selection plot in the active graphics device (e.g. the RStudio Plots pane) when finished. Default TRUE. Requires the png (preferred) or magick package.

Value

The input Seurat object with run metadata stored in seurat_object@misc$cnmf. The k-selection plot is written to output_dir/name/ with a .legend sidecar, and an analysis_params.json (parameters plus a draft methods paragraph) is written to output_dir for create_analysis_pptx.

Details

Parallelism. Factorization runtime scales with n_iter * length(k_range) (e.g. the defaults are 100 x 11 = 1100 NMF fits), not with object size. Set n_workers > 1 to split those fits across parallel cNMF worker processes on a multi-core machine. For cluster-scale runs, cNMF's command-line workflow can distribute the same workers across jobs; see the cNMF documentation.

References