kaleidocell.merge_meta_programs#

kaleidocell.merge_meta_programs(result_dict, merge_groups, verbose=True)[source]#

Merge two or more meta-programs into a single consensus program.

For each merge group the function:

  1. Normalises each constituent MP’s gene-weight series to sum to 1, so all MPs contribute equally regardless of absolute scale.

  2. Averages the normalised weights gene-by-gene — genes absent in a constituent MP are treated as 0. Genes shared across more constituents therefore receive higher averaged weights, naturally surfacing the cross-MP consensus signature.

  3. Pools the underlying NMF program lists from all constituent clusters into one merged cluster.

  4. Re-sorts the cosine-similarity matrix so the merged cluster’s programs are contiguous (required for correct heatmap rendering and metric computation).

  5. Recomputes all quality metrics (silhouette, meanSimilarity, sampleCoverage, nPrograms, nGenes) for the updated MP set.

The merged MP takes the name of the first MP in each group. The original result_dict is not modified.

Constraints#

  • Each merge group must contain at least two MP names.

  • An MP may not appear in more than one merge group.

param result_dict:

Output of derive_nmf_metaprograms().

type result_dict:

dict

param merge_groups:

Each inner list names the MPs to merge, e.g. [['MP1', 'MP2'], ['MP4', 'MP5', 'MP6']].

type merge_groups:

list of list of str

param verbose:

Print per-group merge summary (programs, genes, shared-gene count) and total MP count after merging.

type verbose:

bool, default True

returns:

  • merged_names (list of str) – Names of the newly created merged MPs (one per group, equal to the first element of each group).

  • result_dict_merged (dict) – Deep copy of result_dict with all merges applied and metrics recomputed.

Examples

Merge two groups simultaneously:

>>> merged_names, results_merged = kaleidocell.merge_meta_programs(
...     results_mp,
...     merge_groups=[['MP1', 'MP2'], ['MP4', 'MP5', 'MP6']],
... )
>>> # merged_names == ['MP1', 'MP4']
>>> # Inspect, then commit:
>>> results_mp = results_merged
Parameters:

  • result_dict (dict)

  • merge_groups (list)

  • verbose (bool)

Return type:

tuple