02 · Entwicklungsumgebung und Werkzeuge

Klinischer Aufhänger

Dein Kollege schickt dir eine Excel-Auswertung. Du öffnest sie, und die Formeln schlagen fehl, weil er eine andere Excel-Version nutzt. Oder du rechnest sechs Monate später dasselbe erneut und erhältst andere Zahlen, weil zwischenzeitlich ein Update eingespielt wurde.

Reproduzierbarkeit bedeutet: gleicher Code + gleiche Umgebung = gleiches Ergebnis, heute, morgen und in fünf Jahren.

1 Das Terminal – wohin die Befehle gehen

Viele Anleitungen in diesem Kurs zeigen Terminal-Befehle. Das Terminal ist ein Textfenster, in das du Befehle tippst und mit Enter bestätigst – kein Klickmenü, aber genau deshalb reproduzierbar und protokollierbar.

• macOS: Programm „Terminal" öffnen (Spotlight mit Cmd+Leertaste, dann „Terminal" tippen).

• Windows: „PowerShell" öffnen (Startmenü, „PowerShell" tippen).

Erste sichere Terminal-Minute

Diese Befehle verändern nichts. Sie zeigen nur, wo du bist und welche Dateien im Ordner liegen:

pwd      # print working directory: aktueller Ordner
ls       # list: Dateien und Unterordner anzeigen

Wenn du dich vertippst: kein Drama. Mit der Pfeiltaste nach oben holst du den letzten Befehl zurück, mit Ctrl+C brichst du einen laufenden Befehl ab.

2 Was ist ein Paket – und warum installieren?

Python und R können von sich aus nur wenig: rechnen, Text verarbeiten, Dateien lesen. Die eigentlichen Analysewerkzeuge — Tabellen bearbeiten, Modelle rechnen, Grafiken zeichnen — liefern Pakete (auch Bibliotheken genannt): fertige, von anderen geschriebene und geprüfte Funktionssammlungen. pandas bearbeitet Tabellen in Python, tidyverse tut dasselbe in R, statsmodels rechnet Regressionen.

Diese Pakete sind nicht vorinstalliert. Du lädst sie einmalig aus einem zentralen Archiv herunter — für Python ist das PyPI, für R das CRAN. Genau das tun die Befehle, die gleich kommen:

• Python: pip install pandas (bzw. uv pip install …) holt ein Paket von PyPI.
• R: install.packages("tidyverse") holt es vom CRAN.

Danach machst du das Paket in jedem Skript mit import pandas (Python) bzw. library(tidyverse) (R) verfügbar. Installieren = einmal herunterladen; importieren = in dieser Sitzung benutzen.

Nur im Browser lernen? Dann installierst du genau die Pakete, die ein Codeblock oben nennt — mehr nicht. Die Kurs-Datensätze musst du nicht herunterladen oder erzeugen: die Codeblöcke lesen sie direkt über eine Web-Adresse. Der Rest dieses Moduls (virtuelle Umgebung, Git, Projektordner) lohnt sich, sobald du reproduzierbar arbeiten willst — nötig zum Mitrechnen ist er nicht.

3 Python via uv installieren

uv ist ein moderner Python-Paketmanager, der Installationen isoliert und reproduzierbar macht. Er installiert auch Python selbst.

macOS / Linux: curl lädt eine Datei aus dem Internet — hier das Installationsskript von uv —, und | sh (pipe an die Shell) führt es direkt aus. Zeile unverändert kopieren:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Nach der Installation Terminal neu starten, dann prüfen:

uv --version

Projektumgebung einrichten (einmalig, aus dem Projektordner):

uv venv .venv
source .venv/bin/activate        # macOS/Linux
# Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

requirements.txt enthält nur den Kernpfad (Teil 1–4) und bleibt dadurch schlank. Die fortgeschrittenen ML-/KI-Module (Teil 5) brauchen ein paar schwerere Zusatzpakete, die in einer eigenen Datei stehen — installiere sie erst, wenn du dort ankommst:

uv pip install -r requirements-ml.txt   # xgboost, lightgbm, umap-learn, shap, scikit-survival

Stolperstein (macOS): xgboost und lightgbm benötigen die OpenMP-Laufzeit. Falls die Installation oder der Import scheitert, einmalig brew install libomp ausführen. brew ist Homebrew, ein Paket-Installer für macOS-Systemsoftware; erscheint command not found, richte ihn einmalig über brew.sh ein und wiederhole den Befehl. Linux-/Windows-Wheels bringen die Laufzeit meist mit.

Der Guide zu virtuellen Umgebungen (Virtual Environments)

1. Das Problem: Warum brauchen wir sie überhaupt?

Wenn du Python auf deinem Computer installierst, hast du standardmäßig ein einziges, globales Python-System. Installierst du nun Bibliotheken (z. B. Pandas) direkt global, laden sie alle im selben Ordner. Das führt unweigerlich in die „Dependency Hell“ (Abhängigkeits-Hölle):

