How ithronne/rr-former works
Project type and purpose
• This is an open-source ML tool for rainfall–runoff modeling, centered on a Transformer architecture (“RR-Former”).
• Key workflows: pretraining a global model, testing it (globally or per–basin), then fine-tuning and testing.
File structure
• Top-level scripts:
– pretrain.py / pretrain_test_global.py / pretrain_test_single.py
– fine_tune.py / fine_tune_test.py
• Core modules:
– configs/ (all experiment, dataset, model, run–time settings)
– data/ (raw list files, dataset loader)
– models/ (Transformer and LSTM implementations)
– utils/ (training loops, evaluation, metrics, loss, learning‐rate strategies)
README insights
• Workflow stages:
– Pretrain on CAMELS data → evaluate globally or per basin
– Fine‐tune from pretrained weights → evaluate
• Configuration is entirely code‐based under configs/.
• Data must be downloaded separately and pointed to via configs.
Main components and interactions
a. Data Ingestion & Preprocessing
– data/*.txt files (raw basin lists) + data/dataset.py
– Controlled by configs/data_shape_config.py & configs/dataset_config.py
b. Configuration Manager
– project_config.py sets global paths
– model_config/ (LSTM vs. Transformer hyperparameters)
– run_config/ (pretrain vs. fine_tune settings)
c. Model Definitions
– models/transformer/transformer.py (RR-Former)
– models/lstm/* (alternative architectures)
d. Training Pipeline
– pretrain.py / fine_tune.py invoke utils/train_epoch.py and utils/train_full.py
– Read data → build model with selected config → loop epochs → save checkpoints
e. Evaluation Pipeline
– pretrain_test_*.py / fine_tune_test.py use utils/eval_model.py, utils/metrics.py, utils/test_full.py
f. Auxiliary Utilities
– utils/lr_strategies.py, utils/nseloss.py for specialized losses and schedulers
– utils/tools.py for I/O and logging
Architectural patterns and principles
• Separation of concerns:
– Configs decoupled from code, enabling reproducibility
– Modular model implementations vs. generic training/eval loops
• Pipeline pattern: distinct stages (ingest → preprocess → train → evaluate)
• Extensibility: plug in new model architectures by dropping them into models/
– “Model Zoo” cluster containing Transformer and LSTM modules
– “Training Pipeline” process block
– “Evaluation Pipeline” process block
– Configs → Data Ingestion
– Configs → Model Zoo
– Data Ingestion → Training Pipeline
– Model Zoo → Training Pipeline
– Training Pipeline → Checkpoints & Logs
– Checkpoints & Logs + Data Ingestion → Evaluation Pipeline
– Evaluation Pipeline → Logs / Metrics outputs
c. Highlighted patterns:
– Pipeline stages in sequence (left to right or top to bottom)
– Components grouped by directory (configs, data, models, utils)
d. Technologies & frameworks:
– Python modules (no external services)
– Core dependencies implied: PyTorch/TensorFlow (specify if known)
– Data files on local FS; model artifacts on disk