{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "# Tutorial 5 — Running kaleidoCell on mouse data\n\nkaleidoCell is species-agnostic: the NMF decomposition and consensus meta-program\nderivation work identically regardless of the organism.  The only step that\nrequires species-specific input is **GSEA**, because gene-set databases must\nuse the same gene symbols as your data.\n\nThe bundled GMT files in kaleidoCell contain **human** (HGNC) gene symbols.  For a\nmouse dataset you have two options:\n\n| Option | When to use |\n|--------|-------------|\n| Skip GSEA entirely | You only need the meta-programs and the HTML report |\n| Supply a mouse GMT file | You want pathway enrichment for *Mus musculus* |\n\nThis tutorial walks through both options.  It also explains the difference\nbetween the two GSEA methods available in `run_gsea_pipeline`:\n\n| Method | Description |\n|--------|-------------|\n| `enrichr` (default) | Hypergeometric test on the top-N genes of each MP |\n| `prerank` | GSEA preranked — uses the full ranked gene list, more sensitive |\n\n**Dataset** — example mouse scRNA-seq cohort (`mouse.h5ad`),\nlog-normalised counts in `adata.X`."
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "## 0 · Imports and data preparation"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "outputs": [],
   "source": "import kaleidocell\nimport scanpy as sc\n\nadata = sc.read_h5ad('../data/mouse.h5ad')\nprint(adata)"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "## 1 · Run NMF on every sample\n\nThis step is identical to a human dataset — NMF has no species-specific logic."
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "outputs": [],
   "source": "results_nmf, nmf_convergence = kaleidocell.multi_sample_nmf(\n    adata,\n    batch_key='batch',\n    test_ranks=[4, 5, 6, 7, 8, 9],\n    n_initializations=10,\n    seed=42,\n)\n\nresults_mp = kaleidocell.derive_nmf_metaprograms(results_nmf)\n\nprint(f\"Derived {len(results_mp['mp_dict'])} meta-programs.\")"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "## 2 · Score cells by MP activity"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "outputs": [],
   "source": "mp_scores = kaleidocell.compute_mp_scores(results_mp, adata)\nmp_scores.head()"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "## 3 · Run GSEA with a mouse gene-set file\n\n### Obtaining mouse GMT files\n\nMouse gene-set collections are available from MSigDB:\n\n> **https://www.gsea-msigdb.org/gsea/msigdb/mouse/genesets.jsp**\n\nDownload the collection(s) you need (e.g. `mh.all.v2024.1.Mm.symbols.gmt` for\nmouse Hallmarks) and place the file(s) in a convenient location — here we\nassume `../data/mh.all.v2024.1.Mm.symbols.gmt`.\n\n### `enrichr` vs `prerank`\n\n`run_gsea_pipeline` supports two complementary methods, selected via the\n`method` parameter:\n\n**`enrichr`** (default)\n- Takes the **top N genes** of each meta-program (controlled by `n_top_genes`)\n- Runs a hypergeometric over-representation test against each gene set\n- Fast; well-suited when you trust the discrete gene signature\n\n**`prerank`**\n- Uses the **full ranked gene list** (all genes, sorted by NMF weight)\n- Runs GSEA preranked (Subramanian et al. 2005)\n- More sensitive to subtle pathway signals; slower\n- Recommended when the gene boundary between \"in\" and \"out\" is uncertain"
  },
  {
   "cell_type": "markdown",
   "source": "#### Option A — `enrichr` (hypergeometric, fast)",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "source": "gsea_results_enrichr, gsea_plots_enrichr = kaleidocell.run_gsea_pipeline(\n    results_mp,\n    from_file=['../data/mh.all.v2024.1.Mm.symbols.gmt'],\n    method='enrichr',        # hypergeometric over-representation test\n    n_top_genes=50,          # top genes per MP used as query\n    top_n_plot=6,\n    plot=True,\n    save_csv=False,\n)\n\ngsea_results_enrichr.head(20)",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "source": "#### Option B — `prerank` (full ranked list, more sensitive)",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "source": "gsea_results_prerank, gsea_plots_prerank = kaleidocell.run_gsea_pipeline(\n    results_mp,\n    from_file=['../data/mh.all.v2024.1.Mm.symbols.gmt'],\n    method='prerank',        # GSEA preranked on full NMF weight vector\n    top_n_plot=6,\n    plot=True,\n    save_csv=False,\n)\n\ngsea_results_prerank.head(20)",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "source": "## 4 · Generate HTML report\n\n### Option 1 — skip GSEA (no gene-set file required)\n\nIf you do not need pathway enrichment, pass `results_mp` directly to\n`get_html`.  All other tabs (heatmap, UMAP, metrics, gene table, violin plots)\nare still produced.",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "source": "path = kaleidocell.get_html(\n    results_mp,\n    adata,\n    mp_scores=mp_scores,\n    obs=['batch'],           # adjust to your obs columns of interest\n    output_path='../results/05_no_gsea/',\n)\nprint(f\"Report written to: {path}\")",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "source": "### Option 2 — include GSEA results in the report\n\nPass the `gsea_results` and `gsea_plots` returned by `run_gsea_pipeline` to\n`get_html` to add a GSEA tab to the report.",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "source": "path = kaleidocell.get_html(\n    results_mp,\n    adata,\n    mp_scores=mp_scores,\n    obs=['batch'],\n    gsea_results=gsea_results_enrichr,   # from run_gsea_pipeline above\n    gsea_plots=gsea_plots_enrichr,\n    output_path='../results/05_with_gsea/',\n)\nprint(f\"Report written to: {path}\")",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}