{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "dd40c599",
   "metadata": {},
   "source": [
    "# Notebook: features and classify stage in depth\n",
    "\n",
    "This notebook covers feature construction and **Stage 2: Classify**. You will\n",
    "see how `FEATURE_KIND` selects the matrix each method receives, how per-classifier\n",
    "log banners look, and how to isolate one method when a zoo run fails halfway.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b635327a",
   "metadata": {},
   "source": [
    "## Pipeline position\n",
    "\n",
    "```text\n",
    "Data \u2192 [ Features + Classify ] \u2192 Hardware \u2192 Report\n",
    "```\n",
    "\n",
    "Filter methods share the matched-filter bank. IQ and sequence methods skip that\n",
    "bank and consume `iq_trace` or `raw_trace_seq` instead. Mixing those expectations\n",
    "is a common source of cryptic shape errors.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a3e81373",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "import logging\n",
    "\n",
    "from arcade._logging import configure_logging\n",
    "from arcade.classifiers.base import get_classifier, list_classifiers\n",
    "from arcade.config import load_config\n",
    "from arcade.stages import DefaultClassifyStage, DefaultDataStage\n",
    "\n",
    "configure_logging(logging.INFO)\n",
    "\n",
    "CONFIG = Path(\"configs/example.yaml\")\n",
    "if not CONFIG.is_file():\n",
    "    CONFIG = Path(\"configs/paper_all_methods_benchmark.yaml\")\n",
    "\n",
    "cfg = load_config(CONFIG)\n",
    "\n",
    "# Shrink the run for interactive debugging.\n",
    "cfg.classifiers.run[:] = [\"threshold\", \"lda\"]  # mutate list in place\n",
    "print(\"methods =\", cfg.classifiers.run)\n",
    "print(\"filter_types =\", cfg.classifiers.filter_types)\n",
    "print(\"registered sample =\", list_classifiers()[:8])\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "70913d7f",
   "metadata": {},
   "source": [
    "## Inspect FEATURE_KIND before fitting\n",
    "\n",
    "```text\n",
    "threshold  FEATURE_KIND=filter_features\n",
    "lda        FEATURE_KIND=filter_features\n",
    "fnn        FEATURE_KIND=iq_trace\n",
    "transformer FEATURE_KIND=raw_trace_seq\n",
    "```\n",
    "\n",
    "If `fit` receives the wrong rank or width, check this attribute first.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b5782f10",
   "metadata": {},
   "outputs": [],
   "source": [
    "for name in cfg.classifiers.run:\n",
    "    cls = get_classifier(name)\n",
    "    print(\n",
    "        f\"{name:16s} kind={getattr(cls, 'FEATURE_KIND', '?')} \"\n",
    "        f\"category={getattr(cls, 'CATEGORY', '?')}\"\n",
    "    )\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4bd09df6",
   "metadata": {},
   "outputs": [],
   "source": [
    "data_out = DefaultDataStage().run(cfg)\n",
    "classify_out = DefaultClassifyStage().run(cfg, data_out)\n",
    "\n",
    "# Typical structure: per-method metrics under classify_out[\"classifiers\"]\n",
    "clfs = classify_out.get(\"classifiers\", classify_out)\n",
    "if isinstance(clfs, dict):\n",
    "    for name, payload in clfs.items():\n",
    "        metrics = payload.get(\"metrics\") if isinstance(payload, dict) else None\n",
    "        print(name, \"\u2192\", metrics)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "50dcac50",
   "metadata": {},
   "source": [
    "## Expected log pattern\n",
    "\n",
    "```text\n",
    "[INFO] arcade.stages.classify: === Stage 2: Classify ===\n",
    "[INFO] arcade.stages.classify: --- Classifier: threshold ---\n",
    "[INFO] arcade.stages.classify:   threshold \u2192 joint_acc=... f5q=...\n",
    "[INFO] arcade.stages.classify: --- Classifier: lda ---\n",
    "[INFO] arcade.stages.classify:   lda \u2192 joint_acc=... f5q=...\n",
    "```\n",
    "\n",
    "Progress bars from `tqdm` may appear during neural training. A method that\n",
    "prints `\u2192 (no metrics)` usually failed to evaluate or returned an empty metrics\n",
    "dict; scroll upward for the first WARNING or traceback for that name.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "611abeaa",
   "metadata": {},
   "source": [
    "## Debugging checklist for Stage 2\n",
    "\n",
    "| Symptom | Likely cause | What to try |\n",
    "|---------|--------------|-------------|\n",
    "| Shape error inside `fit` | Wrong `FEATURE_KIND` or filter bank | `arcade describe name`; confirm filter_types |\n",
    "| Only one method fails in a zoo | Method-specific `config_file` / extra missing | Run with `classifiers.run: [that_name]` alone |\n",
    "| Neural import errors | Missing `torch` | `pip install -e \".[torch]\"` |\n",
    "| Path signature import errors | Missing `iisignature` | `pip install -e \".[signature]\"` |\n",
    "| Metrics look fine per-qubit but joint is random | Bit order or label packing from Stage 1 | Fix data-stage label settings; do not retune the model yet |\n",
    "\n",
    "### Isolate one classifier from YAML\n",
    "\n",
    "```yaml\n",
    "classifiers:\n",
    "  run: [fnn]\n",
    "  fnn:\n",
    "    config_file: configs/nn_lienhard_fnn.yaml\n",
    "```\n",
    "\n",
    "Then:\n",
    "\n",
    "```bash\n",
    "arcade run path/to/debug.yaml\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5610274b",
   "metadata": {},
   "source": [
    "## Next\n",
    "\n",
    "Continue with [Hardware and report](stage_hardware_report.ipynb), or jump to\n",
    "[Debugging the pipeline](debugging_pipeline.ipynb) if you are chasing a failure\n",
    "across stages.\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  },
  "nbsphinx": {
   "execute": "never"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}