feat(training): add controlled 40-epoch baseline (#12)

Author: NafizNoyon

configs/training_balanced_e40.yaml

@@ -0,0 +1,31 @@
+# Controlled 40-epoch balanced CPU training experiment.
+# Only the training duration differs from the 20-epoch baseline.
+
+version: 1
+
+model:
+  weights: yolo11n.pt
+  task: detect
+
+dataset:
+  yaml: configs/bdd100k_balanced.yaml
+
+training:
+  epochs: 40
+  image_size: 320
+  batch_size: 4
+  device: cpu
+  workers: 0
+  fraction: 1.0
+  seed: 42
+  deterministic: true
+  amp: false
+  cache: false
+  validate: true
+  plots: true
+  class_weight_power: 0.0
+
+output:
+  project_directory: reports/training
+  run_name: cpu_balanced_baseline_e40
+  exist_ok: false

docs/longer_balanced_training_results.md

@@ -0,0 +1,106 @@
+# Controlled 40-Epoch Balanced Training Experiment
+
+## Objective
+
+This experiment tested whether extending the balanced CPU baseline
+from 20 to 40 epochs improved validation performance while keeping
+all other controlled training parameters unchanged.
+
+## Controlled setup
+
+| Setting | Value |
+|---|---|
+| Model | `yolo11n.pt` |
+| Training images | 2,000 |
+| Validation images | 500 |
+| Validation annotations | 9,615 |
+| Image size | 320 |
+| Batch size | 4 |
+| Device | CPU |
+| Seed | 42 |
+| Class weighting | Disabled |
+| Control duration | 20 epochs |
+| Experimental duration | 40 epochs |
+
+Only the training duration changed between the two checkpoints.
+
+## Training completion
+
+- Completed epochs: 40
+- Best epoch: 40
+- Final epoch: 40
+- Best mAP50 from training results: `0.14125`
+- Best mAP50-95 from training results: `0.07566`
+
+The best result occurring at epoch 40 indicates that the model had
+not clearly plateaued before the experiment ended.
+
+## Structured validation comparison
+
+| Metric | Epoch 20 | Epoch 40 | Relative change |
+|---|---:|---:|---:|
+| Precision | 0.519271 | 0.456200 | -12.15% |
+| Recall | 0.144212 | 0.155435 | +7.78% |
+| mAP50 | 0.117928 | 0.141271 | +19.79% |
+| mAP50-95 | 0.064557 | 0.075606 | +17.11% |
+
+The longer run improved recall and both mAP measurements while
+reducing aggregate precision.
+
+## Class-level AP50-95 changes
+
+| Class | Epoch 20 | Epoch 40 | Delta |
+|---|---:|---:|---:|
+| truck | 0.14351 | 0.17536 | +0.03185 |
+| bus | 0.11718 | 0.14479 | +0.02761 |
+| motorcycle | 0.00525 | 0.02344 | +0.01819 |
+| car | 0.24789 | 0.25933 | +0.01144 |
+| person | 0.05249 | 0.05971 | +0.00722 |
+| traffic sign | 0.04890 | 0.05344 | +0.00454 |
+| bicycle | 0.00213 | 0.00657 | +0.00444 |
+| rider | 0.01104 | 0.01441 | +0.00337 |
+| traffic light | 0.01718 | 0.01901 | +0.00183 |
+| train | 0.00000 | 0.00000 | 0.00000 |
+
+All evaluated classes except train improved in AP50-95. Train
+remained undetected because the pilot training split contains very
+few train annotations.
+
+## Confidence-threshold comparison
+
+Both checkpoints were compared using the same validation set at
+confidence thresholds from `0.05` through `0.50`.
+
+| Model | Best confidence | Precision | Recall | Micro F1 | TP | FP | FN |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| Epoch 20 | 0.20 | 0.5259 | 0.3041 | 0.38537 | 2,924 | 2,636 | 6,691 |
+| Epoch 40 | 0.20 | 0.5197 | 0.3273 | 0.40166 | 3,147 | 2,908 | 6,468 |
+
+Epoch 40 improved the best tested micro F1 by `0.016289`, which is
+approximately `4.23%` relative to the epoch-20 operating point.
+
+Epoch 40 also produced a higher F1 at every tested confidence
+threshold.
+
+## Engineering decision
+
+The 40-epoch checkpoint replaces the 20-epoch checkpoint as the
+deployment-oriented PyTorch baseline.
+
+- Selected checkpoint:
+  `reports/training/cpu_balanced_baseline_e40/weights/best.pt`
+- Selected initial confidence threshold: `0.20`
+- Epoch-20 checkpoint status: superseded baseline
+- Epoch-40 checkpoint status: selected baseline
+
+The selected threshold is an initial validation-set operating point
+and may require recalibration for a different deployment dataset.
+
+## Reproduction
+
+```powershell
+edge-traffic-train --config configs/training_balanced_e40.yaml
+```
+
+Generated weights, plots, logs, and evaluation reports are excluded
+from Git and must be regenerated locally.

docs/training.md

@@ -221,3 +221,23 @@ The deployment-oriented selection therefore remains:
 
 The complete controlled comparison is documented in
 [Partial Rare-Class Weighting Experiment](rare_class_weighting_results.md).
+
+## Controlled 40-epoch balanced training result
+
+Extending the controlled balanced baseline from 20 to 40 epochs
+increased structured-validation mAP50 by 19.79% and mAP50-95 by
+17.11%.
+
+At the best tested confidence threshold of `0.20`, the 40-epoch
+checkpoint achieved a micro F1 of `0.40166`, compared with
+`0.38537` for the 20-epoch checkpoint.
+
+The deployment-oriented baseline is now:
+
+- checkpoint: `cpu_balanced_baseline_e40/weights/best.pt`
+- initial confidence threshold: `0.20`
+- image size: `320`
+- class weighting: disabled
+
+The full controlled comparison is documented in
+[Controlled 40-Epoch Balanced Training Experiment](longer_balanced_training_results.md).