kaleidocell.derive_nmf_metaprograms#

kaleidocell.derive_nmf_metaprograms(nmf_programs_dict, n_MP=None, cluster_method='hclust_opt', kmeans=True, save=False, save_path='', plot=False, verbose=True)[source]#

Derive consensus meta-programs (MPs) across all NMF programs.

Concatenates per-sample loading DataFrames, computes pairwise cosine similarity, clusters via hierarchical Ward linkage, and derives a consensus gene signature per cluster.

Parameters:

  • nmf_programs_dict (dict) – Output of multi_sample_nmf(); maps sample keys to gene × program DataFrames.

  • n_MP (int or None) – Number of meta-program clusters. When None the optimal value is estimated automatically via silhouette score.

  • cluster_method (str, default "hclust_opt") – Only "hclust_opt" (hierarchical Ward linkage) is currently supported.

  • kmeans (bool, default True) – Use KMeans-based consensus (_consensus_kmeans()) when True, otherwise use confidence-based consensus (_consensus_confidence()).

  • save (bool, default False) – Write the MP gene table to a CSV file.

  • save_path (str, default "") – Directory for the saved CSV (uses cwd when empty).

  • plot (bool, default False) – Draw the similarity heatmap inline.

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

Returns:

  • "cluster_dict" — {cluster_id: [program_names]}

  • "mp_dict" — {mp_name: pd.Series of gene weights}

  • "mp_df" — pd.DataFrame (genes × MPs)

  • "similarity_matrix_sorted" — cosine-similarity DataFrame sorted by cluster

  • "metrics" — pd.DataFrame of per-MP quality metrics

Return type:

dict with keys