{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# MaldiAMRKit - Drift Monitoring\n",
"\n",
"This notebook demonstrates `maldiamrkit.drift.DriftMonitor`, which anchors\n",
"a baseline on the earliest timestamps and tracks temporal drift through\n",
"three complementary views:\n",
"\n",
"- **Reference similarity** - distance of per-window median spectrum to\n",
" the baseline reference (no labels needed)\n",
"- **PCA centroid trajectory** - how windows move in a baseline-fitted\n",
" PCA space\n",
"- **Peak-selection stability + effect-size drift** - Jaccard overlap of\n",
" top-k discriminative peaks per window vs. baseline, and Cohen's d of\n",
" specific peaks over time"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Dataset\n",
"\n",
"These notebooks use the **MALDI-Kleb-AI** dataset (Rocchi *et al.*, 2026; [Zenodo DOI 10.5281/zenodo.17405072](https://zenodo.org/records/17405072)), a curated archive of MALDI-TOF spectra of *Klebsiella* clinical isolates from three Italian centres (Rome, Milan, Catania) with Amikacin / Meropenem resistance annotations. For simplicity we restrict the demo to the **Rome sub-cohort** (single site, no batch correction needed). The helper in [`notebooks/_demo.py`](_demo.py) caches the 370 MB tarball under `~/.cache/maldiamrkit/` (or `$MALDIAMRKIT_CACHE_DIR`) on first use."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Load the Dataset\n",
"\n",
"We load the Rome cohort. The Zenodo metadata does not expose an\n",
"acquisition timestamp, so we **simulate dates** by spreading the real\n",
"spectra uniformly across a six-month window. The spectra themselves are\n",
"real clinical isolates; only the time axis is synthetic, which lets us\n",
"demonstrate the `DriftMonitor` API end-to-end without fabricating data."
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"execution": {
"iopub.execute_input": "2026-05-13T10:10:44.044953Z",
"iopub.status.busy": "2026-05-13T10:10:44.044748Z",
"iopub.status.idle": "2026-05-13T10:10:53.991934Z",
"shell.execute_reply": "2026-05-13T10:10:53.991416Z"
}
},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"/home/ettore/.venvs/maldiamrkit/lib/python3.10/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n",
" from .autonotebook import tqdm as notebook_tqdm\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"\r",
"Processing spectra: 0%| | 0/472 [00:00 pd.Series:\n",
" \"\"\"Return the label column for ``antibiotic`` (default Amikacin).\"\"\"\n",
" col = antibiotic or \"Amikacin\"\n",
" return self.meta.loc[self.X.index, col]\n",
"\n",
"\n",
"ordered = X.sort_index()\n",
"start = pd.Timestamp(\"2025-01-01\")\n",
"days = np.linspace(0, 180, num=len(ordered), dtype=int)\n",
"dates = [start + pd.Timedelta(days=int(d)) for d in days]\n",
"\n",
"meta_full = pd.DataFrame(\n",
" {\n",
" \"Amikacin\": y.loc[ordered.index].astype(int),\n",
" \"acquisition_date\": dates,\n",
" },\n",
" index=ordered.index,\n",
")\n",
"dataset = TimestampedSet(X=ordered, meta=meta_full)\n",
"lo = meta_full[\"acquisition_date\"].min().date()\n",
"hi = meta_full[\"acquisition_date\"].max().date()\n",
"print(f\"Date range: {lo} → {hi}\")\n",
"print(\"Class counts:\", meta_full[\"Amikacin\"].value_counts().to_dict())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Fit the DriftMonitor\n",
"\n",
"By default, the baseline is the earliest 20% of sorted timestamps. Below\n",
"we use a 30-day sliding window."
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {
"execution": {
"iopub.execute_input": "2026-05-13T10:10:54.014756Z",
"iopub.status.busy": "2026-05-13T10:10:54.014646Z",
"iopub.status.idle": "2026-05-13T10:10:54.086342Z",
"shell.execute_reply": "2026-05-13T10:10:54.085735Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Baseline cutoff: 2025-02-05\n"
]
}
],
"source": [
"from maldiamrkit.drift import DriftMonitor\n",
"\n",
"monitor = DriftMonitor(\n",
" time_column=\"acquisition_date\",\n",
" window=\"30D\",\n",
" metric=\"cosine\",\n",
" min_samples=5,\n",
").fit(dataset)\n",
"print(f\"Baseline cutoff: {monitor.baseline_end_.date()}\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 1. Reference Similarity\n",
"\n",
"For each 30-day window we compute the median spectrum and measure its\n",
"cosine distance to the baseline reference (element-wise median of\n",
"baseline rows). A rising line signals that the population is drifting\n",
"away from the baseline fingerprint."
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"execution": {
"iopub.execute_input": "2026-05-13T10:10:54.087992Z",
"iopub.status.busy": "2026-05-13T10:10:54.087865Z",
"iopub.status.idle": "2026-05-13T10:10:54.161161Z",
"shell.execute_reply": "2026-05-13T10:10:54.160684Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" window_start | \n",
" window_end | \n",
" n_spectra | \n",
" distance_to_reference | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" 2025-02-06 | \n",
" 2025-03-08 | \n",
" 78 | \n",
" 0.100245 | \n",
"
\n",
" \n",
" | 1 | \n",
" 2025-03-08 | \n",
" 2025-04-07 | \n",
" 79 | \n",
" 0.030005 | \n",
"
\n",
" \n",
" | 2 | \n",
" 2025-04-07 | \n",
" 2025-05-07 | \n",
" 78 | \n",
" 0.068501 | \n",
"
\n",
" \n",
" | 3 | \n",
" 2025-05-07 | \n",
" 2025-06-06 | \n",
" 78 | \n",
" 0.063464 | \n",
"
\n",
" \n",
" | 4 | \n",
" 2025-06-06 | \n",
" 2025-07-06 | \n",
" 63 | \n",
" 0.157319 | \n",
"
\n",
" \n",
"
\n",
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"_ = plot_reference_drift(\n",
" ref_df,\n",
" title=\"Cosine distance to baseline reference - Rome cohort\",\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 2. PCA Centroid Trajectory\n",
"\n",
"`monitor_pca` projects each window's rows onto a PCA space fitted on\n",
"the baseline, then reports the per-window centroid (PC1, PC2) and\n",
"dispersion (mean distance from centroid).\n",
"\n",
"`plot_pca_drift` draws arrows between consecutive centroids and colours\n",
"each point by time (early → late)."
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {
"execution": {
"iopub.execute_input": "2026-05-13T10:10:54.627064Z",
"iopub.status.busy": "2026-05-13T10:10:54.626825Z",
"iopub.status.idle": "2026-05-13T10:10:54.669607Z",
"shell.execute_reply": "2026-05-13T10:10:54.668907Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" window_start | \n",
" window_end | \n",
" centroid_pc1 | \n",
" centroid_pc2 | \n",
" dispersion | \n",
" n_spectra | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" 2025-02-06 | \n",
" 2025-03-08 | \n",
" 15.638410 | \n",
" 7.322260 | \n",
" 28.561470 | \n",
" 78 | \n",
"
\n",
" \n",
" | 1 | \n",
" 2025-03-08 | \n",
" 2025-04-07 | \n",
" 11.465971 | \n",
" 0.634700 | \n",
" 29.147355 | \n",
" 79 | \n",
"
\n",
" \n",
" | 2 | \n",
" 2025-04-07 | \n",
" 2025-05-07 | \n",
" 17.153615 | \n",
" 2.299735 | \n",
" 30.926929 | \n",
" 78 | \n",
"
\n",
" \n",
" | 3 | \n",
" 2025-05-07 | \n",
" 2025-06-06 | \n",
" 16.887356 | \n",
" -1.988096 | \n",
" 35.732134 | \n",
" 78 | \n",
"
\n",
" \n",
" | 4 | \n",
" 2025-06-06 | \n",
" 2025-07-06 | \n",
" 3.947033 | \n",
" 0.726848 | \n",
" 33.505330 | \n",
" 63 | \n",
"
\n",
" \n",
"
\n",
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"_ = plot_pca_drift(pca_df, title=\"PCA centroid trajectory - Rome cohort\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 3. Peak-Selection Stability\n",
"\n",
"For each window, `monitor_peak_stability` fits a fresh\n",
"`DifferentialAnalysis` and computes the Jaccard overlap of its top-k\n",
"peaks with the baseline top-k. A falling curve means discriminative\n",
"peaks are shifting over time - a red flag for biomarker studies."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"execution": {
"iopub.execute_input": "2026-05-13T10:10:54.773339Z",
"iopub.status.busy": "2026-05-13T10:10:54.773227Z",
"iopub.status.idle": "2026-05-13T10:11:04.900757Z",
"shell.execute_reply": "2026-05-13T10:11:04.900204Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" window_start | \n",
" stability_score | \n",
" n_spectra | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" 2025-02-06 | \n",
" 0.000000 | \n",
" 78 | \n",
"
\n",
" \n",
" | 1 | \n",
" 2025-03-08 | \n",
" 0.071429 | \n",
" 79 | \n",
"
\n",
" \n",
" | 2 | \n",
" 2025-04-07 | \n",
" 0.000000 | \n",
" 78 | \n",
"
\n",
" \n",
" | 3 | \n",
" 2025-05-07 | \n",
" 0.000000 | \n",
" 78 | \n",
"
\n",
" \n",
" | 4 | \n",
" 2025-06-06 | \n",
" 0.200000 | \n",
" 63 | \n",
"
\n",
" \n",
"
\n",
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"_ = plot_peak_stability(\n",
" stability_df,\n",
" title=\"Top-15 peak-selection Jaccard vs. baseline\",\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 4. Per-Peak Effect-Size Drift\n",
"\n",
"If you already have a short list of peaks of interest (e.g., from the\n",
"baseline analysis), `monitor_effect_sizes` tracks their Cohen's d\n",
"between R and S in each window. A peak whose d drops toward zero (or\n",
"flips sign) is losing discriminative power."
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {
"execution": {
"iopub.execute_input": "2026-05-13T10:11:04.984441Z",
"iopub.status.busy": "2026-05-13T10:11:04.984318Z",
"iopub.status.idle": "2026-05-13T10:11:05.018749Z",
"shell.execute_reply": "2026-05-13T10:11:05.018100Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" window_start | \n",
" 4703.0 | \n",
" 4712.0 | \n",
" 4715.0 | \n",
" 11114.0 | \n",
" 11108.0 | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" 2025-02-06 | \n",
" 0.556368 | \n",
" 0.352241 | \n",
" 0.450814 | \n",
" 0.401412 | \n",
" 0.537368 | \n",
"
\n",
" \n",
" | 1 | \n",
" 2025-03-08 | \n",
" 0.715240 | \n",
" 0.448572 | \n",
" 0.488254 | \n",
" 0.763298 | \n",
" 0.807354 | \n",
"
\n",
" \n",
" | 2 | \n",
" 2025-04-07 | \n",
" 0.509200 | \n",
" 0.468215 | \n",
" 0.467595 | \n",
" 0.612715 | \n",
" 0.360646 | \n",
"
\n",
" \n",
" | 3 | \n",
" 2025-05-07 | \n",
" 0.616484 | \n",
" 0.580740 | \n",
" 0.681273 | \n",
" 0.528699 | \n",
" 0.634580 | \n",
"
\n",
" \n",
" | 4 | \n",
" 2025-06-06 | \n",
" 0.752635 | \n",
" 0.653076 | \n",
" 0.665924 | \n",
" 0.785004 | \n",
" 0.589966 | \n",
"
\n",
" \n",
"
\n",
"