Add other files and folders, including data related, notebook, test and evaluation

data/CNN/eye_crops/val/open/.gitkeep

@@ -0,0 +1 @@
+

data/README.md

@@ -0,0 +1,47 @@
+# data/
+
+Raw collected session data used for model training and evaluation.
+
+## 1. Contents
+
+Each `collected_<name>/` folder contains `.npz` files for one participant:
+
+| Folder | Participant | Samples |
+|--------|-------------|---------|
+| `collected_Abdelrahman/` | Abdelrahman | 15,870 |
+| `collected_Jarek/` | Jarek | 14,829 |
+| `collected_Junhao/` | Junhao | 8,901 |
+| `collected_Kexin/` | Kexin | 32,312 (2 sessions) |
+| `collected_Langyuan/` | Langyuan | 15,749 |
+| `collected_Mohamed/` | Mohamed | 13,218 |
+| `collected_Yingtao/` | Yingtao | 17,591 |
+| `collected_ayten/` | Ayten | 17,621 |
+| `collected_saba/` | Saba | 8,702 |
+| **Total** | **9 participants** | **144,793** |
+
+## 2. File Format
+
+Each `.npz` file contains:
+
+| Key | Shape | Description |
+|-----|-------|-------------|
+| `features` | (N, 17) | 17-dimensional feature vectors (float32) |
+| `labels` | (N,) | Binary labels: 0 = unfocused, 1 = focused |
+| `feature_names` | (17,) | Column names for the 17 features |
+
+## 3. Feature List
+
+`ear_left`, `ear_right`, `ear_avg`, `h_gaze`, `v_gaze`, `mar`, `yaw`, `pitch`, `roll`, `s_face`, `s_eye`, `gaze_offset`, `head_deviation`, `perclos`, `blink_rate`, `closure_duration`, `yawn_duration`
+
+10 of these are selected for training (see `data_preparation/prepare_dataset.py`).
+
+## 4. Collection
+
+```bash
+python -m models.collect_features --name yourname
+```
+
+1. Webcam opens with live overlay
+2. Press **1** = focused, **0** = unfocused (switch every 10–30 sec)
+3. Press **p** to pause/resume
+4. Press **q** to stop and save

data/collected_Abdelrahman/abdelrahman_20260306_023035.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e2c48532150182c8933d4595e0a0711365645b699647e99976575b7c2adffaf8
+size 1207980

data/collected_Jarek/Jarek_20260225_012931.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0fa68f4d587eee8d645b23b463a9f1c848b9bacc2adb68603d5fa9cd8cb744c7
+size 1128864

data/collected_Junhao/Junhao_20260303_113554.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ec321ee79800c04fdc0f999690d07970445aeca61f977bf6537880bbc996b5e5
+size 678336

data/collected_Kexin/kexin2_20260305_180229.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0e96fe17571fa1fcccc1b4bd0c8838270498883e4db6a608c4d4d4c3a8ac1d0d
+size 1129700

data/collected_Kexin/kexin_20260224_151043.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8d402ca4e66910a2e174c4f4beec5d7b3db6a04213d29673b227ce6ef04b39c4
+size 1329732

data/collected_Langyuan/Langyuan_20260303_153145.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5c679cdba334b2f3f0953b7e44f7209056277c826e2b7b5cfcf2b8b750898400
+size 1198784

data/collected_Mohamed/session_20260224_010131.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0a784f703c13b83911f47ec507d32c25942a07572314b8a77cbf40ca8cdff16f
+size 1006428

data/collected_Yingtao/Yingtao_20260306_023937.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7a75af17e25dca5f06ea9e7443ea5fee9db638f68a5910e014ee7cb8b7ae80fd
+size 1338776

data/collected_ayten/ayten_session_1.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fbecdbffa1c1b03b3b0fb5f715dcb4ff885ecc67da4aff78e6952b8847a96014
+size 1341056

data/collected_saba/saba_20260306_230710.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:db1cab5ddcf9988856c5bdca1183c8eba4647365e675a1d8a200d12f6b5d2097
+size 663212

data_preparation/README.md

@@ -0,0 +1,75 @@
+# data_preparation/
+
+Shared data loading, cleaning, and exploratory analysis.
+
+## 1. Files
+
+| File | Description |
+|------|-------------|
+| `prepare_dataset.py` | Central data loading module used by all training scripts and notebooks |
+| `data_exploration.ipynb` | EDA notebook: feature distributions, class balance, correlations |
+
+## 2. prepare_dataset.py
+
+Provides a consistent pipeline for loading raw `.npz` data from `data/`:
+
+| Function | Purpose |
+|----------|---------|
+| `load_all_pooled(model_name)` | Load all participants, clean, select features, concatenate |
+| `load_per_person(model_name)` | Load grouped by person (for LOPO cross-validation) |
+| `get_numpy_splits(model_name)` | Load + stratified 70/15/15 split + StandardScaler |
+| `get_dataloaders(model_name)` | Same as above, wrapped in PyTorch DataLoaders |
+| `_split_and_scale(features, labels, ...)` | Reusable split + optional scaling |
+
+### Cleaning rules
+
+- `yaw` clipped to [-45, 45], `pitch`/`roll` to [-30, 30]
+- `ear_left`, `ear_right`, `ear_avg` clipped to [0, 0.85]
+
+### Selected features (face_orientation)
+
+`head_deviation`, `s_face`, `s_eye`, `h_gaze`, `pitch`, `ear_left`, `ear_avg`, `ear_right`, `gaze_offset`, `perclos`
+
+## 3. data_exploration.ipynb
+
+Run from this folder or from the project root. Covers:
+
+1. Per-feature statistics (mean, std, min, max)
+2. Class distribution (focused vs unfocused)
+3. Feature histograms and box plots
+4. Correlation matrix
+
+## 4. How to run
+
+`prepare_dataset.py` is a **library module**, not a standalone script. You don’t run it directly; you import it from code that needs data.
+
+**From repo root:**
+
+```bash
+# Optional: quick test that loading works
+python -c "
+from data_preparation.prepare_dataset import load_all_pooled
+X, y, names = load_all_pooled('face_orientation')
+print(f'Loaded {X.shape[0]} samples, {X.shape[1]} features: {names}')
+"
+```
+
+**Used by:**
+
+- `python -m models.mlp.train`
+- `python -m models.xgboost.train`
+- `notebooks/mlp.ipynb`, `notebooks/xgboost.ipynb`
+- `data_preparation/data_exploration.ipynb`
+
+## 5. Usage (in code)
+
+```python
+from data_preparation.prepare_dataset import load_all_pooled, get_numpy_splits
+
+# pooled data
+X, y, names = load_all_pooled("face_orientation")
+
+# ready-to-train splits
+splits, n_features, n_classes, scaler = get_numpy_splits("face_orientation")
+X_train, y_train = splits["X_train"], splits["y_train"]
+```

data_preparation/prepare_dataset.py

