🚢 AIS-ETT Predictor: KI-gestützte Vorhersage & Analyse von Schiffsankunftszeiten

Dieses Projekt nutzt maschinelles Lernen zur Vorhersage der geschätzten Reisezeit (ETT) von Schiffen auf Basis von AIS-Daten. Ein interaktives Webinterface visualisiert die Vorhersagen und ermöglicht die Analyse der Daten.

---

🧭 Inhaltsverzeichnis

• 📋 Voraussetzungen
• 🚀 Erste Schritte
• 💻 Benutzung
• 📖 Projektübersicht
• 📂 Projektstruktur
• 🛠️ Entwicklungsstand
• 📄 Code Dokumentation

---

📋 Voraussetzungen

• Docker & Docker Compose: Für die Containerisierung der Anwendung.
• Git: Zum Klonen des Repositories.
• Webbrowser: Ein moderner Browser (z.B. Chrome, Firefox).
• Python: Zur Installation von DVC.

🚀 Erste Schritte

Folgen Sie diesen Schritten, um die Anwendung zu starten.

1. Repository klonen

git clone https://collaborating.tuhh.de/e16/courses/software-development/ss25/group02.git
cd group02

2. Frontend-Abhängigkeiten installieren

Dieser Schritt ist nur einmal vor dem ersten Start erforderlich.

cd frontend
npm install
cd ..

3. Anwendung starten

Die Anwendung wird mit Docker containerisiert. Die Startskripte versuchen, existierende Modelle vom DVC-Server herunterzuladen, und bauen anschließend die notwendigen Container.

Hinweis: Der erste Docker-Build kann 2–10 Minuten dauern. Die Erstellung der Datenreports kann je nach Hardware 5–25 Minuten in Anspruch nehmen. Die meisten Modelle benötigen (falls nicht heruntergeladen) weniger als 5 Minuten. Das SVR-Training auf dem gesamten Datensatz kann jedoch ca. 60 Minuten pro Route dauern. In diesem Fall sollte SVR_TRAIN_SIZE in compose.yaml auf < 50000 gesetzt werden.

Unter Linux / macOS:

./start.sh

Unter Windows:

Stellen Sie sicher, dass Docker Desktop im Hintergrund läuft. Führen Sie dann den Befehl in der PowerShell aus:

./start.ps1

Nach dem Start ist die Webanwendung unter http://localhost:8080 verfügbar.

💻 Benutzung

Datenreports

Eine Übersicht der Original-, bereinigten und Vergleichsdaten finden Sie über die Menüleiste der Webanwendung oder direkt im Ordner storage/reports/.

Navigation

Über die Kacheln auf der Startseite können Sie zu den verschiedenen Datenreports navigieren:

• Original-Daten: Zeigt relevante Informationen zu den ursprünglichen AIS-Datensätzen.
• Bereinigte Daten: Zeigt relevante Informationen zu den bereinigten Datensätzen.
• Vergleichsansicht: Stellt die Original- und bereinigten Daten gegenüber.

Team-Dokumentation

Die Team-Dokumentation und weitere Berichte befinden sich im Ordner documentation. Da es sich um Confluence-Exporte handelt, können Formatierungsfehler auftreten.

Vorhersage

Um eine Vorhersage zu treffen, laden Sie eine CSV-Datei mit einem AIS-Datensatz über die Dropzone auf der Startseite hoch. Nach dem Upload stehen die Vorhersage sowie Visualisierungen von Statistiken und Karten zur Verfügung.

📖 Projektübersicht

Häfen weltweit benötigen für die Optimierung ihrer Abläufe möglichst genaue Ankunftszeiten. Die Ermittlung dieser Zeiten ist mit herkömmlichen Methoden schwierig, da unvorhersehbare Ereignisse die Reisen beeinflussen können. Daher wird ein Werkzeug benötigt, das auf Basis historischer AIS-Daten zuverlässig eine ETT vorhersagen kann.

Unser Lösungsansatz:

