# Einheiten: backend/tft/model/calibrate.py
stand: f41ac76b5789

## backend/tft/model/calibrate.py::_ranks
beschreibung: Wandelt eine Liste von Werten in mittlere Ränge um und behandelt dabei gleiche Werte (Ties) korrekt.
input: Eine Liste von Float-Werten.
output: Eine Liste von Float-Rängen gleicher Länge mit 1-basierter Mittelrang-Vergabe bei Ties.
entscheidungen:
- Gleiche Werte erhalten alle den Mittelrang ihrer Position.
  beleg: "midrank = (i + j) / 2 + 1"
- Die Ränge sind 1-basiert.
  beleg: "ranks[order[k]] = midrank"
- Iteration erfolgt über sortierte Indizes statt über die Werte direkt.
  beleg: "order = sorted(range(len(values)), key=lambda i: values[i])"
kanten:
- wird-genutzt-von: backend/tft/model/calibrate.py::spearman

## backend/tft/model/calibrate.py::spearman
beschreibung: Berechnet den Spearman-Rangkorrelationskoeffizienten zwischen zwei gleichlangen Wertelisten.
input: Zwei gleich lange Listen von Float-Werten.
output: Der Spearman-Korrelationskoeffizient als Float, bei verschwindender Varianz 0.0.
entscheidungen:
- Division durch Null wird explizit abgefangen und mit 0.0 beantwortet.
  beleg: "if va == 0 or vb == 0:"
- Die Kovarianz und Varianzen werden als Populationsgrößen berechnet.
  beleg: "va = sum((x - ma) ** 2 for x in ra) ** 0.5"
kanten:
- ruft-auf: backend/tft/model/calibrate.py::_ranks
- wird-genutzt-von: backend/tft/model/calibrate.py::calibrate

## backend/tft/model/calibrate.py::board_from_row
beschreibung: Deserialisiert die aus der DB kommenden JSON-Strings für Units und Augments in Board-Strukturen.
input: Zwei JSON-Strings (Units und Augments).
output: Ein Tupel aus einer Liste von Unit-Dicts und einer Liste von Augment-Namen.
entscheidungen:
- Das Feld für Items heißt tolerant „itemNames" und wird mit Default-Leerliste gelesen.
  beleg: "\"items\": u.get(\"itemNames\", []),"
- Die Tier-Information der Unit wird als Sternzahl interpretiert.
  beleg: "\"stars\": u[\"tier\"],"
kanten:
- wird-genutzt-von: backend/tft/model/calibrate.py::_holdout_scores

## backend/tft/model/calibrate.py::_holdout_scores
beschreibung: Lädt Endboard-Zeilen aus der DB, baut daraus Boards je Match und lässt sie durch score_fn bewerten.
input: Eine DB-Connection, ein Artifact-Dict, ein Holdout-Flag und eine score-Funktion.
output: Ein Dict, das je match_id eine Liste von (placement, score)-Paaren enthält.
entscheidungen:
- Die Holdout-Filterung erfolgt match-bezogen über das letzte Zeichen der match_id.
  beleg: "where += \" AND substr(match_id, -1) IN ('0', '5')\""
- Das Set wird aus den Artifact-Metadaten als Filterparameter gelesen.
  beleg: "set_number = artifact[\"meta\"][\"set\"]"
kanten:
- ruft-auf: backend/tft/model/calibrate.py::board_from_row
- wird-genutzt-von: backend/tft/model/calibrate.py::calibrate

## backend/tft/model/calibrate.py::calibrate
beschreibung: Ermittelt die mittlere Spearman-Korrelation zwischen Board-Score und Platzierung über Holdout-Matches als Kalibrierungsmetrik.
input: Eine DB-Connection, ein Artifact-Dict, optional ein Holdout-Flag und eine score-Funktion.
output: Ein Dict mit „matches" (Anzahl) und „mean_spearman" (Mittelwert der Korrelationen).
entscheidungen:
- Nur Matches mit vollständigen 8 Spielern fließen in die Korrelation ein.
  beleg: "if len(players) < 8:"
- Die Korrelation wird negiert, da niedrigere Platzierungen besser sind.
  beleg: "correlations.append(-spearman(placements, scores))"
- Ohne Korrelationen wird 0.0 als Mittelwert zurückgegeben.
  beleg: "\"mean_spearman\": sum(correlations) / n if n else 0.0,"
kanten:
- ruft-auf: backend/tft/model/calibrate.py::_holdout_scores
- ruft-auf: backend/tft/model/calibrate.py::spearman