@@ -0,0 +1,232 @@
+import os
+import glob
+
+import numpy as np
+from sklearn.preprocessing import StandardScaler
+from sklearn.model_selection import train_test_split
+
+try:
+    import torch
+    from torch.utils.data import Dataset, DataLoader
+except ImportError:  # pragma: no cover
+    torch = None
+
+    class Dataset:  # type: ignore
+        pass
+
+    class _MissingTorchDataLoader:  # type: ignore
+        def __init__(self, *args, **kwargs):
+            raise ImportError(
+                "PyTorch not installed"
+            )
+
+    DataLoader = _MissingTorchDataLoader  # type: ignore
+
+DATA_DIR = os.path.join(os.path.dirname(__file__), "..", "data")
+
+SELECTED_FEATURES = {
+    "face_orientation": [
+        'head_deviation', 's_face', 's_eye', 'h_gaze', 'pitch',
+        'ear_left', 'ear_avg', 'ear_right', 'gaze_offset', 'perclos'
+    ],
+    "eye_behaviour": [
+        'ear_left', 'ear_right', 'ear_avg', 'mar',
+        'blink_rate', 'closure_duration', 'perclos', 'yawn_duration'
+    ]
+}
+
+
+class FeatureVectorDataset(Dataset):
+    def __init__(self, features: np.ndarray, labels: np.ndarray):
+        self.features = torch.tensor(features, dtype=torch.float32)
+        self.labels = torch.tensor(labels, dtype=torch.long)
+
+    def __len__(self):
+        return len(self.labels)
+
+    def __getitem__(self, idx):
+        return self.features[idx], self.labels[idx]
+
+
+# ── Low-level helpers ────────────────────────────────────────────────────
+
+def _clean_npz(raw, names):
+    """Apply clipping rules in-place. Shared by all loaders."""
+    for col, lo, hi in [('yaw', -45, 45), ('pitch', -30, 30), ('roll', -30, 30)]:
+        if col in names:
+            raw[:, names.index(col)] = np.clip(raw[:, names.index(col)], lo, hi)
+    for feat in ['ear_left', 'ear_right', 'ear_avg']:
+        if feat in names:
+            raw[:, names.index(feat)] = np.clip(raw[:, names.index(feat)], 0, 0.85)
+    return raw
+
+
+def _load_one_npz(npz_path, target_features):
+    """Load a single .npz file, clean and select features. Returns (X, y, selected_feature_names)."""
+    data = np.load(npz_path, allow_pickle=True)
+    raw = data['features'].astype(np.float32)
+    labels = data['labels'].astype(np.int64)
+    names = list(data['feature_names'])
+    raw = _clean_npz(raw, names)
+    selected = [f for f in target_features if f in names]
+    idx = [names.index(f) for f in selected]
+    return raw[:, idx], labels, selected
+
+
+# ── Public data loaders ──────────────────────────────────────────────────
+
+def load_all_pooled(model_name: str = "face_orientation", data_dir: str = None):
+    """Load all collected_*/*.npz, clean, select features, concatenate.
+
+    Returns (X_all, y_all, all_feature_names).
+    """
+    data_dir = data_dir or DATA_DIR
+    target_features = SELECTED_FEATURES.get(model_name, SELECTED_FEATURES["face_orientation"])
+    pattern = os.path.join(data_dir, "collected_*", "*.npz")
+    npz_files = sorted(glob.glob(pattern))
+
+    if not npz_files:
+        print("[DATA] Warning: No .npz files found. Falling back to synthetic.")
+        X, y = _generate_synthetic_data(model_name)
+        return X, y, target_features
+
+    all_X, all_y = [], []
+    all_names = None
+    for npz_path in npz_files:
+        X, y, names = _load_one_npz(npz_path, target_features)
+        if all_names is None:
+            all_names = names
+        all_X.append(X)
+        all_y.append(y)
+        print(f"[DATA]   + {os.path.basename(npz_path)}: {X.shape[0]} samples")
+
+    X_all = np.concatenate(all_X, axis=0)
+    y_all = np.concatenate(all_y, axis=0)
+    print(f"[DATA] Loaded {len(npz_files)} file(s) for '{model_name}': "
+          f"{X_all.shape[0]} total samples, {X_all.shape[1]} features")
+    return X_all, y_all, all_names
+
+
+def load_per_person(model_name: str = "face_orientation", data_dir: str = None):
+    """Load collected_*/*.npz grouped by person (folder name).
+
+    Returns dict { person_name: (X, y) } where X/y are per-person numpy arrays.
+    Also returns (X_all, y_all) as pooled data.
+    """
+    data_dir = data_dir or DATA_DIR
+    target_features = SELECTED_FEATURES.get(model_name, SELECTED_FEATURES["face_orientation"])
+    pattern = os.path.join(data_dir, "collected_*", "*.npz")
+    npz_files = sorted(glob.glob(pattern))
+
+    if not npz_files:
+        raise FileNotFoundError(f"No .npz files matching {pattern}")
+
+    by_person = {}
+    all_X, all_y = [], []
+    for npz_path in npz_files:
+        folder = os.path.basename(os.path.dirname(npz_path))
+        person = folder.replace("collected_", "", 1)
+        X, y, _ = _load_one_npz(npz_path, target_features)
+        all_X.append(X)
+        all_y.append(y)
+        if person not in by_person:
+            by_person[person] = []
+        by_person[person].append((X, y))
+        print(f"[DATA]   + {person}/{os.path.basename(npz_path)}: {X.shape[0]} samples")
+
+    for person, chunks in by_person.items():
+        by_person[person] = (
+            np.concatenate([c[0] for c in chunks], axis=0),
+            np.concatenate([c[1] for c in chunks], axis=0),
+        )
+
+    X_all = np.concatenate(all_X, axis=0)
+    y_all = np.concatenate(all_y, axis=0)
+    print(f"[DATA] {len(by_person)} persons, {X_all.shape[0]} total samples, {X_all.shape[1]} features")
+    return by_person, X_all, y_all
+
+
+def load_raw_npz(npz_path):
+    """Load a single .npz without cleaning or feature selection. For exploration notebooks."""
+    data = np.load(npz_path, allow_pickle=True)
+    features = data['features'].astype(np.float32)
+    labels = data['labels'].astype(np.int64)
+    names = list(data['feature_names'])
+    return features, labels, names
+
+
+# ── Legacy helpers (used by models/mlp/train.py and models/xgboost/train.py) ─
+
+def _load_real_data(model_name: str):
+    X, y, _ = load_all_pooled(model_name)
+    return X, y
+
+
+def _generate_synthetic_data(model_name: str):
+    target_features = SELECTED_FEATURES.get(model_name, SELECTED_FEATURES["face_orientation"])
+    n = 500
+    d = len(target_features)
+    c = 2
+    rng = np.random.RandomState(42)
+    features = rng.randn(n, d).astype(np.float32)
+    labels = rng.randint(0, c, size=n).astype(np.int64)
+    print(f"[DATA] Using synthetic data for '{model_name}': {n} samples, {d} features, {c} classes")
+    return features, labels
+
+
+def _split_and_scale(features, labels, split_ratios, seed, scale):
+    """Split data into train/val/test (stratified) and optionally scale."""
+    test_ratio = split_ratios[2]
+    val_ratio = split_ratios[1] / (split_ratios[0] + split_ratios[1])
+
+    X_train_val, X_test, y_train_val, y_test = train_test_split(
+        features, labels, test_size=test_ratio, random_state=seed, stratify=labels,
+    )
+    X_train, X_val, y_train, y_val = train_test_split(
+        X_train_val, y_train_val, test_size=val_ratio, random_state=seed, stratify=y_train_val,
+    )
+
+    scaler = None
+    if scale:
+        scaler = StandardScaler()
+        X_train = scaler.fit_transform(X_train)
+        X_val = scaler.transform(X_val)
+        X_test = scaler.transform(X_test)
+        print("[DATA] Applied StandardScaler (fitted on training split)")
+
+    splits = {
+        "X_train": X_train, "y_train": y_train,
+        "X_val": X_val,     "y_val": y_val,
+        "X_test": X_test,   "y_test": y_test,
+    }
+
+    print(f"[DATA] Split (stratified): train={len(y_train)}, val={len(y_val)}, test={len(y_test)}")
+    return splits, scaler
+
+
+def get_numpy_splits(model_name: str, split_ratios=(0.7, 0.15, 0.15), seed: int = 42, scale: bool = True):
+    """Return raw numpy arrays for non-PyTorch models (e.g. XGBoost)."""
+    features, labels = _load_real_data(model_name)
+    num_features = features.shape[1]
+    num_classes = int(labels.max()) + 1
+    splits, scaler = _split_and_scale(features, labels, split_ratios, seed, scale)
+    return splits, num_features, num_classes, scaler
+
+
+def get_dataloaders(model_name: str, batch_size: int = 32, split_ratios=(0.7, 0.15, 0.15), seed: int = 42, scale: bool = True):
+    """Return PyTorch DataLoaders for neural-network models."""
+    features, labels = _load_real_data(model_name)
+    num_features = features.shape[1]
+    num_classes = int(labels.max()) + 1
+    splits, scaler = _split_and_scale(features, labels, split_ratios, seed, scale)
+
+    train_ds = FeatureVectorDataset(splits["X_train"], splits["y_train"])
+    val_ds   = FeatureVectorDataset(splits["X_val"],   splits["y_val"])
+    test_ds  = FeatureVectorDataset(splits["X_test"],  splits["y_test"])
+
+    train_loader = DataLoader(train_ds, batch_size=batch_size, shuffle=True)
+    val_loader   = DataLoader(val_ds,   batch_size=batch_size, shuffle=False)
+    test_loader  = DataLoader(test_ds,  batch_size=batch_size, shuffle=False)
+
+    return train_loader, val_loader, test_loader, num_features, num_classes, scaler
+

