{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "intro",
   "metadata": {},
   "source": [
    "# 01 - Quick start\n",
    "\n",
    "Fit `MaldiMLPClassifier` on real MALDI-TOF spectra and inspect its sklearn-compatible API.\n",
    "\n",
    "All notebooks in this folder use the **MALDI-Kleb-AI** dataset (Rocchi *et al.*, 2026; [Zenodo DOI 10.5281/zenodo.17405072](https://zenodo.org/records/17405072)) - *Klebsiella* isolates from three Italian clinical centres, with Amikacin / Meropenem AMR labels. `notebooks/_demo.py` caches the 370 MB tarball under `~/.cache/maldideepkit/` (or `$MALDIDEEPKIT_CACHE_DIR`) on first use."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "load-md",
   "metadata": {},
   "source": [
    "## 1. Load the demo dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "load",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-04-28T09:47:04.858401Z",
     "iopub.status.busy": "2026-04-28T09:47:04.858297Z",
     "iopub.status.idle": "2026-04-28T09:47:22.012396Z",
     "shell.execute_reply": "2026-04-28T09:47:22.011629Z"
    }
   },
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "face9204d67048a69323d5ce96ab7daf",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "Processing spectra:   0%|          | 0/743 [00:00<?, ?spectrum/s]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "X: (741, 6000) | prevalence(R): 49.80% | batches: ['Catania', 'Milan', 'Rome']\n"
     ]
    }
   ],
   "source": [
    "import sys, pathlib\n",
    "sys.path.insert(0, str(pathlib.Path.cwd().parent))  # make notebooks/_demo.py importable\n",
    "from notebooks._demo import binary_labels, load_maldi_kleb_ai\n",
    "\n",
    "demo = load_maldi_kleb_ai(antibiotic='Amikacin', verbose=True)\n",
    "X, y = binary_labels(demo)  # drop intermediates; y == 1 for resistant\n",
    "print(f'X: {X.shape} | prevalence(R): {y.mean():.2%} | batches: {sorted(demo.batch.unique())}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fit-md",
   "metadata": {},
   "source": [
    "## 2. Fit a classifier\n",
    "\n",
    "`MaldiMLPClassifier` accepts pandas DataFrames and Series directly. With `random_state` fixed, runs are reproducible."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "fit",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-04-28T09:47:22.013839Z",
     "iopub.status.busy": "2026-04-28T09:47:22.013720Z",
     "iopub.status.idle": "2026-04-28T09:47:24.299257Z",
     "shell.execute_reply": "2026-04-28T09:47:24.298376Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "test accuracy: 0.747\n"
     ]
    }
   ],
   "source": [
    "from sklearn.model_selection import train_test_split\n",
    "from maldideepkit import MaldiMLPClassifier\n",
    "\n",
    "X_tr, X_te, y_tr, y_te = train_test_split(X, y, test_size=0.25, stratify=y, random_state=0)\n",
    "\n",
    "clf = MaldiMLPClassifier(epochs=30, batch_size=32, random_state=0).fit(X_tr, y_tr)\n",
    "print(f'test accuracy: {clf.score(X_te, y_te):.3f}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "proba",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-04-28T09:47:24.300849Z",
     "iopub.status.busy": "2026-04-28T09:47:24.300613Z",
     "iopub.status.idle": "2026-04-28T09:47:24.308253Z",
     "shell.execute_reply": "2026-04-28T09:47:24.307671Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "AUROC: 0.826\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "array([[0.35774884, 0.64225113],\n",
       "       [0.5389345 , 0.46106547],\n",
       "       [0.29883578, 0.7011642 ],\n",
       "       [0.42581147, 0.5741885 ],\n",
       "       [0.32527173, 0.6747283 ]], dtype=float32)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import numpy as np\n",
    "from sklearn.metrics import roc_auc_score\n",
    "\n",
    "proba = clf.predict_proba(X_te)\n",
    "print(f'AUROC: {roc_auc_score(y_te, proba[:, 1]):.3f}')\n",
    "proba[:5]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "save-md",
   "metadata": {},
   "source": [
    "## 3. Save and reload\n",
    "\n",
    "Every classifier persists its weights, fitted state, and the constructor kwargs needed to rebuild the model - `save()` writes a `.pt` + `.json` pair, `load()` restores both."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "save",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-04-28T09:47:24.309542Z",
     "iopub.status.busy": "2026-04-28T09:47:24.309439Z",
     "iopub.status.idle": "2026-04-28T09:47:24.356037Z",
     "shell.execute_reply": "2026-04-28T09:47:24.355431Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import tempfile\n",
    "from pathlib import Path\n",
    "\n",
    "with tempfile.TemporaryDirectory() as tmpdir:\n",
    "    path = Path(tmpdir) / 'quickstart_mlp'\n",
    "    clf.save(path)\n",
    "    restored = MaldiMLPClassifier.load(path)\n",
    "\n",
    "np.allclose(restored.predict_proba(X_te[:5]), proba[:5])"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "maldideepkit (3.10.12)",
   "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.10.12"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {
     "36eb52f146ca4535a4157749cc76a8b1": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "2.0.0",
      "model_name": "HTMLModel",
      "state": {
       "_dom_classes": [],
       "_model_module": "@jupyter-widgets/controls",
       "_model_module_version": "2.0.0",
       "_model_name": "HTMLModel",
       "_view_count": null,
       "_view_module": "@jupyter-widgets/controls",
       "_view_module_version": "2.0.0",
       "_view_name": "HTMLView",
       "description": "",
       "description_allow_html": false,
       "layout": "IPY_MODEL_71f84699fafb4273962bb050067507fa",
       "placeholder": "",
       "style": "IPY_MODEL_a6876d6c1d8c4b3aacf3f4713e7a0c8e",
       "tabbable": null,
       "tooltip": null,
       "value": "Processing spectra: 100%"
      }
     },
     "47670526692445f0a540a7df8b4a8087": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "2.0.0",
      "model_name": "HTMLStyleModel",
      "state": {
       "_model_module": "@jupyter-widgets/controls",
       "_model_module_version": "2.0.0",
       "_model_name": "HTMLStyleModel",
       "_view_count": null,
       "_view_module": "@jupyter-widgets/base",
       "_view_module_version": "2.0.0",
       "_view_name": "StyleView",
       "background": null,
       "description_width": "",
       "font_size": null,
       "text_color": null
      }
     },
     "5e1d7a0ec39d4ad980364f2da23d7457": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "2.0.0",
      "model_name": "FloatProgressModel",
      "state": {
       "_dom_classes": [],
       "_model_module": "@jupyter-widgets/controls",
       "_model_module_version": "2.0.0",
       "_model_name": "FloatProgressModel",
       "_view_count": null,
       "_view_module": "@jupyter-widgets/controls",
       "_view_module_version": "2.0.0",
       "_view_name": "ProgressView",
       "bar_style": "success",
       "description": "",
       "description_allow_html": false,
       "layout": "IPY_MODEL_6646776179a440588c6ca9e3411c0ec3",
       "max": 743,
       "min": 0,
       "orientation": "horizontal",
       "style": "IPY_MODEL_dea83a93c7b74592b9dbe9bd8fd755ed",
       "tabbable": null,
       "tooltip": null,
       "value": 743
      }
     },
     "6646776179a440588c6ca9e3411c0ec3": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "2.0.0",
      "model_name": "LayoutModel",
      "state": {
       "_model_module": "@jupyter-widgets/base",
       "_model_module_version": "2.0.0",
       "_model_name": "LayoutModel",
       "_view_count": null,
       "_view_module": "@jupyter-widgets/base",
       "_view_module_version": "2.0.0",
       "_view_name": "LayoutView",
       "align_content": null,
       "align_items": null,
       "align_self": null,
       "border_bottom": null,
       "border_left": null,
       "border_right": null,
       "border_top": null,
       "bottom": null,
       "display": null,
       "flex": null,
       "flex_flow": null,
       "grid_area": null,
       "grid_auto_columns": null,
       "grid_auto_flow": null,
       "grid_auto_rows": null,
       "grid_column": null,
       "grid_gap": null,
       "grid_row": null,
       "grid_template_areas": null,
       "grid_template_columns": null,
       "grid_template_rows": null,
       "height": null,
       "justify_content": null,
       "justify_items": null,
       "left": null,
       "margin": null,
       "max_height": null,
       "max_width": null,
       "min_height": null,
       "min_width": null,
       "object_fit": null,
       "object_position": null,
       "order": null,
       "overflow": null,
       "padding": null,
       "right": null,
       "top": null,
       "visibility": null,
       "width": null
      }
     },
     "71f84699fafb4273962bb050067507fa": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "2.0.0",
      "model_name": "LayoutModel",
      "state": {
       "_model_module": "@jupyter-widgets/base",
       "_model_module_version": "2.0.0",
       "_model_name": "LayoutModel",
       "_view_count": null,
       "_view_module": "@jupyter-widgets/base",
       "_view_module_version": "2.0.0",
       "_view_name": "LayoutView",
       "align_content": null,
       "align_items": null,
       "align_self": null,
       "border_bottom": null,
       "border_left": null,
       "border_right": null,
       "border_top": null,
       "bottom": null,
       "display": null,
       "flex": null,
       "flex_flow": null,
       "grid_area": null,
       "grid_auto_columns": null,
       "grid_auto_flow": null,
       "grid_auto_rows": null,
       "grid_column": null,
       "grid_gap": null,
       "grid_row": null,
       "grid_template_areas": null,
       "grid_template_columns": null,
       "grid_template_rows": null,
       "height": null,
       "justify_content": null,
       "justify_items": null,
       "left": null,
       "margin": null,
       "max_height": null,
       "max_width": null,
       "min_height": null,
       "min_width": null,
       "object_fit": null,
       "object_position": null,
       "order": null,
       "overflow": null,
       "padding": null,
       "right": null,
       "top": null,
       "visibility": null,
       "width": null
      }
     },
     "8dc325bc42e94c309f39a1f8d172fbe1": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "2.0.0",
      "model_name": "LayoutModel",
      "state": {
       "_model_module": "@jupyter-widgets/base",
       "_model_module_version": "2.0.0",
       "_model_name": "LayoutModel",
       "_view_count": null,
       "_view_module": "@jupyter-widgets/base",
       "_view_module_version": "2.0.0",
       "_view_name": "LayoutView",
       "align_content": null,
       "align_items": null,
       "align_self": null,
       "border_bottom": null,
       "border_left": null,
       "border_right": null,
       "border_top": null,
       "bottom": null,
       "display": null,
       "flex": null,
       "flex_flow": null,
       "grid_area": null,
       "grid_auto_columns": null,
       "grid_auto_flow": null,
       "grid_auto_rows": null,
       "grid_column": null,
       "grid_gap": null,
       "grid_row": null,
       "grid_template_areas": null,
       "grid_template_columns": null,
       "grid_template_rows": null,
       "height": null,
       "justify_content": null,
       "justify_items": null,
       "left": null,
       "margin": null,
       "max_height": null,
       "max_width": null,
       "min_height": null,
       "min_width": null,
       "object_fit": null,
       "object_position": null,
       "order": null,
       "overflow": null,
       "padding": null,
       "right": null,
       "top": null,
       "visibility": null,
       "width": null
      }
     },
     "a6876d6c1d8c4b3aacf3f4713e7a0c8e": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "2.0.0",
      "model_name": "HTMLStyleModel",
      "state": {
       "_model_module": "@jupyter-widgets/controls",
       "_model_module_version": "2.0.0",
       "_model_name": "HTMLStyleModel",
       "_view_count": null,
       "_view_module": "@jupyter-widgets/base",
       "_view_module_version": "2.0.0",
       "_view_name": "StyleView",
       "background": null,
       "description_width": "",
       "font_size": null,
       "text_color": null
      }
     },
     "a71d5bfe42be4d9fa182cd7b998de267": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "2.0.0",
      "model_name": "HTMLModel",
      "state": {
       "_dom_classes": [],
       "_model_module": "@jupyter-widgets/controls",
       "_model_module_version": "2.0.0",
       "_model_name": "HTMLModel",
       "_view_count": null,
       "_view_module": "@jupyter-widgets/controls",
       "_view_module_version": "2.0.0",
       "_view_name": "HTMLView",
       "description": "",
       "description_allow_html": false,
       "layout": "IPY_MODEL_bdc4249b308a426f812b30661785eb62",
       "placeholder": "",
       "style": "IPY_MODEL_47670526692445f0a540a7df8b4a8087",
       "tabbable": null,
       "tooltip": null,
       "value": " 743/743 [00:00&lt;00:00, 4098.96spectrum/s]"
      }
     },
     "bdc4249b308a426f812b30661785eb62": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "2.0.0",
      "model_name": "LayoutModel",
      "state": {
       "_model_module": "@jupyter-widgets/base",
       "_model_module_version": "2.0.0",
       "_model_name": "LayoutModel",
       "_view_count": null,
       "_view_module": "@jupyter-widgets/base",
       "_view_module_version": "2.0.0",
       "_view_name": "LayoutView",
       "align_content": null,
       "align_items": null,
       "align_self": null,
       "border_bottom": null,
       "border_left": null,
       "border_right": null,
       "border_top": null,
       "bottom": null,
       "display": null,
       "flex": null,
       "flex_flow": null,
       "grid_area": null,
       "grid_auto_columns": null,
       "grid_auto_flow": null,
       "grid_auto_rows": null,
       "grid_column": null,
       "grid_gap": null,
       "grid_row": null,
       "grid_template_areas": null,
       "grid_template_columns": null,
       "grid_template_rows": null,
       "height": null,
       "justify_content": null,
       "justify_items": null,
       "left": null,
       "margin": null,
       "max_height": null,
       "max_width": null,
       "min_height": null,
       "min_width": null,
       "object_fit": null,
       "object_position": null,
       "order": null,
       "overflow": null,
       "padding": null,
       "right": null,
       "top": null,
       "visibility": null,
       "width": null
      }
     },
     "dea83a93c7b74592b9dbe9bd8fd755ed": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "2.0.0",
      "model_name": "ProgressStyleModel",
      "state": {
       "_model_module": "@jupyter-widgets/controls",
       "_model_module_version": "2.0.0",
       "_model_name": "ProgressStyleModel",
       "_view_count": null,
       "_view_module": "@jupyter-widgets/base",
       "_view_module_version": "2.0.0",
       "_view_name": "StyleView",
       "bar_color": null,
       "description_width": ""
      }
     },
     "face9204d67048a69323d5ce96ab7daf": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "2.0.0",
      "model_name": "HBoxModel",
      "state": {
       "_dom_classes": [],
       "_model_module": "@jupyter-widgets/controls",
       "_model_module_version": "2.0.0",
       "_model_name": "HBoxModel",
       "_view_count": null,
       "_view_module": "@jupyter-widgets/controls",
       "_view_module_version": "2.0.0",
       "_view_name": "HBoxView",
       "box_style": "",
       "children": [
        "IPY_MODEL_36eb52f146ca4535a4157749cc76a8b1",
        "IPY_MODEL_5e1d7a0ec39d4ad980364f2da23d7457",
        "IPY_MODEL_a71d5bfe42be4d9fa182cd7b998de267"
       ],
       "layout": "IPY_MODEL_8dc325bc42e94c309f39a1f8d172fbe1",
       "tabbable": null,
       "tooltip": null
      }
     }
    },
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}