Input-Daten Checkliste¶

Diese Seite listet alle Dateien und Datenquellen, die WorldQual Lite zum Ausführen benötigt. Sie ist als Checkliste gedacht: Vor dem ersten Modelllauf prüfen, ob alle Daten vorhanden sind.

Überblick¶

Das Modell benötigt drei Kategorien von Input-Daten:

Kategorie	Quelle	Anzahl Dateien	Beschreibung
Statische UNF-Dateien	`OTHER_UNF_FILES/`	10	Zelleigenschaften (Fläche, Erosion, Routing, etc.) — ändern sich nicht über die Zeit
Zeitabhängige UNF-Dateien	Verschiedene Ordner	6 pro Jahr	Monatl./jährliche Rasterdaten (Abfluss, Vieh, Dünger, etc.)
Tabellarische Daten	MySQL-DB oder CSV	3–4 Tabellen/Dateien	Länder- und Zellparameter (Bevölkerung, Kläranlagen, Emissionsfaktoren)

Zusätzlich wird eine Einzugsgebiets-Zellenliste (CSV) benötigt, die definiert welche Rasterzellen zum Einzugsgebiet gehören.

1. Einzugsgebiets-Zellenliste (Pflicht)¶

Konfiguriert in: config.yaml → paths.basin_cells_csv

Format: CSV mit mindestens zwei Spalten:

Spalte	Typ	Beschreibung
`Cell_ID`	Integer	GCRC-Nummer der Rasterzelle
`Portion of Cell in Basin (%)`	Float	Prozentualer Flächenanteil der Zelle im Einzugsgebiet (100.823 = vollständig)

Erstellt durch: BasinDelineation.py (Routing-Methode oder Shapefile-Overlay)

Beispiel:

Cell_ID,Portion of Cell in Basin (%)
82128,100.823
82129,100.823
82130,45.5

2. Statische UNF-Dateien (einmalig, zeitunabhängig)¶

Konfiguriert in: config.yaml → paths.other_unf_files_folder

Diese Dateien beschreiben zeitlich konstante Eigenschaften der Rasterzellen. Sie werden einmal geladen und für alle Jahre wiederverwendet.

Dateiname	UNF-Typ	Datentyp	Größe (EU)	Inhalt	Verwendet in
`GR.UNF2`	Short (2 Byte)	Integer	180.721 Werte	Zeilen-Koordinate jeder Zelle im Raster	Alle Berechnungen (Adressierung)
`GC.UNF2`	Short (2 Byte)	Integer	180.721 Werte	Spalten-Koordinate jeder Zelle im Raster	`FileToArray()` (Visualisierung)
`GAREA.UNF0`	Float (4 Byte)	Float	641 Werte (1 pro Zeile)	Zellflächengröße [km²] pro Breitengrad	Flächengewichtung aller diffusen Quellen
`G_LAND_AREA.UNF1`	Byte (1 Byte)	Integer	180.721 Werte	Landflächenanteil [%] pro Zelle	Atm. Deposition, Chem. Verwitterung
`GBUILTUP.UNF0`	Float (4 Byte)	Float	180.721 Werte	Versiegelungsgrad [-] pro Zelle	Abzug versiegelter Fläche bei diffusen Quellen
`G_SOILEROS.UNF0`	Float (4 Byte)	Float	180.721 Werte	Bodenerosionsrate [kg/km²/a]	Fink-Erosionsmodell (`Cell_Yearly_ErodedPortion`)
`GFREQW.UNF1`	Byte (1 Byte)	Integer	180.721 Werte	Wasserflächenanteil [%] pro Zelle	Hydraulic Load (Retention)
`G_PATMDEPOS.UNF0`	Float (4 Byte)	Float	180.721 Werte	Atmosph. P-Depositionsrate [kg/km²/a]	`BackgroundAtm()`
`G_PWEATHERING.UNF0`	Float (4 Byte)	Float	180.721 Werte	Chemische P-Verwitterungsrate [kg/km²/a]	`BackgroundCW()`
`G_OUTFLC.UNF4`	Integer (4 Byte)	Integer	180.721 Werte	Routing: nächste Unterstrom-Zelle	`BasinDelineation.py` (nur bei Routing-Methode)

Größenangaben

Die Angabe "180.721 Werte" gilt für Europa (continent_index: 0). Für andere Kontinente unterscheiden sich die Zellenzahlen — siehe config.yaml → continents.cell_counts.

3. Zeitabhängige UNF-Dateien (pro Simulationsjahr)¶

Für jedes Jahr im Simulationszeitraum werden 6 UNF-Dateien benötigt. Der Pfad wird aus dem konfigurierten Ordner + Jahreszahl zusammengesetzt.