• Modell A benötigt Pandas Version 1.5 (weil älterer Code sonst bricht).
• Modell B benötigt Pandas Version 2.2 (wegen neuerer ML-Features).
• Wenn du Pandas global aktualisierst, funktioniert Projekt A nicht mehr. Wenn du es downgradest, bricht Projekt B.

2. Die Lösung: Die virtuelle Umgebung (venv)

Eine virtuelle Umgebung ist wie ein isolierter Reinraum oder ein eigener Werkzeugkasten für jedes Projekt.

• Sie ist technisch gesehen einfach ein ganz normaler Ordner (meist .venv genannt) in deinem Projektverzeichnis.
• In diesem Ordner liegt eine eigenständige Kopie der Python-Version und aller installierten Bibliotheken.
• Was du innerhalb dieser Umgebung installierst, bleibt dort und berührt weder dein globales System noch andere Projekte.

3. Das Handwerk: Wie nutzt man sie?

• Erstellen: Der Befehl uv venv .venv legt den Ordner .venv in deinem aktuellen Verzeichnis an.
• Aktivieren (Activate): Das ist der wichtigste Schritt. Er teilt deiner Kommandozeile (Terminal) mit: „Nutze ab jetzt das Python und die Bibliotheken aus dem .venv-Ordner, nicht das globale System!“
• macOS/Linux: source .venv/bin/activate
• Windows (PowerShell): .venv\Scripts\activate
• Woran erkenne ich, dass es aktiv ist? Vor deiner Eingabezeile im Terminal steht nun in Klammern (.venv).
• Installieren: Sobald die Umgebung aktiv ist, installiert jeder Befehl wie uv pip install die Pakete in genau diesen Ordner.
• Deaktivieren (Deactivate): Mit dem einfachen Befehl deactivate verlässt du den Reinraum wieder.

4 R + RStudio installieren

R ist die Leitsprache der klinischen Statistik-Community, RStudio die empfohlene Entwicklungsumgebung.

1. R von cran.r-project.org herunterladen und installieren.
2. RStudio Desktop (kostenlos) von posit.co/download/rstudio-desktop installieren.

Benötigte Basispakete in R installieren (einmalig, in der R-Konsole). Kopiere diesen Block — er funktioniert immer, auch ohne das Repository. Der Kernpfad (Module 01–10, 12–25, 32, 34) braucht:

install.packages(c(
  "tidyverse", "gtsummary", "broom", "survival",
  "DBI", "duckdb", "readxl", "writexl", "jsonlite", "httr2",
  "tidymodels", "pROC", "lme4", "sandwich", "lmtest", "mice"
))

Hast du das Repository geklont, installierst du stattdessen mit einem Befehl dieselbe Liste — das Skript prüft, was schon da ist, und lädt nur Fehlendes nach:

source("tools/install_r_packages.R")

Für die Vertiefungen (Module 26–31, 33) kommen später hinzu:

install.packages(c(
  "xgboost", "vip", "pdp", "DALEX", "DALEXtra",
  "randomForestSRC", "cmprsk", "timeROC", "umap", "factoextra", "cluster",
  "tidytext", "nnet", "recipes"
))

Die vollständige Liste pro Modul steht in DEPENDENCIES-R.md.

R-Pakete isolieren mit renv

1. Warum auch in R isolierte Umgebungen?

Genauso wie in Python führt das globale Installieren von Paketen in R (install.packages()) irgendwann zu Konflikten. Wenn du eine Analyse aktualisierst, die vor einem Jahr mit einer älteren Version von gtsummary geschrieben wurde, kann es sein, dass dein Code heute Fehler wirft.

2. Die Lösung in R: renv

Das Paket renv (R environment) ist das Gegenstück zu Pythons venv.

• Es erstellt eine projekteigene Bibliothek im Ordner renv/ im Projektverzeichnis.
• Die genauen Versionen werden in einer Datei namens renv.lock dokumentiert (das R-Gegenstück zu requirements.txt).

3. Das Handwerk: Wie nutzt man renv?

• Initialisieren: Installiere renv einmalig global und initialisiere dein Projekt in der R-Konsole:

  install.packages("renv")
  renv::init()
  

Dadurch wird die Projektbibliothek eingerichtet und das Projekt so konfiguriert, dass es beim Öffnen in RStudio automatisch diese lokale Bibliothek nutzt.

• Pakete installieren: Wenn du nun Pakete installierst, landen sie automatisch in deinem Projekt:

  install.packages("tidyverse")
  

• Zustand einfrieren (Snapshot): Wenn deine Analyse läuft, speicherst du den aktuellen Zustand der Paketversionen ab:

  renv::snapshot()
  

Dadurch wird die Datei renv.lock aktualisiert.

• Wiederherstellen (Restore): Ein Kollege oder du selbst auf einem anderen Rechner können die exakten Paketversionen mit einem Befehl wiederherstellen:

  renv::restore()
  

