# Sprint 2 — Sichere multimodale Korrelationsschicht v1

**Status:** implementation in progress

## Ziel

Sprint 2 verbindet Apple Health, Ernährung, vollständig strukturierte Symptomtage,
tatsächlich verabreichte Adalimumab/Hyrimoz-Medikation und streng validierte
Laborwerte zu einer explorativen Hypothesenschicht. Die Quelldaten bleiben
unverändert in ihren geschützten Tabellen.

Die Schicht dient ausschließlich dazu, mögliche Fragen für Verlaufskontrolle und
ärztliche Gespräche zu priorisieren. Sie erzeugt keine Diagnose, keine
Kausalitätsbehauptung, keine Therapieempfehlung und keine Entwarnung.

## Tages-Features

| Modalität | Aufnahmebedingung | Semantik |
|---|---|---|
| Apple Health | Analytics-v2-Tagespunkt mit `quality=direct` | bereits kanonische Zürcher Lokaltage und metrikspezifische Aggregation |
| Ernährung | `histamine_score` aus `nutrition_daily_summary_v2`, mindestens ein Item und `histamine_unknown_count=0` | regelbasierter, ausdrücklich explorativer Score; unbekannte Produktklassifikationen machen den Tag unvollständig; Makro-/Nährstoffspalten bleiben bis zum separaten YAZIO-Einheiten-Audit ausgeschlossen |
| Symptome | `context=daily_quick_score`, alle sieben bekannten Dimensionen exakt einmal und explizit 0–3 dokumentiert | Summe nur für vollständige, duplikatfreie Tage; ein fehlender Tag ist nicht symptomfrei |
| Medikation | ausschließlich explizite Ereignistypen `administered`/`verabreicht`; Stopps, Pausen, Neustarts oder Dosiswechsel setzen die Phase konservativ auf `unknown` | kategoriale Stratifikation in Baseline, frühe und stabile Behandlungsphase |
| Labor | validiert, gegen Original geprüft, Referenzquelle `scanned_original`, Einheit vorhanden, exakter numerischer Wert und streng allowlist-basiertes Parameter-/Einheitenpaar | exaktes `YYYY-MM-DD` oder vollständig parsebares ISO-8601-Datetime mit `T` wird akzeptiert; ein gültiges Abnahmedatum wird bevorzugt, andernfalls wird ein gültiges Befunddatum verwendet; keine Vorwärtsfüllung; zensierte oder sonstige Same-Day-Duplikate schließen den Feature-Tag aus; persistiert werden nur feste technische Feature-IDs |

Tageswerte werden im Speicher verbunden. Persistiert werden ausschließlich
aggregierte Korrelationsresultate, keine neue Kopie der täglichen Rohwerte.

## Statistische Regeln

1. Spearman-Rangkorrelation statt linearer Pearson-Annahme.
2. Complete-case-Auswertung: nur tatsächlich vorhandene Prädiktor-/Zielpaare.
3. Lags 0 bis 3 bedeuten: Prädiktor am Tag `d`, Symptomziel am Tag `d + lag`.
4. Lag-Paare dürfen keine Behandlungsphasengrenze überschreiten; strukturell ausgeschlossene Lag-Randtage zählen nicht als Missingness.
5. Keine phasenübergreifende Gesamtkorrelation, sobald unterschiedliche Behandlungsphasen vorliegen.
6. Ziel-Coverage im jeweils überlappenden Analysefenster muss mindestens 60 Prozent betragen.
7. Mindestens 14 vollständige Paare und mindestens drei unterschiedliche Werte auf beiden Achsen für eine Berechnung.
8. Der zweiseitige p-Wert stammt aus einer deterministischen Blockpermutation nach festen Kalenderwochen (Montag–Sonntag). Nur vorhandene Complete Cases werden innerhalb ihrer Kalenderwoche geordnet; jede beobachtete Teilwoche wird vollständig mitpermutiert. Der asymptotische iid-Spearman-p-Wert wird nicht verwendet.
9. Benjamini-Hochberg-Korrektur je Ziel und Behandlungsphase über alle getesteten Features und Lags mit gültigem Permutations-p-Wert.
10. Ein korrigiertes Ergebnis wird erst ab 30 Paaren und `q ≤ 0.10` als **exploratives Signal** bezeichnet. Auch dann bleibt es eine Hypothese.
11. Unterhalb der Schwellen wird nur `insufficient_n`, `insufficient_coverage` beziehungsweise „kein belastbares korrigiertes Signal“ ausgegeben.

