Skip to content

cli.md

Latest commit

 

History

History
216 lines (147 loc) · 5.34 KB

cli.md

File metadata and controls

216 lines (147 loc) · 5.34 KB
Raw

CLI Reference

Entry point: st-forecast

Commands

  • train - Train a forecasting model
  • predict - Generate hindcast predictions
  • evaluate - Evaluate predictions against observations
  • visualize - Generate visualizations
  • pipeline - Run complete end-to-end workflow

train

Train a forecasting model.

Usage

st-forecast train RUN_FOLDER [OPTIONS]

Arguments

Argument Description
RUN_FOLDER Directory where artifacts will be saved

Options

Option Type Default Description
--config, -c PATH None Path to config.json. Copied to run folder if not already present
--seed INT 42 Random seed for reproducibility

Example

st-forecast train ./runs/experiment_01 --config configs/my_config.json --seed 123

Outputs

  • {model_name}.pt - Trained model checkpoint
  • scalers/ - Fitted scalers for data normalization
  • train_loss.csv - Training loss history
  • val_loss.csv - Validation loss history

predict

Generate hindcast predictions using a trained model.

Usage

st-forecast predict RUN_FOLDER [OPTIONS]

Arguments

Argument Description
RUN_FOLDER Directory containing config.json, scalers, and trained model

Options

Option Type Default Description
--split, -s CHOICE test Data split to run hindcast on (train, val, test)
--num-samples INT config value Number of samples for probabilistic forecasting
--num-workers INT config value Number of DataLoader workers for faster inference

Example

st-forecast predict ./runs/experiment_01 --split test --num-samples 500

Outputs

  • predictions/{split}_predictions.parquet - Predictions with quantiles

evaluate

Evaluate model predictions against observations.

Usage

st-forecast evaluate RUN_FOLDER [OPTIONS]

Arguments

Argument Description
RUN_FOLDER Directory containing config.json and predictions/ directory

Options

Option Type Default Description
--split, -s CHOICE test Data split to evaluate (train, val, test)
--agricultural-only FLAG False Filter to agricultural period (months 4-9)

Example

st-forecast evaluate ./runs/experiment_01 --split test --agricultural-only

Outputs

  • metrics/{split}_performance.parquet - Per-basin, per-lead-time metrics (NSE, nRMSE, nMAE)
  • metrics/{split}_probabilistic.parquet - Probabilistic calibration metrics
  • metrics/{split}_flood.parquet - Flood detection metrics

visualize

Generate visualizations from model evaluation results.

Usage

st-forecast visualize RUN_FOLDER [OPTIONS]

Arguments

Argument Description
RUN_FOLDER Directory containing config.json and metrics/ directory

Options

Option Type Default Description
--split, -s CHOICE test Data split to visualize (train, val, test)
--all-plots FLAG False Generate all plots
--metrics FLAG False Generate metric boxplots (NSE, nRMSE, nMAE)
--flood FLAG False Generate flood metric plots
--probabilistic FLAG False Generate probabilistic calibration plots
--loss FLAG False Generate training loss plot
--forecasts FLAG False Generate example forecast plots
--agricultural-only FLAG False Use agricultural period metrics (months 4-9)

Example

# Generate all plots
st-forecast visualize ./runs/experiment_01 --all-plots

# Generate specific plots
st-forecast visualize ./runs/experiment_01 --metrics --probabilistic

Outputs

  • figures/ - PNG files for each requested plot type

pipeline

Run the complete forecasting pipeline: train → predict → evaluate → visualize.

Usage

st-forecast pipeline RUN_FOLDER [OPTIONS]

Arguments

Argument Description
RUN_FOLDER Directory where all artifacts will be saved

Options

Option Type Default Description
--config, -c PATH None Path to config.json. Copied to run folder if not already present
--seed INT 42 Random seed for training
--split, -s CHOICE test Data split for prediction/evaluation/visualization
--num-samples INT config value Number of samples for probabilistic forecasting
--num-workers INT config value Number of DataLoader workers
--agricultural-only FLAG False Filter evaluation to agricultural period (months 4-9)
--all-plots/--no-all-plots FLAG True Generate all visualization plots

Example

st-forecast pipeline ./runs/full_run \
    --config configs/production.json \
    --split test \
    --num-samples 500 \
    --agricultural-only

Outputs

All outputs from train, predict, evaluate, and visualize commands:

  • Model checkpoint and scalers
  • Loss histories
  • Predictions parquet
  • Evaluation metrics
  • Visualization figures