{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1. Getting Started\n",
    "\n",
    "This notebook demonstrates a minimal end-to-end workflow using synthetic data.\n",
    "No project files or large datasets are required.\n",
    "\n",
    "**Pipeline phase:** Covers Phases 3 and 3.5b in brief.\n",
    "\n",
    "**What you will learn:**\n",
    "- Create a synthetic AnnData with spatial coordinates\n",
    "- Run the preprocessing recipe for Visium data\n",
    "- Score Hallmark gene sets\n",
    "- Produce a basic spatial plot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import anndata as ad\n",
    "import sc_tools as st\n",
    "\n",
    "print(f\"sc_tools version: {st.__version__}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create a synthetic Visium-like AnnData\n",
    "\n",
    "In a real workflow this would be a Phase 1 checkpoint loaded from disk:\n",
    "```python\n",
    "adata = ad.read_h5ad(\"results/adata.raw.p1.h5ad\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(42)\n",
    "n_spots, n_genes = 500, 200\n",
    "\n",
    "# Raw count matrix (integer)\n",
    "X = np.random.negative_binomial(5, 0.5, size=(n_spots, n_genes)).astype(float)\n",
    "\n",
    "# Gene names: first 10 are Hallmark HYPOXIA genes (for scoring demo)\n",
    "hallmark_genes = [\"ALDOA\", \"CDKN3\", \"ENO1\", \"LDHA\", \"PGK1\", \"TPI1\", \"VEGFA\", \"HK1\", \"HK2\", \"PFKL\"]\n",
    "gene_names = hallmark_genes + [f\"GENE_{i}\" for i in range(n_genes - len(hallmark_genes))]\n",
    "\n",
    "# Spatial coordinates (grid layout)\n",
    "row_idx, col_idx = np.divmod(np.arange(n_spots), 25)\n",
    "spatial_coords = np.column_stack([col_idx * 100, row_idx * 100]).astype(float)\n",
    "\n",
    "adata = ad.AnnData(\n",
    "    X=X,\n",
    "    obs={\"sample\": \"sample_A\", \"library_id\": \"lib_A\"},\n",
    "    var={\"gene_ids\": gene_names},\n",
    "    obsm={\"spatial\": spatial_coords},\n",
    ")\n",
    "adata.var_names = gene_names\n",
    "adata.obs_names = [f\"spot_{i}\" for i in range(n_spots)]\n",
    "\n",
    "print(adata)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Phase 3: Preprocess\n",
    "\n",
    "The `preprocess` recipe handles normalization, HVG selection, PCA, neighbors,\n",
    "UMAP, and Leiden clustering in one call.  For Visium data the default\n",
    "integration is `scvi`; we use `harmony` here to avoid the heavy dependency."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "st.pp.preprocess(\n",
    "    adata,\n",
    "    modality=\"visium\",\n",
    "    integration=\"harmony\",\n",
    "    batch_key=None,         # single sample — no batch correction\n",
    "    n_top_genes=100,\n",
    "    n_pcs=20,\n",
    "    resolution=0.5,\n",
    ")\n",
    "\n",
    "print(\"Clusters:\", adata.obs[\"leiden\"].value_counts().to_dict())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Phase 3.5b: Score gene signatures\n",
    "\n",
    "Load the bundled MSigDB Hallmark gene sets and score them against the data.\n",
    "Scores are written to `adata.obsm['signature_score']` and `adata.obsm['signature_score_z']`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load bundled Hallmark sets (offline — no network required)\n",
    "hallmark = st.tl.load_hallmark()\n",
    "print(f\"Loaded {len(hallmark)} Hallmark gene sets\")\n",
    "\n",
    "# Score (scanpy method by default)\n",
    "st.tl.score_signature(adata, hallmark)\n",
    "\n",
    "# Inspect available score columns\n",
    "from sc_tools.utils.signatures import get_signature_columns\n",
    "cols = get_signature_columns(adata)\n",
    "print(f\"Scored {len(cols)} signatures. First 5: {cols[:5]}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Save Phase 3.5b checkpoint\n",
    "\n",
    "In a real project, save to the standard checkpoint path:\n",
    "```python\n",
    "adata.write_h5ad(\"results/adata.normalized.scored.p35.h5ad\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "## Next steps\n\n- **QC deep-dive:** See [Tutorial 2 — QC and Filtering](02_qc.ipynb)\n- **Preprocessing details:** See [Tutorial 3 — Preprocessing](03_preprocessing.ipynb)\n- **Gene signature scoring:** See [Tutorial 4 — Gene Signature Scoring](04_signature_scoring.ipynb)\n- **API reference:** See the [API docs](../api/index.rst) for `sc_tools.pp` and `sc_tools.tl`"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "sc_tools",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.10.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}