## Missingness und Legacy-Sicherheit

- Nicht dokumentierte Symptome werden niemals als `0` interpretiert.
- Teilweise Quick-Logs bleiben teilweise und erzeugen keinen Total-Score.
- Das Quick-Log-CLI setzt nicht angegebene Dimensionen nicht mehr automatisch auf null, etikettiert alte Kontext-lose Zeilen nicht rückwirkend um und bezeichnet partielle Eingaben ausdrücklich nur als `partial_sum`.
- Dashboard-Charts bauen vollständige Kalenderachsen auf und verwenden `null` für vollständig fehlende Symptomtage sowie für Histamintage mit unbekannter Produktklassifikation; der Symptomscore nutzt denselben strikten, duplikatfreien Sieben-Dimensionen-Vertrag wie die Engine.
- Die Missing-as-zero-Legacy-Engine `nutrition_insights.py` wird weder durch Quick-Log noch YAZIO-Refresh gestartet.
- Automatische Legacy-Safe-/Trigger-Kandidaten, Behandlungsphasenmittelwerte und Ernährungsempfehlungen werden im Dashboard nicht mehr gelesen oder angezeigt. Manuell dokumentierte persönliche Toleranzen bleiben erhalten.

## Persistierte Resultate

`multimodal_correlation_results` enthält ausschließlich:

- Prädiktor- und Zielkennung,
- Lag und Behandlungsphase,
- Paarzahl, beobachtete und erwartete Ziel-Tage, Ziel-Coverage und Prädiktor-Missingness,
- Spearman `rho`, 7-Tage-Blockpermutations-`p` und korrigiertes `q`,
- Status, Methode, technische Qualitätsflags und nicht-kausale Interpretation,
- Berechnungszeitpunkt.

Es werden keine Tageswerte, Freitexte, Notizen, Quelldateinamen oder Apple-Health-
Quellnamen in der Resultattabelle gespeichert. Die Persistenzgrenze lehnt nicht
allowlist-basierte Prädiktoren, Ziele, Phasen, Status, Flags oder Interpretationen
sowie negative, nicht endliche, außerhalb ihrer Wertebereiche liegende oder
untereinander inkonsistente Aggregate vor dem Löschen beziehungsweise Schreiben
bestehender Resultate ab.

## Integration

- `multimodal_correlations.py`: Feature-Layer, Statistik und Aggregate-Persistenz.
- `health_pipeline.py correlations`: manueller Refresh.
- `health_symptom_quick_add.py`: Refresh nach Symptom-Updates.
- `yazio_nutrition_sync.py`: Refresh nach veränderten Ernährungsdaten.
- `health_dashboard_v3.py`: phasenstratifizierte Resultate mit `n`, `rho`, `q`,
  Status und ausdrücklichen Evidenzgrenzen.

## Grenzen

- Beobachtungsdaten bleiben anfällig für Rest-Confounding, Autokorrelation,
  Messfehler, Selektionsbias und zeitveränderliche Faktoren.
- Die feste 56-Tage-Grenze trennt nur eine technische frühe/stabile Phase und ist
  keine medizinische Wirksamkeitsschwelle.
- Seltene Laborabnahmen erreichen typischerweise keine ausreichende Paarzahl.
- Korrelationen dürfen nie allein eine Medikamenten-, Ernährungs- oder
  Behandlungsentscheidung auslösen.