1. Datenbereinigung (backend/utils/dataclean.py): Korrektur von fehlenden/invaliden Werten in den AIS-Datensätzen (Typkonvertierung, Duplikate, Ausreißer via IsolationForests).
2. Feature Engineering (backend/utils/features.py): Hinzufügen zusätzlicher Merkmale zur Anreicherung der Daten.
3. Machine Learning Training (backend/utils/models.py): Implementierung von fünf verschiedenen ML-Algorithmen (u.a. Random Forest, Gradient Boosting, SVR), um deren jeweilige Stärken zu nutzen.
4. Modell-Evaluation (backend/utils/evaluate.py): Bewertung der Modelle mithilfe von Metriken wie MAE und R², um die Genauigkeit zu ermitteln.
5. Ensemble-Vorhersage: Gewichtung der Modelle anhand ihrer Genauigkeit, um eine robuste ETT-Schätzung zu erstellen.
6. Nutzeroberfläche: Ein Webinterface ermöglicht den Upload von AIS-Daten (CSV), die Anzeige der Vorhersagen und eine interaktive Karte zur Visualisierung der Schiffsreise.

📂 Projektstruktur

.
├── .dvc/             # DVC-Konfigurationen (Data Version Control)
├── .vscode/          # VSCode-Konfiguration (Debugger)
├── backend/          # FastAPI-Backend für ML-Vorhersagen
│   └── Dockerfile    # Dockerfile für das Backend
├── frontend/         # React-Frontend-Anwendung
│   └── Dockerfile    # Dockerfile für das Frontend
├── storage/          # DVC-getrackte Daten und Modell-Artefakte
├── documentation/    # Projektdokumentation (aus Confluence)
├── compose.yaml      # Docker-Compose-Konfiguration
├── start.sh          # Startskript für Linux/macOS
└── start.ps1         # Startskript für Windows

🛠️ Entwicklungsstand

Aktueller Stand:

✅ Datenpipeline zur Einlesung und Verarbeitung von AIS-Rohdaten.
✅ Algorithmen zur Datenbereinigung und Feature-Erstellung.
✅ Web-Interface (via Nginx) zur Anzeige der Datenreports.
✅ Docker-Container für das Deployment der Anwendung.
✅ Machine-Learning-Modelle für Training und Vorhersage (inkl. Ensembling).
✅ Caching zur Optimierung von rechenintensiven Schritten.
✅ API zur Erstellung von Vorhersagen.
✅ Web-Interface zur Visualisierung der Vorhersagen.

Geplante Funktionen/Verbesserungen:

• Code-Refactoring (globale Variablen vereinheitlichen, Logging standardisieren, Routen modularisieren).
• Test-Suite aktualisieren und erweitern.
• Erweiterte Analyseoptionen im Web-Interface (z.B. Visualisierung der Modellgenauigkeit).
• Anzeige historischer Durchschnitts-ETTs für Schiffstypen und Routen.
• Funktionale CI-Tests konfigurieren (GitLab CI/CD).
• Secret-Management für API- & DVC-SSH-Schlüssel implementieren.

---

📄 Code Dokumentation

Projektstruktur & Workflow

Das Projekt besteht aus zwei Hauptkomponenten:

• backend/: Ein Python-Programm, das eine FastAPI-Schnittstelle für Vorhersagen bereitstellt.
• frontend/: Eine React-Anwendung, die es ermöglicht, CSV-Dateien an das Backend zu senden und die Ergebnisse darzustellen.

Beide Komponenten sind für OS-unabhängigkeit containerisiert. Zeitaufwändige Aufgaben wie das Modelltraining werden durch Caching (.pkl-Dateien) beschleunigt. Diese Artefakte werden mit DVC versioniert und im Ordner storage/artefacts/ gespeichert.

Tools

• Git: Versionskontrolle und Feature-Branching.
• Jira: Sprint-, Story- und Zeit Management.
• Docker: Containerisierung für Entwicklung und Deployment.
• DVC: Verwaltung von Daten und Modellen.
• VSCode: IDE mit integriertem Debugger.
• GitLab CI/CD: Für automatisierte Tests (Konfiguration in Arbeit).

🏗️ Backend-Architektur

Machine Learning Pipeline

Das System nutzt eine ML-Pipeline mit Ensemble-Methoden.

