update

.planer/einheiten/backend__tft__model__calibrate.py.md

@@ -0,0 +1,69 @@
+# 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