How vitusbenson/greenearthnet works
Project Type and Purpose
• This is a research-oriented machine-learning codebase for multi-modal geospatial vegetation forecasting.
• It provides scripts to train, test (inference), and evaluate a variety of spatio-temporal models (e.g., Contextformer, ConvLSTM, PredRNN, SimVP) on the GreenEarthNet dataset, plus a small suite of pixel-wise baseline models.
• It is not a full-stack web app but a pipeline-style system: data ingestion → preprocessing (cloud masking) → model training/inference → evaluation.
High-Level File/Directory Analysis
• Top‐level scripts:
• train.py – launches training according to a YAML config
• test.py – runs inference, producing predicted output cubes
• eval.py – computes performance metrics on saved predictions
• cloudmask/train_cloudmask_l2argbnir.py – trains a cloud-masking U-Net
• model_configs/… – nested directories of YAML configuration files for each model variant (Contextformer, ConvLSTM, etc.)
• model_pixelwise/… – Python scripts implementing simple baselines (persistence, climatology, Kalman+XGB, etc.)
• Dependencies: earthnet & earthnet-minicuber for data handling; earthnet-models-pytorch and PyTorch Lightning for model implementations and training loops.
Main Components
A. Data Layer
• Raw Data Store (“GreenEarthNet Dataset”) – downloaded via earthnet toolkit, stored on disk (data_dir)
• Data Generation Module (“EarthNet Minicuber”) – produces aligned “minicubes” of multi-modal geospatial inputs
B. Preprocessing Layer
• Cloud Mask Algorithm – either uses pretrained model from earthnet-minicuber or trains new one via cloudmask/train_cloudmask_l2argbnir.py
C. Configuration Layer
• model_configs directory – YAML files specifying model architecture, hyperparameters, seed, weather tokens, etc.
D. Modeling Layer
• External Model Library – earthnet-models-pytorch contains implementations of Contextformer, ConvLSTM, PredRNN, SimVP, etc.
• Pixelwise Baselines – small scripts under model_pixelwise/ for non-deep-learning baselines
E. Training Pipeline
• train.py – reads a config, instantiates a PyTorch Lightning Trainer and DataModule, kicks off training, checkpoints weights
• Logging – TensorBoard, CLI outputs
F. Inference Pipeline
• test.py – loads checkpoint + YAML config, runs forward pass on test splits, writes predictions to disk
G. Evaluation Pipeline
• eval.py – takes ground-truth dataset and predictions, computes accuracy metrics, supports optional comparison directory
Relationships and Data Flows
• Config files feed into both Training and Inference pipelines
• Inference pipeline reads from Checkpoints + Raw Data → Prediction outputs
• Evaluation reads from Raw Data + Predictions → Scores
• Pixelwise Baselines bypass Deep Learning models: Raw Data → model_pixelwise scripts → Predictions → Eval
Architectural Patterns and Principles
• Pipeline architecture: clearly separated stages (ingestion, preprocessing, training, inference, evaluation)
• Config-driven design: no hard-coded hyperparameters; all behavior controlled by YAML.
• Modularization: distinct modules for deep models vs. pixel-wise baselines vs. cloud masking.
• Use of external libraries for domain-specific logic (earthnet, earthnet-minicuber, earthnet-models-pytorch).
• Clear, consistent labels on every component (e.g., “train.py (PyTorch Lightning Trainer)”)