1. Datenverarbeitung & Feature Engineering

CSV-Daten → Datenbereinigung → Feature-Extraktion → ML-Features

• Datenbereinigung (utils/dataclean.py): Behandelt fehlende Werte und konvertiert Datentypen.
• Feature Engineering (utils/features.py): Erstellt geografische, zeitbasierte und schiffsspezifische Merkmale, inklusive des Reisefortschritts (journey_progress).

2. Multi-Model Ensemble

Das System trainiert parallel fünf verschiedene ML-Algorithmen:

• XGBoost Regressor
• Random Forest Regressor
• K-Nearest Neighbors (KNN)
• Support Vector Regression (SVR)
• Linear Regression (Baseline)

Die Ensemble-Gewichte werden durch eine Grid Search automatisch optimiert, um den Summierten Mean Absolute Error (MAE) auf den Testdaten zu minimieren.

Hierbei gibt es Gewichtungsgrenzen. (E.g 0-40% pro Modell)

# Beispiel automatisch gefundener Gewichte:
# XGBoost: 35% (beste Einzelperformance)
# Random Forest: 25% (robuste Vorhersagen)
# KNN: 20% (lokale Muster)
# SVR: 15% (non-lineare Beziehungen)
# Linear Regression: 5% (Baseline-Korrektur)

3. Training Pipeline utils/train.py

Rohdaten → Feature Engineering → Modelltraining → Ensemble → Evaluation → Speicherung

Das Training wird beim Serverstart automatisch ausgeführt. Die Modelle werden als .pkl-Dateien im Ordner ./storage/artefacts/ für jede Route separat gespeichert.

4. Vorhersage-Engine

Die Vorhersage erfolgt in zwei Stufen:

1. Gesamtfahrzeit: Das ML-Ensemble schätzt die komplette Reisezeit.
2. Restfahrzeit: Restzeit = Gesamtzeit × (1 - journey_progress)

# Beispiel-Vorhersage:
journey_progress = 0.3  # 30% der Route absolviert
total_time = 180 min    # Geschätzte Gesamtfahrzeit
remaining_time = 180 × (1 - 0.3) = 126 min  # Verbleibende Zeit

5. API-Endpunkte

Endpoint	Methode	Beschreibung
/api/predict	POST	Nimmt CSV-Daten entgegen und liefert eine ETT-Vorhersage.
/api/retrain	POST	Löst manuell ein erneutes Training der Modelle aus.
/api/health	GET	Gibt den Systemstatus der API zurück.

6. Modell-Persistenz

Beim Serverstart werden vorhandene Modelle aus storage/artefacts/ geladen. Falls keine Modelle existieren, wird das Training automatisch gestartet.

🌐 Frontend-Architektur

Das Projekt nutzt Vite als Development-Server für eine React-Anwendung (mit TypeScript), die später mit NGINX gehosted wird.

Styling

Das Styling basiert auf einer Kombination aus TailwindCSS und der Komponentenbibliothek Shadcn/ui.

CSV Upload

Die Dropzone wird mit react-dropzone realisiert. Die hochgeladene Datei wird mittels papaparse verarbeitet und als FormData-Objekt über einen PredictionContext an die Backend-API (/api/predict) gesendet.

API-Anbindung

Im Entwicklungsmodus leitet ein in vite.config.ts konfigurierter Proxy die API-Anfragen an das Backend weiter (http://localhost:8000). Im Produktivbetrieb wird die Anfrage durch NGINX an den Backend-Container (http://backend:8000) geleitet.

Interaktive Karte

Die Karte wird mit Leaflet und React Leaflet umgesetzt. Die Kartengrundlage (Tiles) wird von Stadia Maps bereitgestellt. Zusätzlich wird ein Overlay mit Seekarten von OpenSeaMap eingebunden. Schiffsrouten werden als GeoJSON-Dateien visualisiert.

Sicherheitshinweis: Der für Stadia Maps benötigte API-Key ist derzeit direkt im Repository gespeichert. Dies stellt ein Sicherheitsrisiko dar und sollte in einer Produktivumgebung durch Umgebungsvariablen ersetzt werden.