#!/usr/bin/env python3
"""Audit returning/new-student and seen/new-course subgroups in walk-forward folds.

Definitions for each fold:
  Returning student: test IDSV appears in that fold's training CSV.
  New student:       test IDSV does not appear in that fold's training CSV.
  Seen course:       test IDMH appears in that fold's training CSV.
  New course:        test IDMH does not appear in that fold's training CSV.

The script reports both raw target-semester rows and model-evaluable rows. The
current test2.py keeps rows only when target_grade10 and target_grade4 are both
numeric, so model-evaluable statistics reproduce its evaluation population.
"""
from __future__ import annotations

import argparse
import csv
import json
import math
from collections import Counter, defaultdict
from pathlib import Path

MISSING = {"", "NULL", "null", "None", "none", "NaN", "nan", "N/A"}
GROUPS = (
    "Returning student + seen course",
    "Returning student + new course",
    "New student + seen course",
    "New student + new course",
)


def norm_id(value: str) -> str | None:
    value = value.strip()
    return None if value in MISSING else value


def as_float(value: str) -> float | None:
    value = value.strip()
    if value in MISSING:
        return None
    try:
        x = float(value)
    except ValueError:
        return None
    return None if math.isnan(x) else x


def load_seen_ids(train_path: Path) -> tuple[set[str], set[str]]:
    students: set[str] = set()
    courses: set[str] = set()
    with train_path.open("r", encoding="utf-8-sig", newline="") as f:
        reader = csv.DictReader(f)
        required = {"IDSV", "IDMH"}
        missing = required.difference(reader.fieldnames or [])
        if missing:
            raise KeyError(f"{train_path}: missing columns {sorted(missing)}")
        for row in reader:
            sid = norm_id(row["IDSV"])
            cid = norm_id(row["IDMH"])
            if sid is not None:
                students.add(sid)
            if cid is not None:
                courses.add(cid)
    return students, courses


def classify(seen_student: bool, seen_course: bool) -> str:
    if seen_student and seen_course:
        return GROUPS[0]
    if seen_student and not seen_course:
        return GROUPS[1]
    if not seen_student and seen_course:
        return GROUPS[2]
    return GROUPS[3]


def audit_fold(train_path: Path, test_path: Path, threshold: float = 5.0) -> dict:
    train_students, train_courses = load_seen_ids(train_path)

    raw = defaultdict(Counter)
    evaluable = defaultdict(Counter)
    unique_students = defaultdict(set)
    unique_courses = defaultdict(set)
    unseen_student_history = Counter()
    unseen_student_ids_by_history = defaultdict(set)
    invalid_rows = []

    with test_path.open("r", encoding="utf-8-sig", newline="") as f:
        reader = csv.DictReader(f)
        required = {"IDSV", "IDMH", "target_grade10"}
        missing = required.difference(reader.fieldnames or [])
        if missing:
            raise KeyError(f"{test_path}: missing columns {sorted(missing)}")

        has_grade4 = "target_grade4" in (reader.fieldnames or [])
        has_hist_count = "hist_semester_count" in (reader.fieldnames or [])
        has_gpa_missing = "student_gpa_history_missing_flag" in (reader.fieldnames or [])

        for row_number, row in enumerate(reader, start=2):
            sid = norm_id(row["IDSV"])
            cid = norm_id(row["IDMH"])
            seen_student = sid is not None and sid in train_students
            seen_course = cid is not None and cid in train_courses
            group = classify(seen_student, seen_course)

            y10 = as_float(row["target_grade10"])
            y4 = as_float(row["target_grade4"]) if has_grade4 else 0.0
            model_evaluable = y10 is not None and (not has_grade4 or y4 is not None)

            raw[group]["rows"] += 1
            if y10 is not None:
                raw[group]["valid_grade10"] += 1
                if y10 < threshold:
                    raw[group]["failures"] += 1
            if sid is not None:
                unique_students[group].add(sid)
            if cid is not None:
                unique_courses[group].add(cid)

            if model_evaluable:
                evaluable[group]["rows"] += 1
                if y10 < threshold:
                    evaluable[group]["failures"] += 1
            else:
                invalid_rows.append({
                    "row_number": row_number,
                    "IDSV": sid,
                    "IDMH": cid,
                    "group": group,
                    "target_grade10": row.get("target_grade10"),
                    "target_grade4": row.get("target_grade4"),
                })

            if not seen_student:
                hist_count = as_float(row.get("hist_semester_count", "")) if has_hist_count else None
                gpa_missing = as_float(row.get("student_gpa_history_missing_flag", "")) if has_gpa_missing else None
                no_history_by_count = hist_count is not None and hist_count <= 0
                no_history_by_flag = gpa_missing is not None and gpa_missing > 0
                if no_history_by_count or no_history_by_flag:
                    history_label = "unseen student + zero GPA/semester history"
                elif hist_count is not None and hist_count > 0:
                    history_label = "unseen student + historical semesters available"
                else:
                    history_label = "unseen student + history status unknown"
                unseen_student_history[history_label] += 1
                if sid is not None:
                    unseen_student_ids_by_history[history_label].add(sid)

    raw_total = sum(x["rows"] for x in raw.values())
    eval_total = sum(x["rows"] for x in evaluable.values())

    def rows_for(source, group):
        rows = source[group]["rows"]
        failures = source[group]["failures"]
        denominator = raw_total if source is raw else eval_total
        return {
            "group": group,
            "rows": rows,
            "row_proportion": rows / denominator if denominator else None,
            "failures": failures,
            "failure_rate": failures / rows if rows else None,
            "unique_students": len(unique_students[group]),
            "unique_courses": len(unique_courses[group]),
        }

    return {
        "train_file": str(train_path),
        "test_file": str(test_path),
        "train_unique_students": len(train_students),
        "train_unique_courses": len(train_courses),
        "raw_total_rows": raw_total,
        "model_evaluable_rows": eval_total,
        "invalid_for_test2_rows": invalid_rows,
        "raw_groups": [rows_for(raw, group) for group in GROUPS],
        "model_evaluable_groups": [rows_for(evaluable, group) for group in GROUPS],
        "unseen_student_history_rows": dict(unseen_student_history),
        "unseen_student_history_unique_students": {
            k: len(v) for k, v in unseen_student_ids_by_history.items()
        },
    }