3a. Historischer Modus (`run.type: "Historical"`)¶

config.yaml-Pfad	Dateinamenmuster	UNF-Typ	Zeitauflösung	Inhalt
`paths.surface_runoff_folder`	`G_SURFACE_RUNOFF_{Jahr}.12.UNF0`	Float × 12 Layer	Monatlich	Oberflächenabfluss [mm/Monat]
`paths.surface_runoff_folder`	`G_SURFACE_RUNOFF_MEAN.UNF0`	Float × 1 Layer	Klimamittel	Mittlerer Jahresabfluss (für Erosionsmodell)
`paths.urban_runoff_folder`	`G_URBAN_RUNOFF_{Jahr}.12.UNF0`	Float × 12 Layer	Monatlich	Urbaner Abfluss [mm/Monat]
`paths.livestock_density_folder`	`G_LIVESTOCK_NR_{Jahr}.12.UNF0`	Float × 12 Layer	Monatlich	Viehdichte [Tiere/Zelle] × 12 Kategorien
`paths.correction_factor_folder`	`G_CORR_FACT_RTF_{Jahr}.12.UNF0`	Float × 12 Layer	Monatlich	Return-Flow-Korrekturfaktoren
`paths.p_rate_ton_folder`	`P_RATE_TON_KM2_{Jahr}.UNF0`	Float × 1 Layer	Jährlich	P-Düngungsrate [t/km²]
`paths.cropland_corrected_folder`	`CROPLAND_CORR_KM2_{Jahr}.UNF0`	Float × 1 Layer	Jährlich	Ackerfläche [km²] pro Zelle

Hinweis zum mittleren Abfluss

G_SURFACE_RUNOFF_MEAN.UNF0 ist eine einzige Datei (kein Jahressuffix) und wird für das Erosionsmodell als Klimamittel benötigt. Sie liegt im selben Ordner wie die jährlichen Abflussdateien.

3b. Zukunftsmodus (`run.type: "Future"`)¶

Im Zukunftsmodus werden die UNF-Dateien aus einer anderen Ordnerstruktur geladen, die nach Szenario, RCP und GCM organisiert ist. Der Basispfad ist config.yaml → paths.future_unf_files.

Datei	Pfadmuster unterhalb `future_unf_files/`
Oberflächenabfluss	`Hydrology/{kontinent}/{rcp}_{GCM}/G_SURFACE_RUNOFF_{Jahr}.12.UNF0`
Urbaner Abfluss	`Hydrology/{kontinent}/{rcp}_{GCM}/G_URBAN_RUNOFF_{Jahr}.12.UNF0`
Viehdichte	`LIVESTOCK_NR/{SSP}/{kontinent}/G_LIVESTOCK_NR_{Jahr}.12.UNF0`
Korrekturfaktor	`correction_factors/{rcp}_{SSP}/{kontinent}/{GCM}/G_CORR_FACT_RTF_{Jahr}.12.UNF0`
P-Düngungsrate	`P_RATE_TON_KM2/{SSP}/{kontinent}/P_RATE_TON_KM2_{SSP}_{Jahr}_{kontinent}.UNF0`
Ackerfläche	`CROPLAND_AREA_KM2/{SSP}/{kontinent}/{SSP}_{Jahr}_5arcmin_cropland_{kontinent}.UNF0`

Dabei sind {kontinent}, {rcp}, {GCM}, {SSP} und {Jahr} Platzhalter die aus config.yaml abgeleitet werden.

4. Tabellarische Daten (Länder- und Zellparameter)¶

Diese Daten können entweder aus einer MySQL-Datenbank (data_source: "DB") oder aus CSV-Dateien (data_source: "Excel") geladen werden.

4a. Datenbankmodus (`data_source: "DB"`)¶

Es werden 7 verschiedene MySQL-Queries ausgeführt. Die Datenbank muss erreichbar sein und die Zugangsdaten in .env hinterlegt.

