{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial 1 — Quick start\n",
    "\n",
    "This tutorial walks through the minimal kaleidocell workflow from raw AnnData to a\n",
    "self-contained HTML report.  It covers:\n",
    "\n",
    "1. Running NMF across all samples simultaneously\n",
    "2. Clustering NMF programs into consensus meta-programs (MPs)\n",
    "3. Visualising the similarity matrix\n",
    "4. Scoring cells by MP activity\n",
    "5. Generating a full HTML report\n",
    "\n",
    "**Dataset** — Peter Sims lab DMSO vs. panobinostat scRNA-seq cohort\n",
    "(5 patients, ~15 000 cells, log-normalised counts stored in `adata.X`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 0 · Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import kaleidocell\n",
    "import scanpy as sc\n",
    "\n",
    "print(f\"kaleidocell version: {kaleidocell.__version__}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1 · Load data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "adata = sc.read_h5ad('../data/petersims_example.h5ad')\n",
    "print(adata)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2 · Run NMF on every sample\n",
    "\n",
    "`multi_sample_nmf` loops over each unique value in `batch_key`, extracts the\n",
    "corresponding cells, and runs NMF at each rank in `test_ranks` with\n",
    "`n_initializations` random starts.  The factorisation with the lowest\n",
    "Frobenius error is retained per rank per sample.\n",
    "\n",
    "**Key parameters**\n",
    "| Parameter | Description |\n",
    "|-----------|-------------|\n",
    "| `batch_key` | `adata.obs` column identifying samples |\n",
    "| `test_ranks` | range of NMF ranks to evaluate |\n",
    "| `n_initializations` | random restarts per rank (higher = more stable, slower) |\n",
    "| `max_iterations` | maximum multiplicative-update steps per init |"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results_nmf, nmf_convergence = kaleidocell.multi_sample_nmf(\n",
    "    adata,\n",
    "    batch_key='Patients',\n",
    "    test_ranks=[4, 5, 6, 7, 8, 9], # default\n",
    "    n_initializations=1, # default\n",
    "    max_iterations = 100  # default\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3 · Derive consensus meta-programs\n",
    "\n",
    "All W matrices from all samples and ranks are concatenated.  Programs are\n",
    "clustered by cosine similarity using Ward linkage.\n",
    "\n",
    "`n_meta_programs` is automatically chosen when not specified (see\n",
    "`kaleidocell.find_optimal_n_mp`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results_mp = kaleidocell.derive_nmf_metaprograms(\n",
    "    results_nmf\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4 · Inspect the similarity heatmap\n",
    "\n",
    "The heatmap shows pairwise cosine similarities between all NMF programs,\n",
    "sorted by cluster assignment.  Tight diagonal blocks indicate well-separated\n",
    "meta-programs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kaleidocell.plot_heatmap(results_mp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5 · Inspect quality metrics\n",
    "\n",
    "| Metric | Meaning |\n",
    "|--------|---------|\n",
    "| `sampleCoverage` | Fraction of samples contributing at least one program to this MP |\n",
    "| `silhouette` | Within-cluster cohesion (−1 to +1; > 0.2 is good) |\n",
    "| `meanSimilarity` | Average pairwise cosine similarity inside the cluster |\n",
    "| `nPrograms` | Number of NMF programs assigned to this MP |\n",
    "| `nGenes` | Size of the consensus gene signature |"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results_mp['metrics']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6 · Score cells by MP activity\n",
    "\n",
    "`compute_mp_scores` projects each cell onto each MP by computing the mean\n",
    "expression of the MP's top genes.  The result is a `(n_cells × n_MPs)`\n",
    "DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mp_scores = kaleidocell.compute_mp_scores(results_mp, adata)\n",
    "mp_scores.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7 · Generate HTML report\n",
    "\n",
    "`get_html` produces a self-contained tabbed HTML file with all results\n",
    "embedded as base64 images — no external dependencies needed to open it.\n",
    "See *Output files* in the documentation for the full list of files written\n",
    "alongside the HTML."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "path = kaleidocell.get_html(\n",
    "    results_mp,\n",
    "    adata,\n",
    "    mp_scores=mp_scores,\n",
    "    obs=['Treatment', 'Patients'],  # violin-plot tabs\n",
    "    output_path='../results/01/', # Will be created if non existant\n",
    ")\n",
    "print(f\"Report written to: {path}\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "kaleidocell_07",
   "language": "python",
   "name": "kaleidocell_07"
  },
  "language_info": {
   "name": "python",
   "version": "3.11.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}