{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f6de5bc8",
   "metadata": {
    "language": "markdown"
   },
   "source": [
    "# Compare two CLI geometries\n",
    "\n",
    "Fresh exact-excluded detailed stem4 and retained advanced vcdr12 outputs. The explicit benchmark option removes exact full-junction reference keys; no score or calibration is transferred between geometries.\n",
    "\n",
    "The displayed scores and their arithmetic delta are geometry diagnostics only. Distinct geometries do not have calibrated comparable score scales; the delta is neither accuracy nor a confidence improvement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cac27f1e",
   "metadata": {
    "language": "python"
   },
   "outputs": [],
   "source": [
    "# Identify the installed CLI and print the fresh kernel environment.\n",
    "import os, sys, subprocess, tempfile, json\n",
    "from pathlib import Path\n",
    "from importlib.metadata import version\n",
    "os.environ[\"POLARS_MAX_THREADS\"] = \"1\"\n",
    "print(\"Python:\", sys.version, \"CLI interpreter:\", sys.executable)\n",
    "for package in (\"vdjmatch\", \"vdjtools\", \"seqtree\", \"polars\"):\n",
    "    print(package, version(package))\n",
    "# Open this notebook from the repository root or the examples directory.\n",
    "examples = next((p for p in (Path.cwd()/\"examples\", Path.cwd())\n",
    "                 if (p/\"inputs/reference.tsv\").is_file()), None)\n",
    "if examples is None:\n",
    "    raise RuntimeError(\"Use the downloaded complete examples bundle, not this notebook alone\")\n",
    "# Deterministic demonstration: no sampling or RNG seeds are used.\n",
    "output = Path(tempfile.mkdtemp(prefix=\"vdjmatch-example-\"))/\"fresh\"\n",
    "output.mkdir()\n",
    "print(\"Fresh output directory:\", output)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "34cdded4",
   "metadata": {
    "language": "python"
   },
   "outputs": [],
   "source": [
    "# Calculate each geometry freshly through this kernel's installed CLI.\n",
    "subprocess.run([sys.executable, \"-m\", \"vdjmatch.cli\", \"annotate\",\n",
    "                str(examples/\"inputs/cohort/sample_a.tsv\"),\n",
    "                \"--vdjdb\", str(examples/\"inputs/reference.tsv\"), \"--threads\", \"1\",\n",
    "                \"--exclude-exact\", \"--details\", \"--output-prefix\", str(output/\"stem4\")],\n",
    "               check=True, timeout=120)\n",
    "subprocess.run([sys.executable, \"-m\", \"vdjmatch.cli\", \"annotate\",\n",
    "                str(examples/\"inputs/cohort/sample_a.tsv\"),\n",
    "                \"--vdjdb\", str(examples/\"inputs/reference.tsv\"), \"--threads\", \"1\",\n",
    "                \"--exclude-exact\", \"--details\", \"--v-regions\", \"cdr12\", \"--stem-depth\", \"0\",\n",
    "                \"--distance-matrix\", \"tcrdist\", \"--junction-ends\", \"trim3\",\n",
    "                \"--output-prefix\", str(output/\"vcdr12\")], check=True, timeout=120)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9654686d",
   "metadata": {
    "language": "python"
   },
   "outputs": [],
   "source": [
    "# Join detailed CLI evidence on source identity and the complete pMHC key.\n",
    "import polars as pl\n",
    "keys = [\"sample_id\", \"source_sequence_id\", \"epitope\", \"mhc_a\", \"mhc_b\", \"mhc_class\"]\n",
    "tables = {name: pl.read_csv(output/(name+\".enrichment.tsv\"), separator=\"\\t\")\n",
    "          for name in (\"stem4\", \"vcdr12\")}\n",
    "assert all(table.select(keys).unique().height == table.height for table in tables.values())\n",
    "left = tables[\"stem4\"].select(keys+[\"kernel_score\"]).rename({\"kernel_score\":\"stem4_score\"})\n",
    "right = tables[\"vcdr12\"].select(keys+[\"kernel_score\"]).rename({\"kernel_score\":\"vcdr12_score\"})\n",
    "comparison = left.join(right, on=keys, how=\"full\", coalesce=True, validate=\"1:1\", nulls_equal=True)\n",
    "comparison = comparison.with_columns((pl.col(\"vcdr12_score\")-pl.col(\"stem4_score\")).alias(\"score_delta\"))\n",
    "print(comparison.sort(keys))\n",
    "assert comparison.height == left.height == right.height\n",
    "for name in tables:\n",
    "    print(name, json.loads((output/(name+\".manifest.json\")).read_text())[\"kernel\"])\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dcf226e3",
   "metadata": {
    "language": "markdown"
   },
   "source": [
    "All displayed results come from fresh CLI tables. Raw synthetic `DEMO_A`/`DEMO_B` labels are software examples, not experimental binding truth. Keep no-hits and missing-chain dispositions. This example establishes neither accuracy nor a false-call threshold. Inspect the CLI manifests beside the tables for model, reference and resource settings. No computed outputs are committed or reused."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}