cellink.tl.external.compute_nmf_programs

cellink.tl.external.compute_nmf_programs(adata, *, n_components=None, n_extra=10, celltype_col='cell_type', layer='counts', normalize=True, random_state=0, device='cuda', prefix='nmf', out_dir=None, save=True)

Compute NMF cellular process programs (single healthy tissue).

Parameters:

• adata (AnnData) – AnnData. Raw counts preferred (from layer or adata.X).

• n_components (int | None (default: None)) – Number of NMF factors. Defaults to n_cell_types + n_extra.

• n_extra (int (default: 10)) – Added to the number of annotated cell types when auto-setting components.

• celltype_col (str (default: 'cell_type')) – Column in adata.obs for auto-setting n_components.

• layer (str | None (default: 'counts')) – Layer to use. If None, uses adata.X.

• normalize (bool (default: True)) – Divide each matrix by its global maximum (as in original sc-linker).

• random_state (int (default: 0)) – NMF random seed.

• device (str, default "cuda") –

  Device for torchnmf backend: "cuda" or "cpu".

  • "cuda" — uses GPU if available, raises a clear warning if CUDA is not found and falls back to CPU.

  • "cpu" — forces CPU even if a GPU is present.

  If torchnmf is not installed at all, cellink logs an install hint and falls back to sklearn NMF (which is slower but always available).

• prefix (str (default: 'nmf')) – File name prefix for output CSVs.

• out_dir (str | Path | None (default: None)) – Directory for output CSVs.

• save (bool (default: True)) – Whether to save CSVs.

Return type:

tuple[DataFrame, DataFrame, DataFrame]

Returns:

-W (DataFrame)

Cell x factor (cell programs), index = obs_names.

-H (DataFrame)

Gene x factor (gene programs), index = var_names.

-corr (DataFrame)

Gene x factor (Pearson correlation between gene expression and W scores).

Notes

Backend priority:

1. torchnmf (GPU or CPU), install with pip install torchnmf. On large matrices (>50k cells) this is 5-20x faster than sklearn.

2. sklearn NMF with init='nndsvda' + solver='cd'. Significantly faster than init='random' but still slow on very large matrices.