Query-Funktion	Datenbank	Tabelle	Abgefragte Felder	Wann
`CountryPopulation()`	`globewq_wq_load`	`country_input`	pop_tot, pop_urb, pop_rur	Pro Jahr
`CountryConnectionToTreatment()`	`globewq_wq_load`	`country_input`	con_prim, con_sec, con_tert, con_untr, con_quat, stp_failure, UrbSewerConn, RurSewerConn, SPO_treat, to_treat_and_unknown, to_hanging_t, to_open_def	Pro Jahr
`CountryReturnFlows()`	`globewq_wq_load`	`country_input`	rtf_man (+ Fraktionen)	Pro Jahr
`CountryEmmisionFactor()`	`globewq_wq_load`	`country_parameter_input`	ef	Pro Jahr
`CountryConcInReturnFlows()`	`globewq_wq_load`	`country_parameter_input`	conc_man_nd, conc_urb	Pro Jahr
`RemovalRate()`	`globewq_wq_load`	`parameter_input`	rem_prim, rem_sec, rem_tert, rem_untr, rem_quat, treat_failure	Pro Jahr
`LivestockExcretionRate()`	`globewq_wq_load`	`ls_exr_input`	ls_exr_rate (× 12 Viehkategorien)	Pro Jahr
`IDFaoReg_from_Country_Id()`	`wq_general`	`_country`	IDFAOReg	Einmalig
`Cell_ID_To_GCRC()`	`watergap_unf`	`gcrc`	cell_land_water	Pro Zelle

4b. CSV-Modus (`data_source: "Excel"`)¶

Im CSV-Modus werden stattdessen 3 CSV-Dateien und 1 Zell-Input-CSV geladen:

Konfiguriert in: config.yaml → paths.data_path

Datei	Pfad relativ zu `data_path`	Inhalt
Country Input	`country_input/{Scenario}_country_input.csv`	Bevölkerung, Kläranlagen-Anschlussraten, Return Flows
Country Parameter Input	`country_parameter_input/{Scenario}_country_parameter_input.csv`	Emissionsfaktoren, Konzentrationen
Parameter Input	`parameter_input/{Scenario}_parameter_input.csv`	Entfernungsraten (Reinigungsleistung)

Zell-Input-CSV (immer benötigt, unabhängig von DB/Excel):

Modus	Pfad	Spalten
Historical	`Europe_Cell_Input_Files/europe_cell_input_{Jahr}.csv`	cell, pop_urb, pop_rur, pop_tot, rtf_man, rtf_dom, rtf_irr, gdp, salinity, humidity, lu
Future	`Europe_Cell_Input_Files/{SSP}/europe_cell_input_{Jahr}.csv`	Gleiche Spalten

CSV-Modus für Studierende

Der CSV-Modus (data_source: "Excel") ist ideal für die Lehre, da keine Datenbankverbindung nötig ist. Die CSVs können vorab exportiert und dem Repository beigelegt werden.

Sonderfälle im CSV-Modus

Die Funktionen Cell_ID_To_GCRC(), IDFaoReg_from_Country_Id() und LivestockExcretionRate() benötigen immer eine Datenbankverbindung, auch im CSV-Modus. Dies ist eine bekannte Einschränkung des aktuellen Codes.

5. Zusammenfassung: Minimaler Datensatz für einen Lauf¶

Der Ordner data/sample_run/ enthält einen funktionsfähigen Minimaldatensatz für das Möhne-Einzugsgebiet (Deutschland, Jahr 2000). Er umfasst ca. 90 MB und kann direkt mit python3 run.py ausgeführt werden.

Dateistruktur¶

data/sample_run/
├── basin/
│   └── basin_cells.csv                                # 23 Zellen des Möhne-Einzugsgebiets
├── cell_input/
│   └── europe_cell_input_2000.csv                     # Zell-Input (Bevölkerung, Return Flows)
├── country_input/
│   └── SSP2_country_input.csv                         # Länderdaten (Eurostat/Weltbank)
├── country_parameter_input/
│   └── SSP2_country_parameter_input.csv               # Emissionsfaktor, Konzentrationen
├── parameter_input/
│   └── SSP2_parameter_input.csv                       # Entfernungsraten (Kläranlagen)
├── shapefiles/
│   └── mother_eu.*                                    # WaterGAP-Referenzgitter Europa
├── unf/
│   ├── G_SURFACE_RUNOFF/
│   │   ├── G_SURFACE_RUNOFF_2000.12.UNF0              # Monatl. Abfluss
│   │   └── G_SURFACE_RUNOFF_MEAN.UNF0                 # Klimamittel Abfluss
│   ├── G_URBAN_RUNOFF/
│   │   └── G_URBAN_RUNOFF_2000.12.UNF0                # Monatl. urbaner Abfluss
│   ├── G_LIVESTOCK_NR/
│   │   └── G_LIVESTOCK_NR_2000.12.UNF0                # Monatl. Viehdichte
│   ├── G_CORR_FACT_RTF/
│   │   └── G_CORR_FACT_RTF_2000.12.UNF0               # Monatl. Korrekturfaktoren
│   ├── P_RATE_TON_KM2/
│   │   └── P_RATE_TON_KM2_2000.UNF0                   # Jährl. P-Düngungsrate
│   ├── CROPLAND_CORR_KM2/
│   │   └── CROPLAND_CORR_KM2_2000.UNF0                # Jährl. Ackerfläche
│   └── OTHER_UNF_FILES/
│       ├── GR.UNF2, GC.UNF2                           # Rasterkoordinaten
│       ├── GAREA.UNF0                                  # Zellflächengröße
│       ├── GCRC.UNF4                                   # Zell-ID-Zuordnung
│       ├── G_OUTFLC.UNF4                               # Routing (Unterstrom-Zellen)
│       ├── G_LAND_AREA.UNF1                            # Landflächenanteil
│       ├── GBUILTUP.UNF0                               # Versiegelungsgrad
│       ├── G_SOILEROS.UNF0                             # Bodenerosionsrate
│       ├── GFREQW.UNF1                                 # Wasserflächenanteil
│       ├── GLCC2000.UNF2                               # Landbedeckung (GLC2000)
│       ├── G_PATMDEPOS.UNF0                            # Atmosph. P-Deposition
│       └── G_PWEATHERING.UNF0                          # Chem. P-Verwitterung
└── PLATZHALTER_FUTURE_UNF.txt                          # Hinweis auf Future-Daten

