Metadata-Version: 2.4
Name: was-disaggregation
Version: 0.8.0
Summary: Forecast-conditioned gridded stochastic weather generation and daily downscaling
Author: Mandela HOUNGNIBO
License-Expression: GPL-3.0-only
Project-URL: Source, https://github.com/hmandela/was-disaggregation
Project-URL: Issues, https://github.com/hmandela/was-disaggregation/issues
Keywords: weather-generator,seasonal-forecast,downscaling,West-Africa,xarray
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: pandas>=2.0
Requires-Dist: xarray>=2023.6
Requires-Dist: netCDF4>=1.6
Requires-Dist: dask[array]>=2023.6
Provides-Extra: notebooks
Requires-Dist: jupyterlab>=4; extra == "notebooks"
Requires-Dist: nbformat>=5.9; extra == "notebooks"
Requires-Dist: nbclient>=0.9; extra == "notebooks"
Requires-Dist: matplotlib>=3.7; extra == "notebooks"
Provides-Extra: dask
Requires-Dist: dask[array,distributed]>=2023.6; extra == "dask"
Provides-Extra: ml
Requires-Dist: torch>=2.1; extra == "ml"
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Dynamic: license-file

# 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:

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

From the GitHub repository, with Pixi already installed:

```bash
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:

| Variable | Canonical unit |
| --- | --- |
| PRCP | mm d-1 |
| TMIN / TMAX | degC |
| HUMIN / HUMAX | % |
| WIND | m s-1 |
| SOLAR | MJ m-2 d-1 |

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

```python
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:

```bash
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

| Family | Main entry points | Interpretation |
| --- | --- | --- |
| Parametric | `WeatherGenerator`, `generate_dask` | Wet/dry Markov or run-length occurrence, Gamma/mixed-exponential rainfall, multivariate transformed residuals and spatial kernels |
| Historical resampling | `ForecastAnalogGenerator`, `ForecastSchaakeGenerator` | Forecast-weighted years/blocks and rank-based dependence templates |
| Multiple attributes | `SeasonalConstraint`, `SeasonalTotal`, `OnsetDate`, `CessationDate`, `MaxDrySpell` | Penalized MRE/Croley year weighting and member-selection diagnostics |
| GLM | `GLMWeatherGenerator`, `CoefficientGP` | Covariate-based daily weather and an optional spatial coefficient layer |
| Dynamical | `DailyBiasCorrector`, `DynamicalDownscaler`, `NHMM`, `NHSMM` | Daily model calibration, state sequences and dependence reordering |
| Neural | `GenerativeDownscaler` | Experimental conditional GAN and diffusion variants requiring PyTorch |
| Verification | `HindcastExperiment`, `daily_scores`, `reliability_table`, `rank_histogram` | Refitting experiments and ensemble diagnostics |

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.
