# `swxg`
`swxg` is a Python package for modern [stochastic weather generation](https://www.ipcc-data.org/guidelines/pages/weather_generators.html). It is suitable for any use case where traces of precipitation, temperature, and its internal variability across a single or multiple sites impact the model outcomes to be investigated. It expands on existing generators which are often designed for more niche applications like replicating weather regimes, downscaling global circulation models, or using weather as an intermediate step in determining flood or drought indices.
All that is needed to use `swxg` is a set of data with precipitation and temperature observations, one or more locations where the observations were collected, and a timestamp for each of the collected observations. `swxg` quickly generates arbitrarily-long sequences of monthly or daily weather variables that match the spatial and temporal correlations from input observations by:
1. fitting observed precipitation individually to a (Gaussian mixture) hidden Markov model with 1 or more hidden states;
2. fitting both observed precipitation and temperature with hydroclimatic copulas;
3. sampling precipitation from its fit, disaggregating to finer resolution where necessary, and;
4. conditionally sampling temperature from the sampled precipitation and its fit, disaggregating to finer resolution where necessary
## Dependencies
The required dependencies to use `swxg` are:
* `Python >= 3.10`
* `copulae >= 0.8`
* `copulas >= 0.10, < 0.12`
* `hmmlearn >= 0.3`
* `matplotlib >= 3.8`
* `numpy == 2.0`
* `pandas >= 2.1`
* `scikit-learn >= 1.4`
* `scipy >= 1.15`
* `statsmodels >= 0.14, < 0.15`
Note that these required packages will be automatically downloaded when you install this package.
## Installation
To install `swxg` from PyPI with `pip`:
pip install swxg
Alternatively, you can install from this repository:
git clone https://github.com/xthames/swxg.git
cd swxg
pip install .
## Contributing, Reporting Issues, and Seeking Support
To **contribute**, please fork this repository and create your own branch. If you are unfamiliar with that process [the corresponding documentation on how to do so from FirstContributions](https://github.com/firstcontributions/first-contributions#first-contributions) is a good place to start. To **report issues** and **seek support**, please use the [GitHub Issues](https://github.com/xthames/swxg/issues) tab for this repository.
## Important Links
* [Official Source Code](https://github.com/xthames/swxg)
* [Documentation](https://swxg.readthedocs.org)
If your work uses `swxg`, please cite:
* [JORS PAPER IN PREP], specifically for the software
* [WRR PAPER IN PREP], if relevant to applied (first) use case
## Known Model Limitations
Because `swxg` is a semi-parametric model, the quality of the input dataset will be reflected in: (1) the confidence of the fits for precipitation and the copulas, and; (2) the resolution of the generated weather.
1. To fit precipitation and the copulas `swxg` aggregates precipitation and temperature both annually and monthly, meaning that more complete years of input data will produce better fitting. A `UserWarning` will appear **if you use fewer than 20 years of input data**. Fitting will still procede regardless, but it is strongly recommended to validate the precipitation and copula fitness through additional metrics for smaller input datasets.
2. When generating weather `swxg` gives the option to determine its output resolution, either at the `monthly` or `daily` scale. How resolved the generated weather can be is determined by the input dataset: `monthly` inputs can be resolved to `monthly` outputs; `daily` inputs can be resolved to both `daily` and `monthly` outputs. A `UserWarning` will appear when **trying to resolve `daily` outputs from `monthly` inputs**. If attempted, the `monthly` resolution will output instead. Subdaily inputs are accepted but generating at the subdaily scale is not yet implemented, and so subdaily data is aggregated to daily.
Raw data
{
"_id": null,
"home_page": null,
"name": "swxg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "swxg, stochastic, synthetic, weather, generator, semiparametric, copula, precipitation, temperature",
"author": null,
"author_email": "Alexander Thames <alexander.b.thames@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ad/73/a28e1800bdb4db8a8f3ccd7d90cb5b05ddb82ed5055ef9207f5e2d1aa3af/swxg-0.3.0.tar.gz",
"platform": null,
"description": "# `swxg`\n`swxg` is a Python package for modern [stochastic weather generation](https://www.ipcc-data.org/guidelines/pages/weather_generators.html). It is suitable for any use case where traces of precipitation, temperature, and its internal variability across a single or multiple sites impact the model outcomes to be investigated. It expands on existing generators which are often designed for more niche applications like replicating weather regimes, downscaling global circulation models, or using weather as an intermediate step in determining flood or drought indices.\n\nAll that is needed to use `swxg` is a set of data with precipitation and temperature observations, one or more locations where the observations were collected, and a timestamp for each of the collected observations. `swxg` quickly generates arbitrarily-long sequences of monthly or daily weather variables that match the spatial and temporal correlations from input observations by: \n 1. fitting observed precipitation individually to a (Gaussian mixture) hidden Markov model with 1 or more hidden states; \n 2. fitting both observed precipitation and temperature with hydroclimatic copulas;\n 3. sampling precipitation from its fit, disaggregating to finer resolution where necessary, and;\n 4. conditionally sampling temperature from the sampled precipitation and its fit, disaggregating to finer resolution where necessary\n\n## Dependencies\nThe required dependencies to use `swxg` are:\n * `Python >= 3.10`\n * `copulae >= 0.8`\n * `copulas >= 0.10, < 0.12`\n * `hmmlearn >= 0.3`\n * `matplotlib >= 3.8`\n * `numpy == 2.0`\n * `pandas >= 2.1`\n * `scikit-learn >= 1.4`\n * `scipy >= 1.15`\n * `statsmodels >= 0.14, < 0.15`\n\nNote that these required packages will be automatically downloaded when you install this package.\n\n## Installation\nTo install `swxg` from PyPI with `pip`:\n\n pip install swxg\n\nAlternatively, you can install from this repository:\n\n git clone https://github.com/xthames/swxg.git\n cd swxg\n pip install .\n\n## Contributing, Reporting Issues, and Seeking Support\nTo **contribute**, please fork this repository and create your own branch. If you are unfamiliar with that process [the corresponding documentation on how to do so from FirstContributions](https://github.com/firstcontributions/first-contributions#first-contributions) is a good place to start. To **report issues** and **seek support**, please use the [GitHub Issues](https://github.com/xthames/swxg/issues) tab for this repository.\n\n## Important Links\n * [Official Source Code](https://github.com/xthames/swxg)\n * [Documentation](https://swxg.readthedocs.org)\n\nIf your work uses `swxg`, please cite: \n * [JORS PAPER IN PREP], specifically for the software\n * [WRR PAPER IN PREP], if relevant to applied (first) use case\n\n## Known Model Limitations\nBecause `swxg` is a semi-parametric model, the quality of the input dataset will be reflected in: (1) the confidence of the fits for precipitation and the copulas, and; (2) the resolution of the generated weather. \n 1. To fit precipitation and the copulas `swxg` aggregates precipitation and temperature both annually and monthly, meaning that more complete years of input data will produce better fitting. A `UserWarning` will appear **if you use fewer than 20 years of input data**. Fitting will still procede regardless, but it is strongly recommended to validate the precipitation and copula fitness through additional metrics for smaller input datasets.\n 2. When generating weather `swxg` gives the option to determine its output resolution, either at the `monthly` or `daily` scale. How resolved the generated weather can be is determined by the input dataset: `monthly` inputs can be resolved to `monthly` outputs; `daily` inputs can be resolved to both `daily` and `monthly` outputs. A `UserWarning` will appear when **trying to resolve `daily` outputs from `monthly` inputs**. If attempted, the `monthly` resolution will output instead. Subdaily inputs are accepted but generating at the subdaily scale is not yet implemented, and so subdaily data is aggregated to daily. \n",
"bugtrack_url": null,
"license": null,
"summary": "Fast, region-agnostic stochastic weather generation",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://swxg.readthedocs.io/",
"Homepage": "https://github.com/xthames/swxg",
"Repository": "https://github.com/xthames/swxg.git"
},
"split_keywords": [
"swxg",
" stochastic",
" synthetic",
" weather",
" generator",
" semiparametric",
" copula",
" precipitation",
" temperature"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d8c3b8de8a1644550d26cad44f6ea25aa3a83c5a59372721ba611b8ba3a5569d",
"md5": "0cfd3b49afc40b2d7e4a953eba8c2e26",
"sha256": "2233f772d38d61e5051e3b6923a7db84717eaad8e03da822591813a55568f2e5"
},
"downloads": -1,
"filename": "swxg-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0cfd3b49afc40b2d7e4a953eba8c2e26",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 495279,
"upload_time": "2025-10-23T03:15:08",
"upload_time_iso_8601": "2025-10-23T03:15:08.155146Z",
"url": "https://files.pythonhosted.org/packages/d8/c3/b8de8a1644550d26cad44f6ea25aa3a83c5a59372721ba611b8ba3a5569d/swxg-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ad73a28e1800bdb4db8a8f3ccd7d90cb5b05ddb82ed5055ef9207f5e2d1aa3af",
"md5": "d6b7e97d0482ed585b1ed8830ed0d658",
"sha256": "2972fa93637b9f7e80b95ab839183a373c71db94f92c72d4931da7289a24650c"
},
"downloads": -1,
"filename": "swxg-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "d6b7e97d0482ed585b1ed8830ed0d658",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 489443,
"upload_time": "2025-10-23T03:15:09",
"upload_time_iso_8601": "2025-10-23T03:15:09.767119Z",
"url": "https://files.pythonhosted.org/packages/ad/73/a28e1800bdb4db8a8f3ccd7d90cb5b05ddb82ed5055ef9207f5e2d1aa3af/swxg-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 03:15:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xthames",
"github_project": "swxg",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "swxg"
}
JSON