evaluation/README.md

@@ -0,0 +1,46 @@
+# evaluation/
+
+Training logs and performance metrics.
+
+## 1. Contents
+
+```
+logs/
+├── face_orientation_training_log.json           # MLP (latest run)
+├── mlp_face_orientation_training_log.json       # MLP (alternate)
+└── xgboost_face_orientation_training_log.json   # XGBoost
+```
+
+## 2. Log Format
+
+Each JSON file records the full training history:
+
+**MLP logs:**
+```json
+{
+  "config": { "epochs": 30, "lr": 0.001, "batch_size": 32, ... },
+  "history": {
+    "train_loss": [0.287, 0.260, ...],
+    "val_loss":   [0.256, 0.245, ...],
+    "train_acc":  [0.889, 0.901, ...],
+    "val_acc":    [0.905, 0.909, ...]
+  },
+  "test": { "accuracy": 0.929, "f1": 0.929, "roc_auc": 0.971 }
+}
+```
+
+**XGBoost logs:**
+```json
+{
+  "config": { "n_estimators": 600, "max_depth": 8, "learning_rate": 0.149, ... },
+  "train_losses": [0.577, ...],
+  "val_losses":   [0.576, ...],
+  "test": { "accuracy": 0.959, "f1": 0.959, "roc_auc": 0.991 }
+}
+```
+
+## 3. Generated By
+
+- `python -m models.mlp.train` → writes MLP log
+- `python -m models.xgboost.train` → writes XGBoost log
+- Notebooks in `notebooks/` also save logs here

notebooks/README.md

@@ -0,0 +1,42 @@
+# notebooks/
+
+Training and evaluation notebooks for MLP and XGBoost models.
+
+## 1. Files
+
+| Notebook | Model | Description |
+|----------|-------|-------------|
+| `mlp.ipynb` | PyTorch MLP | Training, evaluation, and LOPO cross-validation |
+| `xgboost.ipynb` | XGBoost | Training, evaluation, and LOPO cross-validation |
+
+## 2. Structure (both notebooks)
+
+Each notebook follows the same layout:
+
+1. **Imports and CFG** — single config dict, project root setup
+2. **ClearML (optional)** — opt-in experiment tracking
+3. **Data loading** — uses `data_preparation.prepare_dataset` for consistent loading
+4. **Random split training** — 70/15/15 stratified split with per-epoch/round logging
+5. **Loss curves** — train vs validation loss plots
+6. **Test evaluation** — accuracy, F1, ROC-AUC, classification report, confusion matrix
+7. **Checkpoint saving** — model weights + JSON training log
+8. **LOPO evaluation** — Leave-One-Person-Out cross-validation across all 9 participants
+9. **LOPO summary** — per-person accuracy table + bar chart
+
+## 3. Running
+
+Open in Jupyter or VS Code with the Python kernel set to the project venv:
+
+```bash
+source venv/bin/activate
+jupyter notebook notebooks/mlp.ipynb
+```
+
+Make sure the kernel's working directory is either the project root or `notebooks/` — the path resolution handles both.
+
+## 4. Results
+
+| Model | Random Split Accuracy | Random Split F1 | LOPO (mean) |
+|-------|-----------------------|-----------------|-------------|
+| XGBoost | 95.87% | 0.959 | see notebook |
+| MLP | 92.92% | 0.929 | see notebook |

notebooks/mlp.ipynb

