WeatherCop is a multisite weather generator based on vine copulas. It was developed to generate synthetic weather scenarios that preserve both spatial dependencies across weather stations and temporal structure within each station. The package combines statistical copula theory with time series analysis from the VarWG library to create realistic weather ensembles for hydrodynamic and ecological modeling.

WeatherCop operates through a carefully choreographed workflow combining two complementary systems:

1. VarWG Component (marginal distributions):
   • Fits KDE/parametric distributions to each weather variable at each site, accounting for seasonal variations (F_doy)
   • Transforms measurement data to standard-normal space via inverse CDF of day-of-year distributions: Φ⁻¹(F_doy(X))
   • Handles dryness probability estimation for precipitation
   • Applies the inverse transformation to convert simulated data back to the measurement domain: X = F_doy⁻¹(Φ(Y))
2. WeatherCop Component (dependence structure):
   • Fits vine copulas to deseasonalized observations to capture inter-variate dependencies (relationships between different weather variables)
   • Decorrelates observations for phase randomization
   • Re-correlates synthetic data using the fitted copula structure
   • Preserves both temporal autocorrelation within each station and spatial cross-correlations between stations through phase randomization

This separation of concerns enables realistic what-if scenarios: by conditioning on a guiding variable (e.g., temperature), changes propagate to other variables through the vine copula's inter-variate dependence structure, while VarWG ensures each variable maintains realistic distributions and seasonal patterns.

The simplest way to install WeatherCop from PyPI:

pip install weathercop

This installs the package with all dependencies (including VarWG from PyPI).

WeatherCop uses uv for dependency management. To install:

1. Install uv if you haven't already:

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create a project with WeatherCop:

   uv init my_project
   cd my_project
   uv add weathercop

   Or to clone the repository for development:

   git clone https://github.com/iskur/weathercop
   cd weathercop
   uv sync
   python setup.py build_ext --inplace

For development with additional tools:

git clone https://github.com/iskur/weathercop
cd weathercop
uv sync --group dev
python setup.py build_ext --inplace

Note: The first import may take 5-10 minutes as Cython extensions compile. Pre-build them to avoid this delay.

After installation, you can use WeatherCop to generate multisite synthetic weather data:

import xarray as xr
import varwg as vg
from weathercop.multisite import Multisite, set_conf

# Configure VarWG (e.g., with your config module)
import your_vg_conf
set_conf(your_vg_conf)

# Load multisite weather data as xarray Dataset
# Expected dimensions: (time, station, variable)
xds = xr.open_dataset("path/to/multisite_data.nc")

# Initialize the multisite weather generator
wc = Multisite(
    xds,
    verbose=True,
)

# Generate a single realization
sim_result = wc.simulate()

# Generate an ensemble of 20 realizations
wc.simulate_ensemble(20)

# Visualize results
wc.plot_ensemble_stats()
wc.plot_ensemble_meteogram_daily()
wc.plot_ensemble_qq()

The first time you import weathercop, Cython extensions compile automatically. This is normal. To avoid the wait:

python setup.py build_ext --inplace

WeatherCop respects these environment variables:

• WEATHERCOP_DIR: Base directory for cache and data (default: ~/.weathercop)
• WEATHERCOP_ENSEMBLE_ROOT: Directory for ensemble outputs (default: $WEATHERCOP_DIR/ensembles)

Example:

export WEATHERCOP_DIR=/path/to/your/weathercop/data
python your_script.py

To run the test suite:

uv run pytest

Or install test dependencies and run:

uv sync --group test
uv run pytest

• Vine Copula Models: Canonical (C-vine) and Regular (R-vine) implementations
• Seasonal Variations: Time-varying copula parameters with Fourier series smoothing
• Multisite Generation: Simultaneous weather generation across multiple stations
• Comprehensive Copula Library: Clayton, Gumbel, Joe, Plackett, and many more families
• High Performance: Cython-optimized computations with automatic SymPy code generation
• Parallel Processing: Built-in multiprocessing support for large ensembles

• Initial release with vine copula implementations (CVine, RVine)
• Seasonal copula wrapper for time-varying parameters
• Integration with VarWG library for temporal structure preservation
• Automatic Cython code generation for copula functions
• Multisite weather generation workflows
• Migration to modern build system with pyproject.toml
• Dependency management with uv

Requirements: Python ≥ 3.13

Code is hosted at: <repository-url>

Related project: VarWG Weather Generator

MIT License

Copyright (c) iskur <[email protected]>

See the file "LICENSE" for information on the history of this software, terms & conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.