WAS Disaggregation

Forecast-conditioned stochastic weather generation and daily downscaling on xarray grids, developed by Mandela HOUNGNIBO.

• PyPI distribution: was-disaggregation
• Python import: was_disaggregation
• Version: 0.8.0 (development/alpha)
• License: GPL-3.0-only; see LICENSE.

The distribution name was changed from the inconsistent was-weather metadata in the original development archive. The was-weather command remains an alias of was-disaggregation; Python imports use was_disaggregation.

Install and develop

After publication:

python -m pip install was-disaggregation
python -m pip install 'was-disaggregation[ml]'  # optional PyTorch methods

From the GitHub repository, with Pixi already installed:

git clone https://github.com/hmandela/was-disaggregation.git
cd was-disaggregation
pixi install
pixi run test
pixi run release-check

The default Pixi environment uses Python 3.12 on Linux x86-64, Windows x64, macOS Intel and macOS Apple Silicon. The same committed pixi.lock covers all four targets, and .github/workflows/ci.yml checks each one on GitHub after the code is pushed. Additional environments are ml and notebooks: pixi run -e ml test and pixi run -e notebooks jupyter lab. PyTorch is imported only when a neural method requires it. pixi.lock records the dependency solution; retain it in version control when generated by pixi install.

In HindcastExperiment.run(n_jobs>1), Linux parallelizes leave-one-year-out folds with fork. Windows and macOS run those folds sequentially and emit a warning because arbitrary user-supplied fit/predict functions need not be serializable for spawn-based workers. The results and n_jobs=1 API remain available on all platforms.

Input contract

Daily observations use dimensions (T, Y, X) with explicit time, latitude and longitude coordinates. Supported variables are PRCP, TMIN, TMAX, HUMIN, HUMAX, WIND and SOLAR. Supply units on every variable; recognized units are converted to these canonical units:

Wind force categories are not wind speeds. Daily solar input in W m-2 must be a daily mean flux. Use unit_overrides with open_observations when a source's metadata need correction. Grids and times of separate observation files must align exactly. Coordinate aliases such as time, lat and lon are accepted.

Forecast probabilities are a DataArray with dimensions (probability, Y, X) and labels PB, PN, PA. Fractions or percentages are accepted when their sum is within 2% of 1 or 100, then normalized. Invalid triples are masked. Constraint forecasts additionally accept labelled early/normal/late or short/normal/long categories. Select the intended issue time explicitly when working with a multi-time forecast file.

Months must be consecutive, for example (7, 8, 9) or (12, 1, 2). The season year is the year of its first month. The package uses Gregorian dates with February 29 omitted. Native 360-day calendars require explicit preprocessing. Incomplete observed days remain missing and cannot become zero rainfall totals.

Generate daily weather

from was_disaggregation import WeatherGenerator, open_observations, load_probabilities

obs = open_observations({"PRCP": "Daily_PRCP_1991_2024.nc"})
prob = load_probabilities("Forecast_Prob_PRCPJulAugSep_2025.nc", target=obs)
model = WeatherGenerator(
    months=(7, 8, 9), climatology=(1994, 2016), seed=42,
    spatial="distance", conditioning="mixture",
).fit(obs, prob)
generated = model.generate(year=2025, n_members=100)
generated.to_netcdf("weather_JAS_2025.nc")
obs.close()

Use the climatological period defining your forecast provider's categories; (1994, 2016) is an example, not an inferred property of an input file. For large domains, generate_dask builds a lazy tiled dataset. A command-line example is:

pixi run was-disaggregation \
  --obs Daily_PRCP_1991_2024.nc \
  --forecast Forecast_Prob_PRCPJulAugSep_2025.nc \
  --output weather_JAS_2025.nc --year 2025 --months 7 8 9 \
  --climatology 1994 2016 --members 100 --member-batch 20 --tile 10 10

examples/synthetic_smoke.py provides a runnable example without external data.

Methods and interpretation

These are implemented variants inspired by the literature named in module docstrings. They are not certified reproductions of every cited method. Conditioning daily parameters or drawing parameter classes does not guarantee that generated seasonal totals exactly reproduce PB/PN/PA frequencies. In particular, the automatic mixture shrinkage uses approximate seasonal moments; run-length occurrence, month transitions and finite ensembles require empirical verification. MRE/Croley constraints are penalties on historical weights and can conflict; inspect achieved probabilities and effective sample sizes.

Cross-validation must fit corrections, scalers, predictors and model parameters using training data only. The climatology defining externally supplied forecast categories is a separate explicit choice. Validate independent hindcasts against observed seasonal totals, wet-day frequency, spells, extremes, temporal/spatial dependence, variable bounds and reliability before operational use. The included regressions check software behavior; no regional skill claim is inferred from synthetic tests.

Publication

See docs/PUBLICATION_PIXI_FR.md for GitHub, TestPyPI and PyPI steps and docs/AUDIT_FR.md for corrections and remaining validation work. Publishing uses Twine inside Pixi. Tokens are entered at the local prompt and are never written into this source archive. Change was_disaggregation/_version.py before each new release; PyPI does not allow reusing a previously uploaded artifact name.