# Academic Early-Warning Feature Experiment Suite

This project runs controlled E0–E9 experiments for predicting whether a student-course registration will finish with `target_grade10 < 5.0`.

## Core guarantees

- Training historical features use only semesters strictly earlier than each training row's target semester.
- All rows in the same semester receive features before that semester updates historical state.
- Test labels are never read during feature generation.
- Imputation and z-normalization use training statistics only.
- Raw student/course/registration identifiers and absolute semester codes are metadata, not model inputs.
- The MultiTaskNet architecture, effective-number class weighting, low-grade MSE weighting, optimizer, and losses match the accepted baseline.

## Experiments

| Code | Change |
|---|---|
| E0 | Original baseline |
| E1 | Remove constants, unstable registration timing, absolute semester codes, and one redundant course-risk complement |
| E2 | E1 + remove all `course_status_*` columns |
| E3 | E2 + conservative redundancy pruning |
| E4 | E3 + explicit history/missingness availability indicators |
| E5 | E4 + leak-safe student historical risk |
| E6 | E5 + dynamic course risk with empirical-Bayes smoothing |
| E7 | E6 + student-course history and compatibility interactions |
| E8 | E7 + academic-term/cohort context |
| E9 | E8 + exposure-normalized ratios, nonlinear thresholds, log transforms, workload deltas, and compressed curriculum counts |

## Data layout

```text
data/splits/expanding/
├── fold_1/<faculty>_train.csv
├── fold_1/<faculty>_test.csv
...
└── fold_7/<faculty>_test.csv
```

## Recommended workflow

Development screening only:

```bash
python3 run_experiments.py \
  --faculty khoa_cong_nghe_thong_tin \
  --splits_dir ./data/splits/expanding \
  --phase dev \
  --experiments all \
  > experiments_dev.log 2>&1
```

Fast smoke run:

```bash
python3 run_experiments.py \
  --faculty khoa_cong_nghe_thong_tin \
  --splits_dir ./data/splits/expanding \
  --phase dev \
  --experiments E0,E1,E2 \
  --epochs 1 \
  > smoke.log 2>&1
```

Confirm selected finalists on folds 6–7:

```bash
python3 run_experiments.py \
  --faculty khoa_cong_nghe_thong_tin \
  --splits_dir ./data/splits/expanding \
  --phase holdout \
  --experiments E0,E5,E7 \
  > finalists_holdout.log 2>&1
```

Inspect saved prediction errors:

```bash
python3 inspect_predictions.py \
  experiment_outputs/khoa_cong_nghe_thong_tin/E7_compatibility \
  > error_analysis.log 2>&1
```

## Output

Each experiment writes:

- `fold_metrics.csv`
- `equal_budget_metrics.csv`
- `training_diagnostics.csv`
- `feature_manifest.json`
- `summary.json`
- `predictions_fold_<n>.csv`

The faculty directory also receives `experiment_comparison_<phase>.csv`.

## Model-selection guidance

Use pooled development AP as the primary ranking metric, but inspect mean/worst fold AP and Recall/F2 at equal 10%, 15%, and 20% warning budgets. Do not select an experiment from holdout folds 6–7 after repeatedly inspecting them.
