Global Compression and Reorganization of Lake Thermal Habitats

Global Compression and Reorganization of Lake Thermal Habitats 1. Overview This repository contains the data and Python code needed to reproduce the core results and main figures for the manuscript "Global compression and reorganization of lake thermal habitats". The original daily meteorological forcing data and high-resolution process-based model outputs for 1,427,688 lakes are too large to include in this archive. Instead, this repository provides processed lake-level and gridded datasets that are sufficient to reproduce the main quantitative results and figures. The included source data cover: Long-term lake water temperature trends. Thermal habitat shifts caused by long-term warming. Thermal habitat shifts caused by extreme heatwave scenarios. Geospatial and bathymetric data needed for aggregation, mapping, and exposure analyses. 2. Content This repository includes: Source code for reproducing Figures 2-5. Processed datasets used by the figure scripts. Example figure outputs generated from the included data. System requirements, installation instructions, demo instructions, expected outputs, and runtime guidance. 3. System Requirements Hardware A standard desktop or laptop computer can run the scripts, but the full data workflow is memory intensive. We recommend: RAM: at least 64 GB for the full datasets included here. Storage: at least 25 GB free disk space for the repository and generated outputs. GPU: not required. Non-standard hardware: not required. The lightweight Poyang Lake demo dataset requires substantially less memory than the full figure workflows. Software The scripts were developed and tested with Python 3.13.5 on Windows 11. Required Python packages are listed in requirements.txt. To install them with pip: pip install -r requirements.txt Tested environment: Component Version OS Windows 11 AMD64 Python 3.13.5 numpy 2.3.2 pandas 2.3.2 scipy 1.16.1 matplotlib 3.10.6 cartopy 0.24.1 h5py 3.15.1 geopandas 1.1.1 Installation Time On a normal desktop computer with an existing Python installation, package installation typically takes 10-30 minutes. The exact time depends mainly on geospatial dependencies such as Cartopy and GeoPandas. If using conda, installation of geospatial packages may be more reliable: conda create -n lake-habitat python=3.13 numpy pandas scipy matplotlib cartopy h5py geopandas conda activate lake-habitat 4. Directory Structure The repository is organized as a standard reproducible scientific-study archive: Project_Root/ |-- README.md |-- requirements.txt |-- scripts/ | |-- Figure_2.py | |-- Figure_3.py | |-- Figure_4.py | |-- Figure_5.py | |-- demo.py | |-- heatwave.py | |-- thermal_shift.py |-- data/ | |-- processed/ | | |-- lake_center.csv | | |-- lake_thermal_regions.nc | | |-- temp_trend_global_lakes.csv | | |-- global_mean_trend.csv | | |-- global_mean_temperature_list.csv | | |-- daily_nonoverlap_results.npz | | |-- background_results.npz | | |-- heatwave_nonoverlap_results.npz | |-- external/ | | |-- GLOBathy_hAV_relationships.nc | | |-- BasinATLAS_v10_shp/ | | | |-- BasinATLAS_v10_lev06.shp | | | |-- BasinATLAS_v10_lev06.shx | | | |-- BasinATLAS_v10_lev06.dbf | | | |-- BasinATLAS_v10_lev06.prj | | | |-- BasinATLAS_v10_lev06.sbn | | | |-- BasinATLAS_v10_lev06.sbx | |-- demo/ | | |-- data_poyang.npy |-- results/ | |-- figures/ | | |-- Figure_2.png | | |-- Figure_3.png | | |-- Figure_4.png | | |-- Figure_5.png | |-- demo/ | | |-- poyang_heatwave_events.csv | | |-- poyang_long_term_daily_shifts.csv | | |-- poyang_heatwave_day_shifts.csv | | |-- poyang_heatwave_event_shift_summary.csv | | |-- poyang_heatwave_2022_jun_sep.png | | |-- poyang_long_term_shifts_2023_vs_2000.png 5. Data Dictionary Geospatial Data data/processed/lake_center.csv: HydroLake ID, latitude (lat), and longitude (lon) for each simulated lake. Used to map lakes to a 0.5 degree by 0.5 degree global grid. data/processed/lake_thermal_regions.nc: Global lake thermal region classification data. data/external/GLOBathy_hAV_relationships.nc: Lake bathymetry data from GLOBathy. data/external/BasinATLAS_v10_shp/: HydroSHEDS Level-06 river basin shapefile and attributes, including human population counts (pop_ct_ssu) used for exposure analyses. Temperature Trend Data for Figure 2 data/processed/temp_trend_global_lakes.csv: Long-term warming trends for each lake, including profile_mean, surface_mean, bottom_mean, profile_summer, surface_summer, and bottom_summer. data/processed/global_mean_temperature_list.csv: Global mean lake temperature time series from 2000 to 2023. data/processed/global_mean_trend.csv: Depth-resolved intra-annual heatmap matrix showing temperature trends across 50 relative depths and 365 days, averaged across global lakes. Thermal Habitat Shift Data data/processed/daily_nonoverlap_results.npz: Daily long-term-warming habitat shift metrics: non_overlap_compound_all: habitat shift, S_habitat. non_overlap_depth_all: isotherm shift, S_isotherm. non_overlap_temp_all: temperature shift, S_temperature. data/processed/background_results.npz: Background physical drivers in data_all, including vertical temperature gradients, historical inter-annual temperature variability, and long-term warming magnitude. data/processed/heatwave_nonoverlap_results.npz: Heatwave-driven habitat shift metrics, including non_overlap_heatwave_lake_compound, non_overlap_heatwave_lake_depth, and non_overlap_heatwave_lake_temp. Demo Data data/demo/data_poyang.npy: Lightweight Poyang Lake daily temperature-profile demo array. Rows are daily time steps from 2000-01-01 to 2023-12-31, and columns are depth layers from the water surface to 20 m. 6. Installation Guide Install Python 3.13 or a compatible Python 3 version. Install the required packages: Download or extract the repository while preserving the directory structure above. Confirm that the shapefile components are present under data/external/BasinATLAS_v10_shp/. No compilation is required. 7. Demo Full-data demo The current repository can be tested by running one figure script from the scripts/ directory: cd scripts python Figure_2.py Expected output: A high-resolution figure file named Figure_2.png saved in results/figures/. Progress messages printed to the terminal. Expected runtime: Figure 2: typically minutes on a 64 GB desktop. Figures 3-5 may take longer because they load large .npz, NetCDF, and geospatial files. The exact runtime depends on disk speed, available memory, and geospatial library performance. Lightweight Poyang Lake demo The repository includes a lightweight demo dataset in data/demo/. It can be used to test the heatwave detector and thermal habitat shift calculations without loading the multi-GB processed global arrays. Run the demo from the repository root: python scripts/demo.py The demo performs the following steps: Loads data/demo/data_poyang.npy, a daily depth-resolved temperature-profile array for Poyang Lake. Uses the GLOBathy shape parameter from data/external/GLOBathy_hAV_relationships.nc to calculate a weighted profile-mean temperature time series. Detects heatwave events from the weighted profile-mean temperature. Calculates daily long-term thermal habitat shifts by comparing each 2023 calendar-day profile with the matching 2000 calendar-day profile. Calculates heatwave-day thermal habitat shifts by comparing each heatwave-day profile with the same-DOY climatological mean profile. Expected outputs in results/demo/: Output Description poyang_heatwave_events.csv Split heatwave events with event_index, date range, duration, intensity, accumulated intensity, and category. poyang_heatwave_events.csv Daily 2023-versus-2000 thermal habitat shift metrics: S_isotherm, S_temperature, and S_habitat. poyang_heatwave_events.csv Heatwave-day thermal habitat shift metrics. poyang_heatwave_events.csv Mean heatwave-day shift metrics aggregated by event_index. poyang_heatwave_2022_jun_sep.png June-September 2022 weighted temperature plot with climatology, threshold, and heatwave shading. poyang_long_term_shifts_2023_vs_2000.png Daily 2023-versus-2000 shift metrics plotted across the comparison year. On the tested Windows desktop, this demo runs in seconds. 8. Instructions for Reproducing the Main Figures Run each script from inside the scripts/ directory: cd scripts python Figure_2.py python Figure_3.py python Figure_4.py python Figure_5.py Expected outputs: Script Output Figure_2.py results/figures/Figure_2.png Figure_3.py results/figures/Figure_3.png Figure_4.py results/figures/Figure_4.png Figure_5.py results/figures/Figure_5.png Minor cosmetic changes, such as panel-label placement or legend adjustment, may have been applied to the final manuscript figures using Adobe Illustrator. 9. Script Descriptions Figure_2.py: Reproduces spatiotemporal and vertical patterns of global lake warming. It generates maps of annual and summer profile-averaged water temperature trends, latitude-trend profiles, depth-resolved seasonal heatmaps, and violin plots. Figure_3.py: Reproduces global thermal habitat shifts driven by long-term warming. It maps S_habitat, S_isotherm, and S_temperature, summarizes shifts by thermal region, and plots cumulative human population exposure. Figure_4.py: Reproduces global physical drivers and intra-annual evolution of thermal habitat shifts. It maps absolute vertical temperature gradients and inter-annual temperature variability, and plots seasonal vulnerability curves. Figure_5.py: Reproduces heatwave-driven thermal habitat shifts relative to long-term warming. It maps the ratio S_heatwave / S_long-term and summarizes regional patterns. demo.py: Runs the lightweight Poyang Lake workflow, including heatwave detection, long-term daily thermal habitat shifts, heatwave-day shifts, CSV export, and diagnostic plots. heatwave.py: Provides reusable heatwave event-detection utilities. The main function, heatwave_detect(), returns split heatwave event date ranges and event statistics. thermal_shift.py: Provides reusable thermal habitat shift utilities, including isotherm-depth interpolation, long-term daily shift metrics, and heatwave-day shift metrics.