Reorganize TrkQual Repo and Add BDT Robustness Tests Under Feature Perturbations

TrkQual/perturbation_analysis/01_data_perturbation.ipynb

@@ -0,0 +1,118 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0f1f4855",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import uproot\n",
+    "import numpy as np\n",
+    "import os\n",
+    "from pathlib import Path"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bf91ed20",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Original nactive mean: 32.2548\n",
+      "Original momerr mean:  0.1635\n",
+      "Saved _nactive_plus1: /Users/malikfarouh/Documents/ML workspace/data/trkqual_tree_v2.0_training_nactive_plus1.root\n",
+      "Saved _momerr_plus10pct: /Users/malikfarouh/Documents/ML workspace/data/trkqual_tree_v2.0_training_momerr_plus10pct.root\n",
+      "Saved _momerr_minus10pct: /Users/malikfarouh/Documents/ML workspace/data/trkqual_tree_v2.0_training_momerr_minus10pct.root\n",
+      "Saved _momerr_plus50pct: /Users/malikfarouh/Documents/ML workspace/data/trkqual_tree_v2.0_training_momerr_plus50pct.root\n",
+      "Saved _momerr_minus50pct: /Users/malikfarouh/Documents/ML workspace/data/trkqual_tree_v2.0_training_momerr_minus50pct.root\n",
+      "\n",
+      "Verification:\n",
+      "perturbed                nactive_mean  momerr_mean\n",
+      "----------------------------------------------------\n",
+      "ORIGINAL                      32.2548       0.1635\n",
+      "_nactive_plus1                33.2548       0.1635\n",
+      "_momerr_plus10pct             32.2548       0.1798\n",
+      "_momerr_minus10pct            32.2548       0.1471\n",
+      "_momerr_plus50pct             32.2548       0.2452\n",
+      "_momerr_minus50pct            32.2548       0.0817\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Config\n",
+    "DATA_DIR = \"./\" \n",
+    "infile = Path(DATA_DIR) / \"trkqual_tree_v2.0_training.root\"\n",
+    "treename = \"trkqualtree\"\n",
+    "\n",
+    "# Load once\n",
+    "arrays = uproot.open(infile)[treename].arrays(library=\"np\")\n",
+    "\n",
+    "def save_perturbed(base_arrays, suffix, transform_fn):\n",
+    "    a = dict(base_arrays)             # copy dict of branch arrays\n",
+    "    transform_fn(a)                   # mutate selected branches\n",
+    "    out = infile.with_name(infile.stem + suffix + infile.suffix)\n",
+    "    with uproot.recreate(out) as f:\n",
+    "        f[treename] = a\n",
+    "    return out, a\n",
+    "\n",
+    "# Define all edits in one place\n",
+    "perturbed = [\n",
+    "    (\"_nactive_plus1\", lambda a: a.__setitem__(\"trk.nactive\", a[\"trk.nactive\"] + 1)),\n",
+    "    (\"_momerr_plus10pct\", lambda a: a.__setitem__(\"trk_ent.momerr\", a[\"trk_ent.momerr\"] * 1.10)),\n",
+    "    (\"_momerr_minus10pct\", lambda a: a.__setitem__(\"trk_ent.momerr\", a[\"trk_ent.momerr\"] * 0.90)),\n",
+    "     (\"_momerr_plus50pct\", lambda a: a.__setitem__(\"trk_ent.momerr\", a[\"trk_ent.momerr\"] * 1.50)),\n",
+    "        (\"_momerr_minus50pct\", lambda a: a.__setitem__(\"trk_ent.momerr\", a[\"trk_ent.momerr\"] * 0.50)),\n",
+    "    #(\"_fambig_full\", lambda a: a.__setitem__(\"trk.nnullambig\", a[\"trk.nactive\"].copy())),\n",
+    "    #(\"_momerr_x2\", lambda a: a.__setitem__(\"trk_ent.momerr\", a[\"trk_ent.momerr\"] * 2.0)),\n",
+    "    #(\"_fambigFull_momerrX2\", lambda a: (a.__setitem__(\"trk.nnullambig\", a[\"trk.nactive\"].copy()),\n",
+    "                                         #a.__setitem__(\"trk_ent.momerr\", a[\"trk_ent.momerr\"] * 2.0))),   \n",
+    "]\n",
+    "\n",
+    "# Quick original checks\n",
+    "print(f\"Original nactive mean: {arrays['trk.nactive'].mean():.4f}\")\n",
+    "print(f\"Original momerr mean:  {arrays['trk_ent.momerr'].mean():.4f}\")\n",
+    "\n",
+    "# Build all files\n",
+    "written = []\n",
+    "for suffix, fn in perturbed:\n",
+    "    out, arr_out = save_perturbed(arrays, suffix, fn)\n",
+    "    written.append((suffix, out, arr_out))\n",
+    "    print(f\"Saved {suffix}: {out}\")\n",
+    "\n",
+    "# verification table\n",
+    "print(\"\\nVerification:\")\n",
+    "print(f\"{'perturbed':24s} {'nactive_mean':>12s} {'momerr_mean':>12s}\")\n",
+    "print(\"-\" * 52)\n",
+    "print(f\"{'ORIGINAL':24s} {arrays['trk.nactive'].mean():12.4f} {arrays['trk_ent.momerr'].mean():12.4f}\")\n",
+    "for suffix, _, a in written:\n",
+    "    print(f\"{suffix:24s} {a['trk.nactive'].mean():12.4f} {a['trk_ent.momerr'].mean():12.4f}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "venv (3.9.6.final.0)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

TrkQual/perturbation_analysis/README.md

@@ -0,0 +1,15 @@
+# Perturbation Analysis Study
+
+This directory contains a suite of notebooks dedicated to evaluating an independent XGBoost gradient-boosted decision tree (BDT) classifier for the Mu2e tracking quality verification pipeline. The focus is to analyze algorithmic stability and domain adaptation under various systematic track features and data distortions.
+
+## File Walkthrough
+* **00_TrkQualTrain_main.ipynb:** It was only added to help viewer see how trained BDT model was saved.
+* **01_data_perturbation.ipynb:** Responsible for creating and perturbing all of the required data sets.
+* **02_factive_nactive_analysis.ipynb:** Investigates the physical properties of track hits, evaluates feature correlations, and isolates the impact of active hit fractions on background rejection.
+* **03_momerr_robustness_analysis.ipynb:** A targeted stress-test notebook that subjects the model to severe ±10% and extreme ±50% momentum error variations to evaluate algorithmic stability.
+* **04_all_data_perturbation_analysis.ipynb:** The global analysis file. It compiles all perturbed data streams into a unified evaluation framework to compare static cut strategies against adaptive dynamic domain adaptation.
+
+## Methodological Notes on Feature Sensitivity
+
+### Single-Feature Perturbation Logic (`nactive` vs. `factive`)
+In Notebook `02`, `nactive` was deliberately perturbed independently as there are multiple features that depend on it, so perturbing it gave an initial understanding and helped to move towards perturbing the `momerr` feature.