kaleidocell.multi_sample_nmf#

kaleidocell.multi_sample_nmf(adata, test_ranks=None, n_initializations=1, max_iterations=100, seed=123, stop_threshold=40, n_threads=1, specificity_normalize=True, neptune_run=None, batch_key='donor_id', show_progress=True, verbose=True)[source]#

Run NMF independently for each sample and collect gene loadings.

Iterates over every unique value in adata.obs[batch_key], runs multi_rank_nmf() on the corresponding subset, optionally applies specificity-weighted normalisation, and returns all per-sample loading DataFrames together with their convergence curves.

Parameters:

  • adata (AnnData) – Annotated data matrix. Must contain the column batch_key in adata.obs.

  • test_ranks (list of int, default [3, 4, 5, 6, 7, 8, 9]) – Factorization ranks to evaluate per sample.

  • n_initializations (int, default 1) – Number of random restarts per rank.

  • max_iterations (int, default 100) – Maximum multiplicative-update steps.

  • seed (int, default 123) – Random seed for reproducibility.

  • stop_threshold (int, default 40) – Early-stopping patience (consecutive stable exposures).

  • n_threads (int, default 1) – Reserved for future CPU thread control.

  • specificity_normalize (bool, default True) – Apply weighted_loadings() to each W matrix.

  • neptune_run (optional) – Neptune experiment-tracking object.

  • batch_key (str, default "donor_id") – adata.obs column that defines sample identity.

  • show_progress (bool, default True) – Display a global tqdm progress bar.

  • verbose (bool, default True) – Print status messages.

Returns:

  • nmf_programs (dict) – {sample_key: pd.DataFrame} — each DataFrame is genes × (all ranks × n_programs) with column names like "donor1_Sig10_1".

  • convergence_curves (dict) – {sample_key: {"ranks": [...], "curves": [...]}}