@@ -0,0 +1,571 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# MLP Training (ClearML-compatible)\n",
+        "\n",
+        "PyTorch MLP for focus classification.\n",
+        "- Single CFG dict (ClearML `task.connect(CFG)`)\n",
+        "- 70/15/15 stratified random split\n",
+        "- Per-epoch train/val loss + accuracy table\n",
+        "- Test evaluation: accuracy, F1, ROC-AUC\n",
+        "- ClearML scalar logging (opt-in)\n",
+        "- LOPO comparison at the end"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 1. Imports and CFG"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import json\n",
+        "import os\n",
+        "import sys\n",
+        "import random\n",
+        "\n",
+        "import numpy as np\n",
+        "import torch\n",
+        "import torch.nn as nn\n",
+        "import torch.optim as optim\n",
+        "from torch.utils.data import DataLoader, TensorDataset\n",
+        "from sklearn.preprocessing import StandardScaler\n",
+        "from sklearn.model_selection import train_test_split\n",
+        "from sklearn.metrics import (\n",
+        "    accuracy_score, f1_score, roc_auc_score,\n",
+        "    classification_report, confusion_matrix, ConfusionMatrixDisplay,\n",
+        ")\n",
+        "import matplotlib.pyplot as plt\n",
+        "import warnings\n",
+        "warnings.filterwarnings(\"ignore\")\n",
+        "\n",
+        "# Add project root to sys.path\n",
+        "_cwd = os.getcwd()\n",
+        "PROJECT_ROOT = _cwd if os.path.isdir(os.path.join(_cwd, \"models\")) else os.path.abspath(os.path.join(_cwd, \"..\"))\n",
+        "if PROJECT_ROOT not in sys.path:\n",
+        "    sys.path.insert(0, PROJECT_ROOT)\n",
+        "\n",
+        "from data_preparation.prepare_dataset import load_per_person, SELECTED_FEATURES, _split_and_scale\n",
+        "\n",
+        "CFG = {\n",
+        "    \"model_name\": \"face_orientation\",\n",
+        "    \"seed\": 42,\n",
+        "    \"split_ratios\": (0.7, 0.15, 0.15),\n",
+        "    \"scale\": True,\n",
+        "    \"batch_size\": 32,\n",
+        "    \"epochs\": 30,\n",
+        "    \"lr\": 1e-3,\n",
+        "    \"hidden_sizes\": [64, 32],\n",
+        "    \"checkpoints_dir\": os.path.join(PROJECT_ROOT, \"checkpoints\"),\n",
+        "    \"logs_dir\": os.path.join(PROJECT_ROOT, \"evaluation\", \"logs\"),\n",
+        "}\n",
+        "\n",
+        "print(f\"Project root: {PROJECT_ROOT}\")\n",
+        "print(f\"Device: {'cuda' if torch.cuda.is_available() else 'cpu'}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 2. ClearML (optional)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "USE_CLEARML = False  # set True when ClearML credentials are configured\n",
+        "task = None\n",
+        "\n",
+        "if USE_CLEARML:\n",
+        "    from clearml import Task\n",
+        "    task = Task.init(\n",
+        "        project_name=\"FocusGuards Large Group Project\",\n",
+        "        task_name=\"MLP Model Training\",\n",
+        "        tags=[\"training\", \"mlp\"]\n",
+        "    )\n",
+        "    task.connect(CFG)\n",
+        "    print(\"[ClearML] Connected\")\n",
+        "else:\n",
+        "    print(\"[ClearML] Disabled (set USE_CLEARML = True to enable)\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 3. Load data"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "def set_seed(seed):\n",
+        "    random.seed(seed)\n",
+        "    np.random.seed(seed)\n",
+        "    torch.manual_seed(seed)\n",
+        "    if torch.cuda.is_available():\n",
+        "        torch.cuda.manual_seed_all(seed)\n",
+        "\n",
+        "set_seed(CFG[\"seed\"])\n",
+        "\n",
+        "by_person, X_all, y_all = load_per_person(CFG[\"model_name\"])\n",
+        "person_names = sorted(by_person.keys())\n",
+        "num_features = X_all.shape[1]\n",
+        "num_classes = int(y_all.max()) + 1\n",
+        "print(f\"\\nPersons: {person_names}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 4. Random split (70/15/15) and scaling"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "splits, scaler = _split_and_scale(X_all, y_all, CFG[\"split_ratios\"], CFG[\"seed\"], CFG[\"scale\"])\n",
+        "X_train, y_train = splits[\"X_train\"], splits[\"y_train\"]\n",
+        "X_val, y_val = splits[\"X_val\"], splits[\"y_val\"]\n",
+        "X_test, y_test = splits[\"X_test\"], splits[\"y_test\"]\n",
+        "\n",
+        "print(f\"Features: {num_features}, Classes: {num_classes}\")\n",
+        "\n",
+        "def make_loader(X, y, batch_size, shuffle=False):\n",
+        "    ds = TensorDataset(torch.tensor(X, dtype=torch.float32), torch.tensor(y, dtype=torch.long))\n",
+        "    return DataLoader(ds, batch_size=batch_size, shuffle=shuffle)\n",
+        "\n",
+        "train_loader = make_loader(X_train, y_train, CFG[\"batch_size\"], shuffle=True)\n",
+        "val_loader = make_loader(X_val, y_val, CFG[\"batch_size\"])\n",
+        "test_loader = make_loader(X_test, y_test, CFG[\"batch_size\"])"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 5. Model definition"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "class MLP(nn.Module):\n",
+        "    def __init__(self, in_features, hidden_sizes, num_classes):\n",
+        "        super().__init__()\n",
+        "        layers = []\n",
+        "        prev = in_features\n",
+        "        for h in hidden_sizes:\n",
+        "            layers += [nn.Linear(prev, h), nn.ReLU()]\n",
+        "            prev = h\n",
+        "        layers.append(nn.Linear(prev, num_classes))\n",
+        "        self.network = nn.Sequential(*layers)\n",
+        "\n",
+        "    def forward(self, x):\n",
+        "        return self.network(x)\n",
+        "\n",
+        "\n",
+        "device = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n",
+        "model = MLP(num_features, CFG[\"hidden_sizes\"], num_classes).to(device)\n",
+        "criterion = nn.CrossEntropyLoss()\n",
+        "optimizer = optim.Adam(model.parameters(), lr=CFG[\"lr\"])\n",
+        "\n",
+        "param_count = sum(p.numel() for p in model.parameters())\n",
+        "print(f\"Model: MLP {[num_features] + CFG['hidden_sizes'] + [num_classes]}\")\n",
+        "print(f\"Parameters: {param_count:,}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 6. Training loop (per-epoch logging)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "history = {\n",
+        "    \"model_name\": f\"mlp_{CFG['model_name']}\",\n",
+        "    \"param_count\": param_count,\n",
+        "    \"epochs\": [],\n",
+        "    \"train_loss\": [],\n",
+        "    \"train_acc\": [],\n",
+        "    \"val_loss\": [],\n",
+        "    \"val_acc\": [],\n",
+        "}\n",
+        "best_val_acc = 0.0\n",
+        "best_ckpt_path = os.path.join(CFG[\"checkpoints_dir\"], \"mlp_best.pt\")\n",
+        "os.makedirs(CFG[\"checkpoints_dir\"], exist_ok=True)\n",
+        "\n",
+        "print(f\"{'Epoch':>6} | {'Train Loss':>10} | {'Train Acc':>9} | {'Val Loss':>10} | {'Val Acc':>9}\")\n",
+        "print(\"-\" * 60)\n",
+        "\n",
+        "for epoch in range(1, CFG[\"epochs\"] + 1):\n",
+        "    model.train()\n",
+        "    t_loss, t_correct, t_total = 0.0, 0, 0\n",
+        "    for xb, yb in train_loader:\n",
+        "        xb, yb = xb.to(device), yb.to(device)\n",
+        "        optimizer.zero_grad()\n",
+        "        out = model(xb)\n",
+        "        loss = criterion(out, yb)\n",
+        "        loss.backward()\n",
+        "        optimizer.step()\n",
+        "        t_loss += loss.item() * xb.size(0)\n",
+        "        t_correct += (out.argmax(1) == yb).sum().item()\n",
+        "        t_total += xb.size(0)\n",
+        "    train_loss = t_loss / t_total\n",
+        "    train_acc = t_correct / t_total\n",
+        "\n",
+        "    model.eval()\n",
+        "    v_loss, v_correct, v_total = 0.0, 0, 0\n",
+        "    with torch.no_grad():\n",
+        "        for xb, yb in val_loader:\n",
+        "            xb, yb = xb.to(device), yb.to(device)\n",
+        "            out = model(xb)\n",
+        "            loss = criterion(out, yb)\n",
+        "            v_loss += loss.item() * xb.size(0)\n",
+        "            v_correct += (out.argmax(1) == yb).sum().item()\n",
+        "            v_total += xb.size(0)\n",
+        "    val_loss = v_loss / v_total\n",
+        "    val_acc = v_correct / v_total\n",
+        "\n",
+        "    history[\"epochs\"].append(epoch)\n",
+        "    history[\"train_loss\"].append(round(train_loss, 4))\n",
+        "    history[\"train_acc\"].append(round(train_acc, 4))\n",
+        "    history[\"val_loss\"].append(round(val_loss, 4))\n",
+        "    history[\"val_acc\"].append(round(val_acc, 4))\n",
+        "\n",
+        "    if task is not None:\n",
+        "        task.logger.report_scalar(\"Loss\", \"Train\", float(train_loss), iteration=epoch)\n",
+        "        task.logger.report_scalar(\"Loss\", \"Val\", float(val_loss), iteration=epoch)\n",
+        "        task.logger.report_scalar(\"Accuracy\", \"Train\", float(train_acc), iteration=epoch)\n",
+        "        task.logger.report_scalar(\"Accuracy\", \"Val\", float(val_acc), iteration=epoch)\n",
+        "        task.logger.report_scalar(\"Learning Rate\", \"LR\", float(optimizer.param_groups[0][\"lr\"]), iteration=epoch)\n",
+        "        task.logger.flush()\n",
+        "\n",
+        "    marker = \"\"\n",
+        "    if val_acc > best_val_acc:\n",
+        "        best_val_acc = val_acc\n",
+        "        torch.save(model.state_dict(), best_ckpt_path)\n",
+        "        marker = \" *\"\n",
+        "\n",
+        "    print(f\"{epoch:>6} | {train_loss:>10.4f} | {train_acc:>8.2%} | {val_loss:>10.4f} | {val_acc:>8.2%}{marker}\")\n",
+        "\n",
+        "print(f\"\\nBest val accuracy: {best_val_acc:.2%}\")\n",
+        "print(f\"Checkpoint: {best_ckpt_path}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 7. Loss and accuracy curves"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4))\n",
+        "epochs = history[\"epochs\"]\n",
+        "ax1.plot(epochs, history[\"train_loss\"], label=\"Train\")\n",
+        "ax1.plot(epochs, history[\"val_loss\"], label=\"Val\")\n",
+        "ax1.set_xlabel(\"Epoch\"); ax1.set_ylabel(\"Loss\"); ax1.set_title(\"Loss\"); ax1.legend()\n",
+        "ax2.plot(epochs, history[\"train_acc\"], label=\"Train\")\n",
+        "ax2.plot(epochs, history[\"val_acc\"], label=\"Val\")\n",
+        "ax2.set_xlabel(\"Epoch\"); ax2.set_ylabel(\"Accuracy\"); ax2.set_title(\"Accuracy\"); ax2.legend()\n",
+        "plt.suptitle(f\"MLP Training — {CFG['model_name']}\")\n",
+        "plt.tight_layout()\n",
+        "plt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 8. Test evaluation (random split)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "model.load_state_dict(torch.load(best_ckpt_path, weights_only=True))\n",
+        "model.eval()\n",
+        "\n",
+        "all_preds, all_labels, all_probs = [], [], []\n",
+        "test_loss_sum, test_total = 0.0, 0\n",
+        "with torch.no_grad():\n",
+        "    for xb, yb in test_loader:\n",
+        "        xb, yb = xb.to(device), yb.to(device)\n",
+        "        out = model(xb)\n",
+        "        test_loss_sum += criterion(out, yb).item() * xb.size(0)\n",
+        "        test_total += xb.size(0)\n",
+        "        probs = torch.softmax(out, dim=1)\n",
+        "        all_preds.extend(out.argmax(1).cpu().numpy())\n",
+        "        all_labels.extend(yb.cpu().numpy())\n",
+        "        all_probs.extend(probs.cpu().numpy())\n",
+        "\n",
+        "test_loss = test_loss_sum / test_total\n",
+        "test_preds = np.array(all_preds)\n",
+        "test_labels = np.array(all_labels)\n",
+        "test_probs = np.array(all_probs)\n",
+        "\n",
+        "test_acc = float(accuracy_score(test_labels, test_preds))\n",
+        "test_f1 = float(f1_score(test_labels, test_preds, average=\"weighted\"))\n",
+        "if num_classes > 2:\n",
+        "    test_auc = float(roc_auc_score(test_labels, test_probs, multi_class=\"ovr\", average=\"weighted\"))\n",
+        "else:\n",
+        "    test_auc = float(roc_auc_score(test_labels, test_probs[:, 1]))\n",
+        "\n",
+        "print(f\"[TEST] Loss:     {test_loss:.4f}\")\n",
+        "print(f\"[TEST] Accuracy: {test_acc:.2%}\")\n",
+        "print(f\"[TEST] F1:       {test_f1:.4f}\")\n",
+        "print(f\"[TEST] ROC-AUC:  {test_auc:.4f}\")\n",
+        "\n",
+        "if task is not None:\n",
+        "    task.logger.report_single_value(\"test_accuracy\", test_acc)\n",
+        "    task.logger.report_single_value(\"test_f1\", test_f1)\n",
+        "    task.logger.report_single_value(\"test_auc\", test_auc)\n",
+        "    task.logger.flush()\n",
+        "\n",
+        "print(\"\\nClassification report:\")\n",
+        "print(classification_report(test_labels, test_preds, target_names=[\"Unfocused (0)\", \"Focused (1)\"]))"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 9. Confusion matrix"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "fig, ax = plt.subplots(figsize=(5, 4))\n",
+        "cm = confusion_matrix(test_labels, test_preds)\n",
+        "ConfusionMatrixDisplay(cm, display_labels=[\"Unfocused\", \"Focused\"]).plot(ax=ax, cmap=\"Blues\")\n",
+        "ax.set_title(f\"MLP confusion matrix — test acc {test_acc:.2%}\")\n",
+        "plt.tight_layout()\n",
+        "plt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 10. Save checkpoint and JSON log"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "history[\"test_loss\"] = round(test_loss, 4)\n",
+        "history[\"test_acc\"] = round(test_acc, 4)\n",
+        "history[\"test_f1\"] = round(test_f1, 4)\n",
+        "history[\"test_auc\"] = round(test_auc, 4)\n",
+        "\n",
+        "os.makedirs(CFG[\"logs_dir\"], exist_ok=True)\n",
+        "log_path = os.path.join(CFG[\"logs_dir\"], f\"mlp_{CFG['model_name']}_training_log.json\")\n",
+        "with open(log_path, \"w\") as f:\n",
+        "    json.dump(history, f, indent=2)\n",
+        "\n",
+        "print(f\"[CKPT] Best model: {best_ckpt_path}\")\n",
+        "print(f\"[LOG]  History:    {log_path}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 11. LOPO comparison (MLP)\n",
+        "\n",
+        "Train+test with Leave-One-Person-Out so we can compare fairly with XGBoost/RF under LOPO."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "def train_mlp_on_splits(X_train, y_train, X_test, y_test, cfg, n_features, n_classes):\n",
+        "    device = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n",
+        "    sc = StandardScaler()\n",
+        "    X_tr = sc.fit_transform(X_train)\n",
+        "    X_te = sc.transform(X_test)\n",
+        "\n",
+        "    tr_ds = TensorDataset(torch.tensor(X_tr, dtype=torch.float32), torch.tensor(y_train, dtype=torch.long))\n",
+        "    te_ds = TensorDataset(torch.tensor(X_te, dtype=torch.float32), torch.tensor(y_test, dtype=torch.long))\n",
+        "    tr_loader = DataLoader(tr_ds, batch_size=cfg[\"batch_size\"], shuffle=True)\n",
+        "    te_loader = DataLoader(te_ds, batch_size=cfg[\"batch_size\"])\n",
+        "\n",
+        "    net = MLP(n_features, cfg[\"hidden_sizes\"], n_classes).to(device)\n",
+        "    opt = optim.Adam(net.parameters(), lr=cfg[\"lr\"])\n",
+        "    crit = nn.CrossEntropyLoss()\n",
+        "\n",
+        "    for _ in range(cfg[\"epochs\"]):\n",
+        "        net.train()\n",
+        "        for xb, yb in tr_loader:\n",
+        "            xb, yb = xb.to(device), yb.to(device)\n",
+        "            opt.zero_grad()\n",
+        "            crit(net(xb), yb).backward()\n",
+        "            opt.step()\n",
+        "\n",
+        "    net.eval()\n",
+        "    preds_list, probs_list, labels_list = [], [], []\n",
+        "    with torch.no_grad():\n",
+        "        for xb, yb in te_loader:\n",
+        "            xb = xb.to(device)\n",
+        "            out = net(xb)\n",
+        "            preds_list.extend(out.argmax(1).cpu().numpy())\n",
+        "            probs_list.extend(torch.softmax(out, dim=1).cpu().numpy())\n",
+        "            labels_list.extend(yb.numpy())\n",
+        "\n",
+        "    preds = np.array(preds_list)\n",
+        "    probs = np.array(probs_list)\n",
+        "    labels = np.array(labels_list)\n",
+        "    acc = accuracy_score(labels, preds)\n",
+        "    f1 = f1_score(labels, preds, average=\"weighted\")\n",
+        "    auc = roc_auc_score(labels, probs[:, 1]) if n_classes == 2 else roc_auc_score(labels, probs, multi_class=\"ovr\", average=\"weighted\")\n",
+        "    return {\"accuracy\": acc, \"f1\": f1, \"roc_auc\": auc}"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "print(\"MLP LOPO evaluation\")\n",
+        "print(\"-\" * 60)\n",
+        "\n",
+        "lopo_results = []\n",
+        "for test_person in person_names:\n",
+        "    train_persons = [p for p in person_names if p != test_person]\n",
+        "    X_tr = np.concatenate([by_person[p][0] for p in train_persons], axis=0)\n",
+        "    y_tr = np.concatenate([by_person[p][1] for p in train_persons], axis=0)\n",
+        "    X_te, y_te = by_person[test_person]\n",
+        "\n",
+        "    set_seed(CFG[\"seed\"])\n",
+        "    metrics = train_mlp_on_splits(X_tr, y_tr, X_te, y_te, CFG, num_features, num_classes)\n",
+        "    metrics[\"test_person\"] = test_person\n",
+        "    metrics[\"n_test\"] = len(y_te)\n",
+        "    lopo_results.append(metrics)\n",
+        "    print(f\"  test={test_person}: acc={metrics['accuracy']:.2%}  F1={metrics['f1']:.4f}  AUC={metrics['roc_auc']:.4f}  (n={len(y_te)})\")\n",
+        "\n",
+        "print(\"\\nMLP LOPO summary (mean +/- std):\")\n",
+        "for m in [\"accuracy\", \"f1\", \"roc_auc\"]:\n",
+        "    vals = [r[m] for r in lopo_results]\n",
+        "    print(f\"  {m}: {np.mean(vals):.4f} +/- {np.std(vals):.4f}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 12. Random split vs LOPO summary"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import pandas as pd\n",
+        "\n",
+        "lopo_acc = np.mean([r[\"accuracy\"] for r in lopo_results])\n",
+        "lopo_f1 = np.mean([r[\"f1\"] for r in lopo_results])\n",
+        "lopo_auc = np.mean([r[\"roc_auc\"] for r in lopo_results])\n",
+        "\n",
+        "summary = pd.DataFrame([\n",
+        "    {\"Method\": \"Random split (70/15/15)\", \"Accuracy\": f\"{test_acc:.2%}\", \"F1\": f\"{test_f1:.4f}\", \"ROC-AUC\": f\"{test_auc:.4f}\"},\n",
+        "    {\"Method\": \"LOPO (mean)\", \"Accuracy\": f\"{lopo_acc:.2%}\", \"F1\": f\"{lopo_f1:.4f}\", \"ROC-AUC\": f\"{lopo_auc:.4f}\"},\n",
+        "])\n",
+        "display(summary)\n",
+        "\n",
+        "print(\"\\nCompare these MLP LOPO numbers with XGBoost (from xgboost.ipynb).\")\n",
+        "print(\"If XGB LOPO > MLP LOPO, XGB generalises better across unseen persons.\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 13. Per-person accuracy bar chart"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "fig, ax = plt.subplots(figsize=(10, 4))\n",
+        "names_sorted = [r[\"test_person\"] for r in lopo_results]\n",
+        "accs = [r[\"accuracy\"] for r in lopo_results]\n",
+        "ax.bar(names_sorted, accs, color=\"steelblue\", edgecolor=\"black\")\n",
+        "ax.axhline(y=lopo_acc, color=\"red\", linestyle=\"--\", label=f\"Mean = {lopo_acc:.2%}\")\n",
+        "ax.set_ylabel(\"Accuracy\")\n",
+        "ax.set_xlabel(\"Left-out person\")\n",
+        "ax.set_title(\"MLP LOPO: test accuracy per left-out person\")\n",
+        "ax.legend()\n",
+        "plt.xticks(rotation=45, ha=\"right\")\n",
+        "plt.tight_layout()\n",
+        "plt.show()"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.13.0"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}