def write_summary_csv(report: dict, path: Path) -> None:
    fields = [
        "fold", "test_semester", "population", "group", "rows",
        "row_proportion", "failures", "failure_rate",
        "unique_students", "unique_courses",
    ]
    with path.open("w", encoding="utf-8-sig", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=fields)
        writer.writeheader()
        for fold in report["folds"]:
            for population, key in (("raw", "raw_groups"), ("model_evaluable", "model_evaluable_groups")):
                for row in fold[key]:
                    writer.writerow({
                        "fold": fold["fold"],
                        "test_semester": fold["test_semester"],
                        "population": population,
                        **row,
                    })


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--splits-dir",
        type=Path,
        default=Path("data/splits/expanding"),
        help="Directory containing fold_1 ... fold_7",
    )
    parser.add_argument("--faculty", default="khoa_cong_nghe_thong_tin")
    parser.add_argument("--folds", default="1,2,3,4,5,6,7")
    parser.add_argument("--threshold", type=float, default=5.0)
    parser.add_argument("--json-out", type=Path, default=Path("cold_start_subgroups.json"))
    parser.add_argument("--csv-out", type=Path, default=Path("cold_start_subgroups.csv"))
    args = parser.parse_args()

    fold_numbers = [int(x.strip()) for x in args.folds.split(",") if x.strip()]
    report = {
        "definitions": {
            "returning_student": "IDSV appears in the same fold's training CSV",
            "new_student": "IDSV does not appear in the same fold's training CSV",
            "seen_course": "IDMH appears in the same fold's training CSV",
            "new_course": "IDMH does not appear in the same fold's training CSV",
            "model_evaluable": "target_grade10 and target_grade4 are numeric, matching test2.py",
        },
        "threshold": args.threshold,
        "folds": [],
    }

    for fold in fold_numbers:
        fold_dir = args.splits_dir / f"fold_{fold}"
        train_path = fold_dir / f"{args.faculty}_train.csv"
        test_path = fold_dir / f"{args.faculty}_test.csv"
        result = audit_fold(train_path, test_path, args.threshold)
        result["fold"] = fold
        # Read the target semester from the first data row.
        with test_path.open("r", encoding="utf-8-sig", newline="") as f:
            first = next(csv.DictReader(f), {})
        result["test_semester"] = first.get("target_NHHK")
        report["folds"].append(result)

    args.json_out.parent.mkdir(parents=True, exist_ok=True)
    args.csv_out.parent.mkdir(parents=True, exist_ok=True)
    args.json_out.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
    write_summary_csv(report, args.csv_out)

    for fold in report["folds"]:
        print(f"\nFold {fold['fold']} — semester {fold['test_semester']} — model-evaluable n={fold['model_evaluable_rows']:,}")
        for row in fold["model_evaluable_groups"]:
            print(
                f"  {row['group']:<38} rows={row['rows']:>5,} "
                f"share={row['row_proportion']:>7.2%} failures={row['failures']:>4,} "
                f"fail_rate={(row['failure_rate'] if row['failure_rate'] is not None else float('nan')):>7.2%}"
            )
        print("  unseen-student history rows:", fold["unseen_student_history_rows"])
        if fold["invalid_for_test2_rows"]:
            print("  rows excluded by test2.py:", fold["invalid_for_test2_rows"])

    print(f"\nSaved {args.json_out}")
    print(f"Saved {args.csv_out}")


if __name__ == "__main__":
    main()
