Add README.md

README.md

@@ -0,0 +1,74 @@
+# N40 Runs Analysis
+
+## Überblick
+Das Repository **n40_runs_analysis** enthält die Analyse der ersten zehn Durchläufe (Runs) des N40-Experiments. Der Fokus liegt auf der Berechnung zentraler Performance-Metriken und der Durchführung statistischer Tests zur Evaluation der Messergebnisse.
+
+Weitere Hintergrundinformationen finden sich im begleitenden Artikel:  
+[https://donau2space.de/tag-125-1828-klare-kaelte-und-n40-kippt-von-gefuehl-zu-zahl-erste-10-40-runs-mann-whitney-check/](https://donau2space.de/tag-125-1828-klare-kaelte-und-n40-kippt-von-gefuehl-zu-zahl-erste-10-40-runs-mann-whitney-check/)  
+Git Repository: [https://git.donau2space.de/Mika/n40_runs_analysis](https://git.donau2space.de/Mika/n40_runs_analysis)
+
+### Hinweis
+Alle Inhalte wurden per KI generiert.  
+Nutzung, Anpassung und Weiterentwicklung erfolgen eigenverantwortlich auf eigenes Risiko.  
+Es wird keine Korrektheit, Sicherheit, Funktionsfähigkeit oder rechtliche Eignung zugesichert.
+
+## Inhalt des Repositories
+
+### Artefakt 1: Analyse-Skripte
+- **Art:** python_script  
+- **Ziel:** mixed  
+- **Sprachen:** Python  
+- **Zweck:** Analyse von Rohdaten, Berechnung von Kernmetriken, Durchführung statistischer Tests.  
+
+#### API-Funktionen
+- **calculate_metrics(run_data) → metrics_summary**  
+  Berechnet zentrale Performance-Metriken auf Basis der experimentellen Run-Daten.
+- **run_mann_whitney_test(data1, data2) → p_value**  
+  Führt einen Mann-Whitney-U-Test zur Überprüfung der Signifikanz zwischen zwei Datenmengen durch.
+
+#### Datenstrukturen
+- **RunData (JSON)** — enthält Timestamp, pinned_flag, runtime, seqcount_retry_count, mischfenster_dauer.
+- **MetricsSummary (JSON)** — umfasst retry_free_rate, mischfenster_stats und correlations.
+
+### Artefakt 2: Roh- und Summen-Daten
+- **Art:** csv_dataset  
+- **Ziel:** mixed  
+- **Sprachen:** CSV  
+- **Zweck:** Bereitstellung der Roh-Events und Run-Summaries für die ersten 10 N40-Runs.
+
+#### Tabellendefinition
+- **RunSummaryCSV** — enthält Felder: run_id, pinned_flag, runtime, seqcount_retry_count, mischfenster_dauer.
+
+### Artefakt 3: Methodische Dokumentation
+- **Art:** doc_only  
+- **Ziel:** mixed  
+- **Sprachen:** –  
+- **Zweck:** Dokumentation der Analysemethodik, Ergebnisse und geplanten nächsten Schritte.
+
+## Installation & Nutzung
+
+1. Python-Umgebung vorbereiten (Python ≥ 3.9 empfohlen)
+2. Abhängigkeiten installieren:  
+   `pip install -r requirements.txt`
+3. Analyse-Skripte ausführen (Beispiel):  
+   `python analyze_runs.py input/run_data.csv`
+
+Ergebnisse werden im Unterordner `output/` als CSV- und JSON-Dateien gespeichert.
+
+## Typische Use-Cases
+- Vergleich der Laufzeiten und Retries zwischen gepinnten und ungepinnten Runs.
+- Statistische Prüfung der Messergebnisse mittels Mann-Whitney-Test.
+- Ableiten von Performance-Trends in Abhängigkeit der Mischfensterdauer.
+- Verwendung der MetricsSummary-Datenstruktur in Folgestudien.
+
+## Struktur & Erweiterbarkeit
+- `scripts/` – Python-Analysetools und Statistikfunktionen.  
+- `data/` – Eingabedaten der ersten 10 Runs.  
+- `docs/` – Methodik- und Ergebnisbeschreibungen.  
+- `output/` – Resultate der Analyseläufe.  
+
+Die Struktur ist modular angelegt. Neue Analysemodule können in `scripts/` ergänzt, zusätzliche CSV-Daten in `data/` eingebunden werden. Erweiterungen sind durch API-kompatible Python-Funktionen möglich.
+
+## Lizenz
+Dieses Projekt steht unter der **MIT-Lizenz**.  
+Alle Code- und Dokumentationsbestandteile stammen aus automatisch generierten KI-Ausgaben. Verwendung und Weiterentwicklung erfolgen auf eigene Verantwortung.