notebooks/xgboost.ipynb

@@ -0,0 +1,475 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# XGBoost Training + LOPO evaluation (ClearML-compatible)\n",
+        "\n",
+        "XGBoost for focus classification.\n",
+        "- Single CFG dict (ClearML `task.connect(CFG)`)\n",
+        "- 70/15/15 stratified random split with per-round loss logging\n",
+        "- Test evaluation: accuracy, F1, ROC-AUC\n",
+        "- ClearML scalar logging (opt-in)\n",
+        "- LOPO comparison at the end"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 1. Imports and CFG"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import json\n",
+        "import os\n",
+        "import sys\n",
+        "import random\n",
+        "\n",
+        "import numpy as np\n",
+        "from xgboost import XGBClassifier\n",
+        "from sklearn.model_selection import train_test_split\n",
+        "from sklearn.metrics import (\n",
+        "    accuracy_score, f1_score, roc_auc_score,\n",
+        "    classification_report, confusion_matrix, ConfusionMatrixDisplay,\n",
+        ")\n",
+        "import matplotlib.pyplot as plt\n",
+        "import warnings\n",
+        "warnings.filterwarnings(\"ignore\")\n",
+        "\n",
+        "# Add project root to sys.path\n",
+        "_cwd = os.getcwd()\n",
+        "PROJECT_ROOT = _cwd if os.path.isdir(os.path.join(_cwd, \"models\")) else os.path.abspath(os.path.join(_cwd, \"..\"))\n",
+        "if PROJECT_ROOT not in sys.path:\n",
+        "    sys.path.insert(0, PROJECT_ROOT)\n",
+        "\n",
+        "from data_preparation.prepare_dataset import load_per_person, SELECTED_FEATURES, _split_and_scale\n",
+        "\n",
+        "CFG = {\n",
+        "    \"model_name\": \"face_orientation\",\n",
+        "    \"seed\": 42,\n",
+        "    \"split_ratios\": (0.7, 0.15, 0.15),\n",
+        "    \"scale\": False,  # tree-based model — scaling unnecessary\n",
+        "    \"n_estimators\": 600,\n",
+        "    \"max_depth\": 8,\n",
+        "    \"learning_rate\": 0.149,\n",
+        "    \"subsample\": 0.9625,\n",
+        "    \"colsample_bytree\": 0.9013,\n",
+        "    \"reg_alpha\": 1.1407,\n",
+        "    \"reg_lambda\": 2.4181,\n",
+        "    \"eval_metric\": \"logloss\",\n",
+        "    \"checkpoints_dir\": os.path.join(PROJECT_ROOT, \"models\", \"xgboost\", \"checkpoints\"),\n",
+        "    \"logs_dir\": os.path.join(PROJECT_ROOT, \"evaluation\", \"logs\"),\n",
+        "}\n",
+        "\n",
+        "print(f\"Project root: {PROJECT_ROOT}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 2. ClearML (optional)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "USE_CLEARML = False  # set True when ClearML credentials are configured\n",
+        "task = None\n",
+        "\n",
+        "if USE_CLEARML:\n",
+        "    from clearml import Task\n",
+        "    task = Task.init(\n",
+        "        project_name=\"FocusGuards Large Group Project\",\n",
+        "        task_name=\"XGBoost Training + LOPO\",\n",
+        "        tags=[\"training\", \"xgboost\"]\n",
+        "    )\n",
+        "    task.connect(CFG)\n",
+        "    print(\"[ClearML] Connected\")\n",
+        "else:\n",
+        "    print(\"[ClearML] Disabled (set USE_CLEARML = True to enable)\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 3. Load data"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "def set_seed(seed):\n",
+        "    random.seed(seed)\n",
+        "    np.random.seed(seed)\n",
+        "\n",
+        "set_seed(CFG[\"seed\"])\n",
+        "\n",
+        "by_person, X_all, y_all = load_per_person(CFG[\"model_name\"])\n",
+        "person_names = sorted(by_person.keys())\n",
+        "num_features = X_all.shape[1]\n",
+        "num_classes = int(y_all.max()) + 1\n",
+        "print(f\"\\nPersons: {person_names}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 4. Random split (70/15/15)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "splits, _ = _split_and_scale(X_all, y_all, CFG[\"split_ratios\"], CFG[\"seed\"], CFG[\"scale\"])\n",
+        "X_train, y_train = splits[\"X_train\"], splits[\"y_train\"]\n",
+        "X_val, y_val = splits[\"X_val\"], splits[\"y_val\"]\n",
+        "X_test, y_test = splits[\"X_test\"], splits[\"y_test\"]\n",
+        "\n",
+        "print(f\"Features: {num_features}, Classes: {num_classes}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 5. Model definition and training"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "model = XGBClassifier(\n",
+        "    n_estimators=CFG[\"n_estimators\"],\n",
+        "    max_depth=CFG[\"max_depth\"],\n",
+        "    learning_rate=CFG[\"learning_rate\"],\n",
+        "    subsample=CFG[\"subsample\"],\n",
+        "    colsample_bytree=CFG[\"colsample_bytree\"],\n",
+        "    reg_alpha=CFG[\"reg_alpha\"],\n",
+        "    reg_lambda=CFG[\"reg_lambda\"],\n",
+        "    eval_metric=CFG[\"eval_metric\"],\n",
+        "    use_label_encoder=False,\n",
+        "    random_state=CFG[\"seed\"],\n",
+        "    verbosity=1,\n",
+        ")\n",
+        "\n",
+        "model.fit(\n",
+        "    X_train, y_train,\n",
+        "    eval_set=[(X_train, y_train), (X_val, y_val)],\n",
+        "    verbose=10,\n",
+        ")\n",
+        "\n",
+        "print(f\"\\n[TRAIN] Training complete: {CFG['n_estimators']} rounds\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 6. Per-round loss logging"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "evals = model.evals_result()\n",
+        "train_losses = evals[\"validation_0\"][CFG[\"eval_metric\"]]\n",
+        "val_losses = evals[\"validation_1\"][CFG[\"eval_metric\"]]\n",
+        "rounds = list(range(1, len(train_losses) + 1))\n",
+        "\n",
+        "if task is not None:\n",
+        "    for i, (tl, vl) in enumerate(zip(train_losses, val_losses)):\n",
+        "        task.logger.report_scalar(\"Loss\", \"Train\", tl, iteration=i + 1)\n",
+        "        task.logger.report_scalar(\"Loss\", \"Val\", vl, iteration=i + 1)\n",
+        "    task.logger.flush()\n",
+        "\n",
+        "print(f\"Final train logloss: {train_losses[-1]:.4f}\")\n",
+        "print(f\"Final val logloss:   {val_losses[-1]:.4f}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 7. Loss curve"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "fig, ax = plt.subplots(figsize=(8, 4))\n",
+        "ax.plot(rounds, train_losses, label=\"Train\")\n",
+        "ax.plot(rounds, val_losses, label=\"Val\")\n",
+        "ax.set_xlabel(\"Boosting round\")\n",
+        "ax.set_ylabel(\"Log loss\")\n",
+        "ax.set_title(f\"XGBoost Training — {CFG['model_name']}\")\n",
+        "ax.legend()\n",
+        "plt.tight_layout()\n",
+        "plt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 8. Test evaluation (random split)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "test_preds = model.predict(X_test)\n",
+        "test_probs = model.predict_proba(X_test)\n",
+        "test_acc = float(accuracy_score(y_test, test_preds))\n",
+        "test_f1 = float(f1_score(y_test, test_preds, average=\"weighted\"))\n",
+        "if num_classes > 2:\n",
+        "    test_auc = float(roc_auc_score(y_test, test_probs, multi_class=\"ovr\", average=\"weighted\"))\n",
+        "else:\n",
+        "    test_auc = float(roc_auc_score(y_test, test_probs[:, 1]))\n",
+        "\n",
+        "print(f\"[TEST] Accuracy: {test_acc:.2%}\")\n",
+        "print(f\"[TEST] F1:       {test_f1:.4f}\")\n",
+        "print(f\"[TEST] ROC-AUC:  {test_auc:.4f}\")\n",
+        "\n",
+        "if task is not None:\n",
+        "    task.logger.report_single_value(\"test_accuracy\", test_acc)\n",
+        "    task.logger.report_single_value(\"test_f1\", test_f1)\n",
+        "    task.logger.report_single_value(\"test_auc\", test_auc)\n",
+        "    task.logger.flush()\n",
+        "\n",
+        "print(\"\\nClassification report:\")\n",
+        "print(classification_report(y_test, test_preds, target_names=[\"Unfocused (0)\", \"Focused (1)\"]))"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 9. Confusion matrix"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "fig, ax = plt.subplots(figsize=(5, 4))\n",
+        "cm = confusion_matrix(y_test, test_preds)\n",
+        "ConfusionMatrixDisplay(cm, display_labels=[\"Unfocused\", \"Focused\"]).plot(ax=ax, cmap=\"Blues\")\n",
+        "ax.set_title(f\"XGBoost confusion matrix — test acc {test_acc:.2%}\")\n",
+        "plt.tight_layout()\n",
+        "plt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 10. Save checkpoint and JSON log"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "os.makedirs(CFG[\"checkpoints_dir\"], exist_ok=True)\n",
+        "model_path = os.path.join(CFG[\"checkpoints_dir\"], f\"{CFG['model_name']}_best.json\")\n",
+        "model.save_model(model_path)\n",
+        "\n",
+        "history = {\n",
+        "    \"model_name\": f\"xgboost_{CFG['model_name']}\",\n",
+        "    \"n_estimators\": CFG[\"n_estimators\"],\n",
+        "    \"max_depth\": CFG[\"max_depth\"],\n",
+        "    \"epochs\": rounds,\n",
+        "    \"train_loss\": [round(v, 4) for v in train_losses],\n",
+        "    \"val_loss\": [round(v, 4) for v in val_losses],\n",
+        "    \"test_acc\": round(test_acc, 4),\n",
+        "    \"test_f1\": round(test_f1, 4),\n",
+        "    \"test_auc\": round(test_auc, 4),\n",
+        "}\n",
+        "\n",
+        "os.makedirs(CFG[\"logs_dir\"], exist_ok=True)\n",
+        "log_path = os.path.join(CFG[\"logs_dir\"], f\"xgboost_{CFG['model_name']}_training_log.json\")\n",
+        "with open(log_path, \"w\") as f:\n",
+        "    json.dump(history, f, indent=2)\n",
+        "\n",
+        "print(f\"[CKPT] Model: {model_path}\")\n",
+        "print(f\"[LOG]  History: {log_path}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 11. LOPO comparison (XGBoost)\n",
+        "\n",
+        "Train+test with Leave-One-Person-Out so we can compare fairly with MLP/RF under LOPO."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "def train_xgb_on_splits(X_train, y_train, X_test, y_test, cfg):\n",
+        "    m = XGBClassifier(\n",
+        "        n_estimators=cfg[\"n_estimators\"],\n",
+        "        max_depth=cfg[\"max_depth\"],\n",
+        "        learning_rate=cfg[\"learning_rate\"],\n",
+        "        subsample=cfg[\"subsample\"],\n",
+        "        colsample_bytree=cfg[\"colsample_bytree\"],\n",
+        "        reg_alpha=cfg[\"reg_alpha\"],\n",
+        "        reg_lambda=cfg[\"reg_lambda\"],\n",
+        "        eval_metric=cfg[\"eval_metric\"],\n",
+        "        use_label_encoder=False,\n",
+        "        random_state=cfg[\"seed\"],\n",
+        "        verbosity=0,\n",
+        "    )\n",
+        "    m.fit(X_train, y_train, verbose=False)\n",
+        "\n",
+        "    preds = m.predict(X_test)\n",
+        "    probs = m.predict_proba(X_test)\n",
+        "    n_cls = probs.shape[1]\n",
+        "    acc = accuracy_score(y_test, preds)\n",
+        "    f1 = f1_score(y_test, preds, average=\"weighted\")\n",
+        "    auc = roc_auc_score(y_test, probs[:, 1]) if n_cls == 2 else roc_auc_score(y_test, probs, multi_class=\"ovr\", average=\"weighted\")\n",
+        "    return {\"accuracy\": acc, \"f1\": f1, \"roc_auc\": auc}"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "print(\"XGBoost LOPO evaluation\")\n",
+        "print(\"-\" * 60)\n",
+        "\n",
+        "lopo_results = []\n",
+        "for test_person in person_names:\n",
+        "    train_persons = [p for p in person_names if p != test_person]\n",
+        "    X_tr = np.concatenate([by_person[p][0] for p in train_persons], axis=0)\n",
+        "    y_tr = np.concatenate([by_person[p][1] for p in train_persons], axis=0)\n",
+        "    X_te, y_te = by_person[test_person]\n",
+        "\n",
+        "    set_seed(CFG[\"seed\"])\n",
+        "    metrics = train_xgb_on_splits(X_tr, y_tr, X_te, y_te, CFG)\n",
+        "    metrics[\"test_person\"] = test_person\n",
+        "    metrics[\"n_test\"] = len(y_te)\n",
+        "    lopo_results.append(metrics)\n",
+        "    print(f\"  test={test_person}: acc={metrics['accuracy']:.2%}  F1={metrics['f1']:.4f}  AUC={metrics['roc_auc']:.4f}  (n={len(y_te)})\")\n",
+        "\n",
+        "print(\"\\nXGBoost LOPO summary (mean +/- std):\")\n",
+        "for m in [\"accuracy\", \"f1\", \"roc_auc\"]:\n",
+        "    vals = [r[m] for r in lopo_results]\n",
+        "    print(f\"  {m}: {np.mean(vals):.4f} +/- {np.std(vals):.4f}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 12. Random split vs LOPO summary"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import pandas as pd\n",
+        "\n",
+        "lopo_acc = np.mean([r[\"accuracy\"] for r in lopo_results])\n",
+        "lopo_f1 = np.mean([r[\"f1\"] for r in lopo_results])\n",
+        "lopo_auc = np.mean([r[\"roc_auc\"] for r in lopo_results])\n",
+        "\n",
+        "summary = pd.DataFrame([\n",
+        "    {\"Method\": \"Random split (70/15/15)\", \"Accuracy\": f\"{test_acc:.2%}\", \"F1\": f\"{test_f1:.4f}\", \"ROC-AUC\": f\"{test_auc:.4f}\"},\n",
+        "    {\"Method\": \"LOPO (mean)\", \"Accuracy\": f\"{lopo_acc:.2%}\", \"F1\": f\"{lopo_f1:.4f}\", \"ROC-AUC\": f\"{lopo_auc:.4f}\"},\n",
+        "])\n",
+        "display(summary)\n",
+        "\n",
+        "print(\"\\nPer-fold LOPO results:\")\n",
+        "display(pd.DataFrame(lopo_results))\n",
+        "\n",
+        "print(\"\\nCompare these XGBoost LOPO numbers with MLP (from mlp.ipynb).\")\n",
+        "print(\"If XGB LOPO > MLP LOPO, XGB generalises better across unseen persons.\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 13. Per-person accuracy bar chart"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "fig, ax = plt.subplots(figsize=(10, 4))\n",
+        "names_sorted = [r[\"test_person\"] for r in lopo_results]\n",
+        "accs = [r[\"accuracy\"] for r in lopo_results]\n",
+        "ax.bar(names_sorted, accs, color=\"steelblue\", edgecolor=\"black\")\n",
+        "ax.axhline(y=lopo_acc, color=\"red\", linestyle=\"--\", label=f\"Mean = {lopo_acc:.2%}\")\n",
+        "ax.set_ylabel(\"Accuracy\")\n",
+        "ax.set_xlabel(\"Left-out person\")\n",
+        "ax.set_title(\"XGBoost LOPO: test accuracy per left-out person\")\n",
+        "ax.legend()\n",
+        "plt.xticks(rotation=45, ha=\"right\")\n",
+        "plt.tight_layout()\n",
+        "plt.show()"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.13.0"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}

tests/test_data_preparation.py

@@ -0,0 +1,39 @@
+import os
+import sys
+import numpy as np
+
+
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, PROJECT_ROOT)
+
+from data_preparation.prepare_dataset import (
+    SELECTED_FEATURES,
+    _generate_synthetic_data,
+    get_numpy_splits,
+)
+
+
+def test_generate_synthetic_data_shape():
+    X, y = _generate_synthetic_data("face_orientation")
+    assert X.shape[0] == 500
+    assert y.shape[0] == 500
+    assert X.shape[1] == len(SELECTED_FEATURES["face_orientation"])
+
+
+def test_get_numpy_splits_consistency():
+    splits, num_features, num_classes, scaler = get_numpy_splits("face_orientation")
+
+    # number of sample > 0，and split each in train/val/test
+    n_train = len(splits["y_train"])
+    n_val = len(splits["y_val"])
+    n_test = len(splits["y_test"])
+    assert n_train > 0
+    assert n_val > 0
+    assert n_test > 0
+
+    # feature dim should same as num_features
+    assert splits["X_train"].shape[1] == num_features
+
+    assert num_classes >= 2
+

tests/test_health_endpoint.py

@@ -0,0 +1,18 @@
+import pytest
+from fastapi.testclient import TestClient
+
+from main import app
+
+
+client = TestClient(app)
+
+
+def test_health_endpoint_ok():
+    resp = client.get("/health")
+    assert resp.status_code == 200
+    data = resp.json()
+    assert "status" in data
+    assert isinstance(data["status"], str)
+    assert "models_loaded" in data
+    assert isinstance(data["models_loaded"], list)
+

tests/test_models_clip_features.py

@@ -0,0 +1,47 @@
+import os
+import sys
+
+import numpy as np
+
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, PROJECT_ROOT)
+
+from ui.pipeline import _clip_features
+from models.collect_features import FEATURE_NAMES
+
+
+def test_clip_features_clamps_ranges():
+    idx = {name: i for i, name in enumerate(FEATURE_NAMES)}
+    vec = np.zeros(len(FEATURE_NAMES), dtype=np.float32)
+
+    # 设置超出合理范围的值
+    vec[idx["yaw"]] = 90.0
+    vec[idx["pitch"]] = -90.0
+    vec[idx["roll"]] = 90.0
+    vec[idx["head_deviation"]] = 999.0
+    for name in ("ear_left", "ear_right", "ear_avg"):
+        vec[idx[name]] = 2.0
+    vec[idx["mar"]] = 5.0
+    vec[idx["gaze_offset"]] = 1.0
+    vec[idx["perclos"]] = 2.0
+    vec[idx["blink_rate"]] = 100.0
+    vec[idx["closure_duration"]] = 50.0
+    vec[idx["yawn_duration"]] = 50.0
+
+    out = _clip_features(vec)
+
+    assert -45.0 <= out[idx["yaw"]] <= 45.0
+    assert -30.0 <= out[idx["pitch"]] <= 30.0
+    assert -30.0 <= out[idx["roll"]] <= 30.0
+
+    for name in ("ear_left", "ear_right", "ear_avg"):
+        assert 0.0 <= out[idx[name]] <= 0.85
+
+    assert 0.0 <= out[idx["mar"]] <= 1.0
+    assert 0.0 <= out[idx["gaze_offset"]] <= 0.5
+    assert 0.0 <= out[idx["perclos"]] <= 0.8
+    assert 0.0 <= out[idx["blink_rate"]] <= 30.0
+    assert 0.0 <= out[idx["closure_duration"]] <= 10.0
+    assert 0.0 <= out[idx["yawn_duration"]] <= 10.0
+