kaleidocell.get_html#

kaleidocell.get_html(results_mp, adata, mp_scores=None, obs=None, gsea_sets=None, output_path='results/results.html', gene_name_col=None, gene_name_from_col=None, verbose=True)[source]#

Generate a self-contained tabbed HTML report of kaleidocell results.

Each section appears in its own tab so the user can navigate easily between views. The report is written to a single HTML file with all images embedded as base64 strings — no external resources are required to view it.

Tabs generated#

Heatmap

Cosine-similarity matrix coloured heatmap with cluster boundaries (always included).

UMAP scores (requires mp_scores)

All MP module scores overlaid on the UMAP embedding. UMAP is recomputed if not already present in adata.

GSEA — GO Biological Process (skipped if GMT file absent)

Enrichr bar plots per MP using the MSigDB C5 GO BP gene sets.

Genes

Scrollable per-MP gene tables (all genes with scores).

Violin plots (one tab per key in obs)

MP score distributions across the specified adata.obs column. Omitted when obs is None or empty.

param results_mp:

Output of derive_nmf_metaprograms().

type results_mp:

dict

param adata:

Dataset used for UMAP and violin-plot obs annotations.

type adata:

AnnData

param mp_scores:

Per-cell module scores from compute_mp_scores(). Required for the UMAP-scores and violin-plot tabs; those tabs are skipped when None.

type mp_scores:

pd.DataFrame or None

param obs:

adata.obs columns for which violin-plot tabs are generated (e.g. ['Treatment', 'donor']). Pass None or an empty list to omit violin plots entirely.

type obs:

list of str or None

param gsea_sets:

Mapping {label: gmt_path} overriding the default GMT files. Default:

{
    "GO Biological Process": "<pkg>/files/c5.go.bp.v2026.1.Hs.symbols.gmt",
}

Pass an empty dict {} to skip GSEA entirely.

type gsea_sets:

dict or None

param output_path:

Path for the generated HTML file. All other output files (PDFs, CSVs) are written to the same directory. Parent directories are created automatically.

type output_path:

str, default "results/results.html"

param gene_name_col:

Column in adata.var containing the gene names to display in the report (e.g. "gene_name" for HGNC symbols when the MP gene names are Ensembl IDs). When None gene names are shown as stored in results_mp.

type gene_name_col:

str or None

param gene_name_from_col:

Column in adata.var whose values match the current gene names in results_mp. Only used when gene_name_col is set. When None the current names are matched against adata.var.index.

type gene_name_from_col:

str or None

param verbose:

Print progress messages and a summary of written files.

type verbose:

bool, default True

returns:

  • str – Absolute path to the written HTML file.

  • Files written

  • ————-

  • results.html – Self-contained tabbed report (always).

  • heatmap.pdf – Cosine-similarity matrix (always).

  • umap_scores.pdf – MP scores on UMAP (requires mp_scores).

  • gsea_{label}.csv – Significant GSEA terms per GMT file (when GSEA runs successfully).

  • gsea_{label}_{MP}.pdf – GSEA bar plots, one PDF per MP per GMT file.

  • genes.csv – Long-format gene table: gene, mp, score (always).

  • violins_{obs_key}.pdf (one per figure/MP) – Violin plots per obs key (requires obs).

Examples

Minimal call — heatmap + genes only:

>>> path = kaleidocell.get_html(results_mp, adata)

Full report with UMAP, violins and GSEA:

>>> path = kaleidocell.get_html(
...     results_mp, adata,
...     mp_scores=mp_scores,
...     obs=['Treatment', 'donor'],
... )
>>> print(f"Report written to {path}")

Custom GMT files:

>>> path = kaleidocell.get_html(
...     results_mp, adata,
...     gsea_sets={"KEGG": "/path/to/kegg.gmt"},
... )
Parameters:

  • results_mp (dict)

  • mp_scores (DataFrame)

  • obs (list)

  • gsea_sets (dict)

  • output_path (str)

  • gene_name_col (str)

  • gene_name_from_col (str)

  • verbose (bool)

Return type:

str