Platzhalter-Dateien¶

In jedem Unterordner liegen PLATZHALTER_*.txt-Dateien, die beschreiben welche zusätzlichen Daten für erweiterte Läufe benötigt werden:

Datei	Beschreibung
`PLATZHALTER_ANDERE_JAHRE.txt`	Hinweis auf UNF-Dateien für weitere Jahre (1980–2016)
`PLATZHALTER_ANDERE_KONTINENTE.txt`	Hinweis auf Shapefiles für weitere Kontinente
`PLATZHALTER_FUTURE_UNF.txt`	Hinweis auf Future/SSP-UNF-Dateien für Szenarienläufe

Datenherkunft der Country-CSVs¶

Die tabellarischen Länderdaten im sample_run/ wurden mit scripts/fetch_real_data.py automatisch aus öffentlichen Quellen heruntergeladen:

Datensatz	Quelle	API
Bevölkerung (pop_tot)	Weltbank	`SP.POP.TOTL`
Urbanisierungsgrad	Weltbank	`SP.URB.TOTL.IN.ZS`
Kläranlagen-Anschlussraten	Eurostat	`env_ww_con`
Abwassermengen (rtf_man)	Eurostat	`env_ww_genv`
Emissionsfaktoren, Entfernungsraten	Literaturwerte	Bouwman et al. / Seitzinger et al.

Fehlende Jahre werden per linearer Interpolation aufgefüllt.

Datenbankzugriff (auch im CSV-Modus)¶

Auch bei data_source: "Excel" werden folgende DB-Abfragen ausgeführt:

Funktion	Datenbank	Wann	Workaround ohne DB
`Cell_ID_To_GCRC()`	`watergap_unf`	Pro Zelle, pro Monat	Erfordert Code-Anpassung
`IDFaoReg_from_Country_Id()`	`wq_general`	Einmalig pro Lauf	FAO-Region-ID kann hardcodiert werden
`LivestockExcretionRate()`	`globewq_wq_load`	Einmalig pro Lauf	12 Exkretionsraten können hardcodiert werden

6. UNF-Dateiformat Referenz¶

Das WaterGAP-UNF-Format ist ein einfaches Binärformat ohne Header. Die Daten werden als Big-Endian-Werte sequentiell gespeichert.

Endung	Bytes/Wert	Datentyp	Python `struct`-Format
`.UNF0`	4	Float (32-bit)	`>f`
`.UNF1`	1	Unsigned Byte	`int.from_bytes(..., "big")`
`.UNF2`	2	Short Integer (16-bit)	`int.from_bytes(..., "big")`
`.UNF4`	4	Integer (32-bit)	`int.from_bytes(..., "big")`

Layer-Konvention: Die Anzahl der Layer wird im Dateinamen codiert, z.B. .12.UNF0 = 12 Monatsschichten. Ohne Zahl = 1 Layer.

Speicherlayout: Bei Multi-Layer-Dateien (z.B. 12 Monate) sind die Daten zellenweise verschachtelt: Zelle 1 Monat 1, Zelle 1 Monat 2, ..., Zelle 1 Monat 12, Zelle 2 Monat 1, usw.

Zugriff auf einen Wert:

# Für Zelle mit GCRC-Index und Monat (1-basiert):
index = 12 * (Cell_GCRC - 1) + (month - 1)
wert = daten[index]

Ausnahme: GAREA.UNF0 hat nur nrow Werte (eine Fläche pro Breitengrad-Zeile, nicht pro Zelle). Der Zugriff erfolgt über GR_Data: area = Area_Data[GR_Data[Cell_GCRC - 1] - 1].