{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "19b953bb",
   "metadata": {
    "language": "markdown"
   },
   "source": [
    "# Read repertoire evidence against every mock panel\n",
    "\n",
    "Receptor annotation ranks peptide–MHC candidates. Repertoire inference compares a declared endpoint with matched reference panels. This offline lesson uses **synthetic final-table fixtures**, not biological results or a fitted null. It does not calculate Pgen, draw reference panels or rerun inference.\n",
    "\n",
    "For your own completed run, replace the fixture paths with the `counts.tsv` and `summary.tsv` exported by `vdjmatch repertoire-exact --pgen-features FEATURES --abundance-metrics`. Keep their producing manifest. The `curve_mean` endpoint measures mean discoverable matched source clonotypes over whole-library sampling effort; it differs from matched-subset Hill diversity, read abundance and asymptotic richness.\n",
    "\n",
    "The report reuses the shipping `repertoire-report` CLI and retains the recorded empirical P and BH q values. Inspect effect size and all panels, retain every library/timepoint, and distinguish library from donor counts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6537195e",
   "metadata": {
    "language": "python"
   },
   "outputs": [],
   "source": [
    "# Report this kernel's versions and prepare a fresh output directory.\n",
    "import sys, tempfile, subprocess\n",
    "from pathlib import Path\n",
    "from importlib.metadata import version\n",
    "import vdjtools\n",
    "import polars as pl\n",
    "print(sys.version.split()[0], {name: version(name) for name in ('vdjmatch','vdjtools','polars')})\n",
    "output = Path(tempfile.mkdtemp(prefix='vdjmatch-evidence-'))\n",
    "print(output)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e713c335",
   "metadata": {
    "language": "python"
   },
   "outputs": [],
   "source": [
    "# Write synthetic final tables; no statistical inference is performed here.\n",
    "counts = pl.DataFrame({'sample_id': ['DEMO']*201, 'group_id': ['SYNTHETIC_TARGET']*201,\n",
    "    'replicate': list(range(-1,200)), 'matched_curve_mean': [10.]+[1.]*200})\n",
    "summary = pl.DataFrame({'sample_id': ['DEMO'], 'sample_label': ['Synthetic example'],\n",
    "    'group_id': ['SYNTHETIC_TARGET'], 'original_p_curve_mean': [1/201],\n",
    "    'original_q_curve_mean': [.03]})\n",
    "counts.write_csv(output/'counts.tsv', separator='\\t')\n",
    "summary.write_csv(output/'summary.tsv', separator='\\t')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "15d5027c",
   "metadata": {
    "language": "python"
   },
   "outputs": [],
   "source": [
    "# Render all 200 recorded endpoints with the installed CLI.\n",
    "subprocess.run([sys.executable, '-m', 'vdjmatch.cli', 'repertoire-report',\n",
    "    str(output/'counts.tsv'), str(output/'summary.tsv'), '--metric', 'curve_mean',\n",
    "    '--output-prefix', str(output/'evidence')], check=True, timeout=60)\n",
    "evidence = pl.read_csv(output/'evidence.evidence.tsv', separator='\\t')\n",
    "assert evidence['mock_panels'].to_list() == [200]\n",
    "assert evidence['recorded_p'][0] == summary['original_p_curve_mean'][0]\n",
    "assert evidence['recorded_q'][0] == summary['original_q_curve_mean'][0]\n",
    "evidence"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d383d332",
   "metadata": {
    "language": "python"
   },
   "outputs": [],
   "source": [
    "# Inspect the report; PDF and flat evidence TSV accompany this preview.\n",
    "from IPython.display import Image, display\n",
    "display(Image(filename=str(output/'evidence.page-1.png')))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "865de6a5",
   "metadata": {
    "language": "markdown"
   },
   "source": [
    "## Interpret the endpoint in its producing context\n",
    "\n",
    "The illustrative observed/mock ratio is 10; these fabricated values establish only that reporting preserves the input evidence. They make no claim about binding, calibration or biological accuracy.\n",
    "\n",
    "For biological tables, report the actual matching/V/J predicate, raw marginal Pgen source, observed-control population, count unit, mock count and test family. Full-data discovery uses all observed clone abundances across a fixed whole-library effort grid. The 100,000-read detection experiment is a separate subsampling analysis. Hamming-1 paired exposure is also a distinct workflow: preserve observed pairing and full pMHC/HLA context, and do not transfer the bulk significance law to descriptive paired exposure.\n",
    "\n",
    "See the [repertoire method guide](https://docs.isalgo.dev/vdjmatch/repertoire-method.html) for the owning algorithms and CLI options."
   ]
  }
 ],
 "metadata": {
  "execution_timeout_seconds": 60,
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}