Metadata-Version: 2.5
Name: weathersynth
Version: 0.1.0
Summary: A reproducible K-nearest-neighbor weather generator.
Project-URL: Homepage, https://github.com/RomeoSilvestri/weathersynth
Project-URL: Issues, https://github.com/RomeoSilvestri/weathersynth/issues
Author: Romeo Silvestri
License: MIT
License-File: LICENSE
Keywords: knn,resampling,synthetic-data,weather
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Description-Content-Type: text/markdown

# WeatherSynth

WeatherSynth is a compact, reproducible K-nearest-neighbor (KNN) generator for
synthetic weather time series. It resamples observed successor states, retaining
their joint structure across all input variables. It is a weather generator, not
a weather-forecasting system.

This first public release intentionally contains only the KNN generator and its
calendar, validation, and reproducibility utilities. The API is experimental.

## Install

WeatherSynth requires Python 3.10 or later.

```bash
pip install weathersynth
```

## Quickstart

```python
from weathersynth import KNNWeatherGenerator
import numpy as np
import pandas as pd

rng = np.random.default_rng(7)
dates = pd.date_range("2000-01-01", periods=365 * 10, freq="D")
weather = pd.DataFrame(
    {
        "temperature": 12 + 10 * np.sin(2 * np.pi * dates.dayofyear / 365) + rng.normal(0, 2, len(dates)),
        "precipitation": rng.gamma(1.5, 3, len(dates)),
    },
    index=dates,
)

generator = KNNWeatherGenerator(random_state=42).fit(weather)
synthetic = generator.generate(start="2030-01-01", n_years=5)
```

Historical input must be a numeric pandas `DataFrame` with a regular
`DatetimeIndex`. Generated data has the same weather columns. See the KNN
constructor docstring for configuration options including seasonal matching,
feature weighting, exact-search backend, and ensemble generation.

## Development

Create the locked development environment:

```bash
uv sync --locked
```

Run the quality checks:

```bash
uv run ruff check src tests
uv run mypy src/weathersynth
uv run pytest
uv build
```

See [Changelog](CHANGELOG.md) for release notes.

## Citation and license

Citation metadata is available in [CITATION](CITATION.cff). WeatherSynth is
released under the [MIT License](LICENSE).
