Human-induced vegetation shifts drive global declines in urban vegetation transpiration

Abstract

Title Code for: Human-induced vegetation shifts drive global declines in urban vegetation transpiration Description This repository contains the complete codebase for the manuscript "Human-induced vegetation shifts drive global declines in urban vegetation transpiration." The software implements a hybrid physics–deep learning framework (CNN-PM) for estimating urban vegetation transpiration (VTu), a six-model comparison framework for systematic architecture and input ablation analysis, a multi-source geospatial data preprocessing pipeline, and an XGBoost-SHAP trend attribution module. All code is written in Python and built on PyTorch. Repository structure The repository comprises eight modular packages, organized along the analysis pipeline from raw data ingestion through model training, evaluation, and trend attribution: 1. Data preprocessing pipeline (data_preprocessing/) Transforms raw multi-source geospatial data into model-ready input arrays. Handles 7 data sources (Landsat, TerraClimate, GLASS LAI, CAMS CO₂, GGA anthropogenic heat flux, WorldPop, VIIRS nighttime lights) at native resolutions ranging from 30 m to 10 km, performing quality control (physical range checks, IQR-based outlier detection, gap filling), spatial alignment (reprojection, resampling to a common 30 m grid), and temporal aggregation (half-hourly flux observations to daily/monthly means). Includes an eddy covariance flux station processor with u* filtering, energy balance closure assessment, and turbulence-based VTu partitioning. Outputs standardized .npz arrays compatible with all six comparison models. 2. Hybrid CNN-PM model with AHF (cnn_pm_model/) — Model #5 The primary model of the study. Couples two sub-CNN networks (CNN_c for climatic conductance G_c, CNN_a for anthropogenic conductance G_a) with a differentiable Penman-Monteith equation (PM-MU). CNN_c takes 10 vegetation/climate inputs through 3 convolutional layers; CNN_a takes 7 urban/anthropogenic inputs (including AHF) through 4 convolutional layers. Both output conductance values via Softplus activation, which are then passed to the PM-MU physics layer where AHF is explicitly added to the available energy term. The model is trained end-to-end with MSE loss, producing physically interpretable intermediate variables (G_c, G_a) alongside the final VTu estimate. 3. Hybrid CNN-PM model without AHF (cnn_pm_noahf/) — Model #6 Identical to model #5 except AHF is excluded from both CNN_a inputs (6 instead of 7) and the PM energy balance (Rn − G instead of Rn − G + AHF). Direct comparison with model #5 quantifies the added value of explicit AHF coupling in the hybrid framework. 4. Pure CNN model with AHF (pure_cnn_vtu/) — Model #3 A fully data-driven multi-branch 1D CNN with Squeeze-and-Excitation (SE) attention that directly predicts VTu from 14 input variables without embedding any physical equations. Inputs are grouped into three semantically coherent branches — vegetation (6 variables), meteorological (4 variables), and urban/AHF (4 variables) — each encoded by 3 residual convolutional blocks with channel gating, then fused via SE attention and regressed through a 4-layer fully connected head. Serves as the data-driven baseline for comparison against the physics-informed hybrid model. 5. Pure CNN model without AHF (pure_cnn_noahf/) — Model #4 Identical to model #3 except the urban branch receives 3 inputs instead of 4 (AHF removed). Comparison with model #3 quantifies AHF's contribution in the purely data-driven setting. 6. Pure PM model with AHF (pure_pm_vtu/) — Models #1 and #2 A pure physics-based implementation with approximately 20 learnable scalar parameters (no neural network weights). Stomatal conductance (G_c) is parameterized via Jarvis-type stress functions (soil moisture Hill function, VPD exponential closure, temperature parabolic optimum, light Michaelis-Menten saturation, Beer-Lambert LAI scaling, CO₂ stomatal response, vegetation composition sigmoid). Aerodynamic conductance (G_a) uses a wind-power-law base with roughness, stability, moisture, and AHF buoyancy correction terms. All parameters are optimized via backpropagation through the differentiable PM-MU equation. Provides the physics-only baseline with full parameter interpretability. 7. Pure PM model without AHF (pure_pm_noahf/) — Model #2 Identical to model #1 except the AHF buoyancy term in G_a and the AHF energy term in PM are removed (~19 instead of ~20 parameters). 8. Trend attribution (trend_attribution/) Implements a three-stage attribution pipeline: (i) Mann-Kendall trend tests with Sen's slope for VTu and all 13 drivers, (ii) XGBoost regression learning the functional relationship between drivers and VTu (R² > 0.9 required), and (iii) SHAP decomposition of VTu trends into individual driver contributions via Sen's slope of each variable's SHAP time series. Driver contributions are aggregated into landscape pattern change (fc, fimp, fwoody, fgrass, LAI) and climate change (Ta, Ts, AC, u, SM, VPD, AHF, Ra) categories following Equations [8]–[9] in the manuscript. Supports single-city and batch processing (3,560 cities) for both historical and future SSP scenarios. Six-model comparison framework A central design principle of this codebase is the systematic comparison of three model architectures (Pure PM, Pure CNN, Hybrid CNN-PM) × two AHF configurations (with/without), yielding six models trained and evaluated under an identical protocol: Model Architecture AHF Package Learnable parameters #1 Pure PM Yes pure_pm_vtu ~20 scalars #2 Pure PM No pure_pm_noahf ~19 scalars #3 Pure CNN Yes pure_cnn_vtu ~100K+ weights #4 Pure CNN No pure_cnn_noahf ~100K+ weights #5 Hybrid CNN-PM Yes cnn_pm_model ~100K+ weights #6 Hybrid CNN-PM No cnn_pm_noahf ~100K+ weights All six models share: MSE loss function, 80/20 train/validation split, 300× repeated cross-validation, identical evaluation metrics (KGE, RMSE, bias, MAPD), and 10 extreme-scenario stress tests. This design isolates the contributions of (a) physical constraints (PM vs. CNN vs. hybrid) and (b) anthropogenic heat flux coupling (with vs. without AHF) to model performance and physical realism. Training protocol All models are trained using Genetic Algorithm (GA) hyperparameter optimization over 70 generations across 300 cross-validation iterations. The GA simultaneously tunes learning rate, weight decay, and batch size, with convergence monitored via validation loss, RMSE, and KGE. Optimized hyperparameters: learning rate = 0.002 (both sub-models), weight decay = 0.006 (CNN_c) / 0.0015 (CNN_a), batch size = 32 (CNN_c) / 64 (CNN_a). Requirements Python ≥ 3.10 PyTorch ≥ 2.0 (CUDA 11.8+ recommended for GPU training) XGBoost ≥ 1.7 SHAP ≥ 0.42 scikit-learn ≥ 1.2 NumPy, pandas, SciPy, rasterio, netCDF4, h5py GDAL (for geospatial preprocessing) Each package includes its own requirements.txt for dependency management. Reproducibility To reproduce the results reported in the manuscript: Prepare raw data following the directory layout specified in data_preprocessing/README.md Run the preprocessing pipeline to generate model-ready .npz arrays Train all six models using the provided training scripts with 300× cross-validation Evaluate models and generate performance comparison tables Run the CNN-PM model (#5) for historical reconstruction (1986–2020) and future projection (2021–2100) across 3,560 cities Execute the trend attribution pipeline to decompose VTu trends into driver contributions Relationship to the data repository This code repository is designed to work with the companion data repository (see Related Identifiers), which provides all input datasets, intermediate results, and figure source data. The code processes raw observational and remote sensing data into the results and figures presented in the manuscript. Keywords urban vegetation transpiration, Penman-Monteith, convolutional neural network, physics-informed deep learning, hybrid model, SHAP, XGBoost, trend attribution, eddy covariance, anthropogenic heat flux, urban climate, geospatial data processing, SSP scenarios Programming Language Python License MIT License Related Identifiers Companion data repository: [Zenodo DOI to be added upon publication] Manuscript: Chen, H. et al. Human-induced vegetation shifts drive global declines in urban vegetation transpiration.