How cmeo97/nowcastinggpt works
Project type and purpose
• This is a research-oriented, full-stack machine-learning system for extreme precipitation nowcasting.
• It consists of data ingestion & preprocessing, model training (VQ-VAE tokeniser + autoregressive Transformer), evaluation/prediction, configuration management, and experiment logging.
File structure
• Top-level directories:
• Dataset_CSV_Files (raw CSV pointers to radar images)
• config (YAML configs for tokenizer and world_model/trainer)
• asset (static images for documentation)
• src (all Python source code, subdivided into preprocessing, model definitions, training, prediction, and utilities)
• Key scripts:
• src/Resize_Images.py → converts raw images → NumPy arrays
• src/collector.py → builds PyTorch DataLoaders
• src/main.py & trainer.sh → orchestrate end-to-end training and evaluation
• src/make_prediction.py & make_reconstructions.py → generate and save predicted/reconstructed frames
• src/trainer.py → training loop wrapper (integrates with Weights & Biases)
• Models in src/models:
• tokenizer (VQ-VAE nets, LPIPS loss, discrete tokeniser)
• transformer (autoregressive world model + classifier head)
• Config files: define hyperparameters, paths, wandb settings.
README for additional insights
• The system is built around:
• A VQ-VAE “tokeniser” that compresses radar frames into discrete codes
• A Transformer “world model” that autoregressively predicts future token sequences
• An Extreme Value Loss (EVL) regularization module
• Training and evaluation are driven by YAML configurations and a Bash wrapper.
• Logging to Weights & Biases is built-in.
Components & Interactions
a. Main components:
1. Data Source: CSV files pointing to radar image archives
2. Preprocessing: Resize_Images.py → NumPy arrays
3. Data Loader: Collector class → PyTorch DataLoaders
4. Model Stack:
• VQ-VAE Tokeniser (src/models/tokenizer/*)
• Autoregressive Transformer (src/models/transformer.py + classifier)
• Extreme Value Loss module (integrated into trainer)
5. Training Orchestrator:
• main.py & trainer.py
• trainer.sh for shell control
6. Logging & Monitoring: Weights & Biases
7. Prediction/Evaluation:
• make_prediction.py → future frames
• make_reconstructions.py → VQ-VAE reconstructions
8. Outputs:
• outputs/<date>/media/predictions
• outputs/<date>/media/reconstructions
9. Configuration Store: config/*.yaml
10. Utilities: src/utils.py, kv_caching, slicer, etc.
b. Relationships & data flow:
• Raw CSV metadata → (Resize_Images) → NumPy arrays
• NumPy arrays → (Collector) → DataLoader batches
• Batches → (VQ-VAE) → discrete tokens → (Transformer) → predicted token sequences
• Tokens → (Reconstruction) → frames → saved to outputs
• Trainer orchestrates forward/backward passes, EVL computation, calls wandb API.
c. Architectural patterns:
• Modular pipeline (ETL → modeling → evaluation)
• Clear separation of concerns: preprocessing, data loading, model definition, training logic, config
• Config-driven execution (YAML) for reproducibility
• Use of a script wrapper (trainer.sh) for remote/nohup execution
d. Key technologies & libraries:
• Python 3.8.16, PyTorch 1.11.0, Torchvision, Torchaudio
• PyTorch Lightning utilities, torchmetrics, pycm
• Weights & Biases for logging
• YAML for configuration