5 VS Code als Editor

1. code.visualstudio.com, herunterladen und installieren.
2. Erweiterungen installieren: Python (Microsoft) und R (REditorSupport).
3. Projektordner in VS Code öffnen: Datei → Ordner öffnen.
4. Python-Interpreter auswählen: Strg+Shift+P → „Python: Select Interpreter" → .venv wählen.

6 Git und GitHub, Versionsgeschichte für Code

Git speichert jede Version deines Codes, wie die „Änderungsverfolgung" in Word, nur für Skripte. GitHub ist der cloudbasierte Speicherort.

Git installieren: git-scm.com

Erstes Repository einrichten (im Projektordner):

git init
git add .
git commit -m "Initial commit: project structure"

Für den Kurs genügt Git lokal. GitHub ist empfohlen, aber optional.

.venv/
renv/library/
renv/local/
renv/staging/
__pycache__/
*.pyc
.DS_Store

7 Projektstruktur

Data Science Coach/
├── data/              ← Rohdaten (nie manuell bearbeiten)
├── lib/               ← gemeinsame Hilfsfunktionen
├── module/            ← eine Lektion je Unterordner
├── .venv/             ← virtuelle Python-Umgebung (nicht versionieren!)
└── renv/              ← lokale R-Paketbibliothek (nicht versionieren!)

import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[3]
sys.path.insert(0, str(ROOT))

import pandas as pd
import numpy as np
from lib.helpers import SEED, load_cohort

print(f"Python:  {sys.version.split()[0]}")
print(f"pandas:  {pd.__version__}")
print(f"numpy:   {np.__version__}")
print(f"Seed:    {SEED}")

cohort = load_cohort()
print(f"Dataset: {cohort.shape[0]} patients")
print("Environment OK.")

source(file.path("lib", "helpers.R"))
library(tidyverse)

cat("R:      ", R.version.string, "\n")
cat("tidyverse:", as.character(packageVersion("tidyverse")), "\n")
cat("Seed:   ", SEED, "\n")

cohort <- load_cohort()
cat("Dataset:", nrow(cohort), "patients\n")
cat("Environment OK.\n")

10 Beispieldaten des Kurses erzeugen (optional)

Brauchst du das? In den allermeisten Fällen nein. Die Datensätze liegen fertig im Kurs, und jeder Codeblock liest sie über eine Web-Adresse — lokal musst du nichts erzeugen, auch nicht als reine:r R-Nutzer:in. Dieser Abschnitt ist nur für den Fall, dass du das Repository geklont hast und die Daten aus dem Skript heraus exakt reproduzieren willst.

Der Kurs arbeitet mit einer synthetischen (frei erfundenen, datenschutz­freien) Intensivkohorte. Wer das Repo geklont hat, kann sie mit festem Seed neu erzeugen – so hat jede:r byte-genau dieselben Zahlen. Im Terminal, aus dem Projektordner und mit aktivierter Umgebung (Abschnitte 1 und 3):

python data/generate_data.py   # erzeugt Kohorte + Begleitdateien in data/
python data/figures.py         # erzeugt die Abbildungen der Lektionen

generate_data.py erzeugt zehn Dateien: die vier Kern-Datensätze (kohorte.csv, vitalwerte.csv, labor.csv, notizen.csv), vier Begleitdateien für Modul 04 im deutschen CSV-, Excel- und JSON-Format (kohorte_de.csv, einschluss.xlsx, beispiel.json, fhir_bundle.json) sowie zwei Spezialdateien: konkurrenz_risiken.csv (Modul 20) und bga_ph_wahrheit.csv (Modul 14). Erwartete Ausgabe (Seed 42):

Generated (seed 42):
  kohorte.csv       500 rows, 16 cols
  vitalwerte.csv   1873 rows, 6 cols
  labor.csv         500 rows, 7 cols
  notizen.csv       500 rows, 3 cols
  kohorte_de.csv
  einschluss.xlsx
  beispiel.json
  fhir_bundle.json
  konkurrenz_risiken.csv   500 rows, 4 cols
  bga_ph_wahrheit.csv   500 rows, 2 cols

Fallstricke und Merksätze

• Immer aus dem Projektordner starten. python module/02-werkzeuge/code/python.py funktioniert; cd module/02-werkzeuge && python code/python.py kann den lib/-Pfad brechen, wenn die relativen Pfade nicht stimmen.

• Virtuelle Umgebung vergessen ist der häufigste Einstiegsfehler. Vor jeder Sitzung aktivieren: source .venv/bin/activate (macOS/Linux) oder .venv\Scripts\activate (Windows). VS Code aktiviert sie oft automatisch.

• Paketversionen pinnen für maximale Reproduzierbarkeit: uv pip freeze > requirements.txt sichert den exakten Stand.

• install.packages() in R muss nur einmalig ausgeführt werden; danach genügt library(tidyverse).

Selbstcheck