Task Scripts

spotforecast2 provides command-line task scripts for common forecasting workflows. These scripts are registered as console entry points and can be invoked directly via uv run or after package installation.

Available Taks

Command Description
spotforecast-demo Demonstration task comparing baseline, covariate, and custom models
spotforecast-n2o1 N-to-1 forecasting with weighted aggregation
spotforecast-n2o1-df N-to-1 forecasting using a DataFrame input
spotforecast-n2o1-cov N-to-1 forecasting with exogenous covariates
spotforecast-n2o1-cov-df N-to-1 forecasting with covariates and DataFrame input
spotforecast2-entsoe ENTSO-E energy forecasting pipeline (download, train, predict)

Demo Task

The spotforecast-demo command runs a comparison of three forecasting approaches:

  1. Baseline: Standard N-to-1 recursive forecaster
  2. Covariate-enhanced: Includes weather, holidays, and cyclical features
  3. Custom LightGBM: Optimized hyperparameters
# Run with default settings
uv run spotforecast-demo

# Force retraining and save plot
uv run spotforecast-demo --force_train true --html task_demo_plot.html

N-to-1 Forecasting Tasks

These tasks implement multi-output time series forecasting with weighted aggregation.

Basic N-to-1

uv run spotforecast-n2o1

N-to-1 with DataFrame Input

uv run spotforecast-n2o1-df

N-to-1 with Covariates

Includes weather data, holiday indicators, and cyclical time features.

uv run spotforecast-n2o1-cov

N-to-1 with Covariates and DataFrame

uv run spotforecast-n2o1-cov-df

Configuration

All tasks use sensible defaults but can be customized via:

  • Environment variables (e.g., ENTSOE_API_KEY)
  • Command-line arguments (use --help for details)
  • Configuration files stored in ~/spotforecast2_models/
# View available options for any command
uv run spotforecast-demo --help
uv run spotforecast2-entsoe predict --help

Model Persistence

Trained models are saved to ~/spotforecast2_models/<task_name>/ by default. This allows:

  • Incremental retraining: Only retrain when models are stale
  • Reproducibility: Models are versioned by task and timestamp
  • Auditability: Full training logs are stored alongside models

!!! warning “Safety-Critical Consideration” In production environments, always verify model checksums and training timestamps before deployment.

Testing

The task scripts are covered by comprehensive safety-critical tests to ensure reliability in production environments.

Running Tests

Run all ENTSO-E task tests:

uv run pytest tests/test_tasks_entsoe.py -v

Run specific test categories:

# Run only safety-critical tests
uv run pytest tests/test_tasks_entsoe.py::TestSafetyCriticalEntsoe -v

# Run parameter validation tests
uv run pytest tests/test_tasks_entsoe.py::TestSafetyCriticalEntsoe::test_train_lgbm_model_parameter_correctness -v

# Run with coverage
uv run pytest tests/test_tasks_entsoe.py --cov=spotforecast2.tasks.task_entsoe --cov-report=html

Test Categories

The test suite includes:

  • Parameter Validation: Ensures correct parameter passing between CLI and internal functions
  • Error Handling: Validates graceful degradation and meaningful error messages
  • Data Validation: Tests boundary conditions and edge cases
  • Integration Tests: Verifies end-to-end functionality
  • Regression Tests: Protects against known historical bugs
  • Model Selection Safety: Prevents model mismatch in production pipelines

!!! tip “Continuous Testing” Run tests before deployment in production environments: bash uv run pytest tests/ -v --tb=short

ENTSO-E Task

The spotforecast2-entsoe command provides a unified CLI for the ENTSO-E energy forecasting pipeline. It is described in the separate document ENTSO-E Task.