ewatercycle


Nameewatercycle JSON
Version 2.4.0 PyPI version JSON
download
home_pageNone
SummaryA Python package for running and validating a hydrology model
upload_time2024-12-04 12:18:33
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseApache-2.0
keywords bmi fair geoscience ewatercycle
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # ewatercycle

![image](https://github.com/eWaterCycle/ewatercycle/raw/main/docs/examples/logo.png)

A Python package for running hydrological models.

[![Test CI](https://github.com/eWaterCycle/ewatercycle/actions/workflows/test.yml/badge.svg)](https://github.com/eWaterCycle/ewatercycle/actions/workflows/test.yml)
[![Lint CI](https://github.com/eWaterCycle/ewatercycle/actions/workflows/lint.yml/badge.svg)](https://github.com/eWaterCycle/ewatercycle/actions/workflows/lint.yml)
[![Build CI](https://github.com/eWaterCycle/ewatercycle/actions/workflows/build.yml/badge.svg)](https://github.com/eWaterCycle/ewatercycle/actions/workflows/build.yml)
[![codecov](https://codecov.io/gh/eWaterCycle/ewatercycle/graph/badge.svg?token=dAZma01eVz)](https://codecov.io/gh/eWaterCycle/ewatercycle)
[![Documentation Status](https://readthedocs.org/projects/ewatercycle/badge/?version=latest)](https://ewatercycle.readthedocs.io/en/latest/?badge=latest)
[![PyPI](https://img.shields.io/pypi/v/ewatercycle)](https://pypi.org/project/ewatercycle/)
[![image](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B-yellow)](https://fair-software.eu)
[![image](https://zenodo.org/badge/DOI/10.5281/zenodo.5119389.svg)](https://doi.org/10.5281/zenodo.5119389)
[![Research Software Directory Badge](https://img.shields.io/badge/rsd-ewatercycle-00a3e3.svg)](https://www.research-software.nl/software/ewatercycle)
[![SQAaaS badge shields.io](https://img.shields.io/badge/sqaaas%20software-silver-lightgrey)](https://api.eu.badgr.io/public/assertions/1iy8I58zRvm7P9en2q0Egg "SQAaaS silver badge achieved")
[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/eWaterCycle/ewatercycle)

The eWaterCycle package makes it easier to use hydrological models
without having intimate knowledge about how to install and run the
models.

- Uses container for running models in an isolated and portable way
    with [grpc4bmi](https://github.com/eWaterCycle/grpc4bmi)
- Generates rain and sunshine required for the model using
    [ESMValTool](https://www.esmvaltool.org/)
- Supports observation data from [GRDC or
    USGS](https://ewatercycle.readthedocs.io/en/latest/observations.html)
- Exposes [simple
    interface](https://ewatercycle.readthedocs.io/en/latest/user_guide.html)
    to quickly get up and running

## Install

The ewatercycle package needs some geospatial non-python packages to
generate forcing data. It is preferred to create a Conda environment to
install those dependencies:

```shell
curl -o conda-lock.yml https://raw.githubusercontent.com/eWaterCycle/ewatercycle/main/conda-lock.yml
conda install mamba conda-lock -n base -c conda-forge -y
conda-lock install --no-dev -n ewatercycle
conda activate ewatercycle
```

The ewatercycle package is installed with

```shell
pip install ewatercycle
```

The ewatercycle package ships without any models. Models are packaged in [plugins](https://ewatercycle.readthedocs.io/en/latest/plugins.html). To install all endorsed plugins use

```shell
pip install ewatercycle-hype ewatercycle-lisflood ewatercycle-marrmot ewatercycle-pcrglobwb ewatercycle-wflow ewatercycle-leakybucket
```

Besides installing software you will need to create a configuration
file, download several data sets and get container images. See the
[system setup
chapter](https://ewatercycle.readthedocs.org/en/latest/system_setup.html)
for instructions.

## Usage

Example using the [Marrmot M14
(TOPMODEL)](https://github.com/wknoben/MARRMoT/blob/master/MARRMoT/Models/Model%20files/m_14_topmodel_7p_2s.m)
hydrological model on Rhine catchment to generate forcing, run it
and produce a hydrograph.

<details>

<summary>
In condensed code:

```python
forcing = ewatercycle.forcing.sources['MarrmotForcing'].generate(...)
model = ewatercycle.models.sources['MarrmotM14'](forcing)
model.setup(...)
model.initialize()
while (model.time < model.end_time):
    model.update()
    value = model.get_value_as_xarray('flux_out_Q')
model.finalize()
ewatercycle.analysis.hydrograph(...)
```

(Click to see real code)
</summary>
In real code:

```python
import ewatercycle.analysis
import ewatercycle.forcing
import ewatercycle.models
import ewatercycle.observation.grdc
from ewatercycle.testing.fixtures import rhine_shape
import shapefile
import xarray as xr

forcing = ewatercycle.forcing.sources['MarrmotForcing'].generate(
    dataset='ERA5',
    start_time='2010-01-01T00:00:00Z',
    end_time='2010-12-31T00:00:00Z',
    shape=rhine_shape()
)

model = ewatercycle.models.sources['MarrmotM14'](version='2020.11', forcing=forcing)

cfg_file, cfg_dir = model.setup(
    threshold_flow_generation_evap_change=0.1,
)

model.initialize(cfg_file)

# flux_out_Q unit conversion factor from mm/day to m3/s
sf = shapefile.Reader(rhine_shape())
area = sf.record(0)['SUB_AREA'] * 1e6 # from shapefile in m2
conversion_mmday2m3s = 1 / (1000 * 24 * 60 * 60)
conversion = conversion_mmday2m3s * area

simulated_discharge = []
while (model.time < model.end_time):
    model.update()
    simulated_discharge.append(
        model.get_value_as_xarray('flux_out_Q')
    )

observations_ds = ewatercycle.observation.grdc.get_grdc_data(
    station_id=6335020,  # Rees, Germany
    start_time=model.start_time_as_isostr,
    end_time=model.end_time_as_isostr,
    column='observation',
)

# Combine the simulated discharge with the observations
sim_da = xr.concat(simulated_discharge, dim='time') * conversion
sim_da.name = 'simulated'
discharge = xr.merge([sim_da, observations_ds["observation"]]).to_dataframe()
discharge = discharge[["observation", "simulated"]].dropna()

ewatercycle.analysis.hydrograph(discharge, reference='observation')

model.finalize()
```

</details>

More examples can be found in the plugins listed in the
[documentation](https://ewatercycle.readthedocs.io/en/latest/plugins.html).

## Contributing

If you want to contribute to the development of ewatercycle package,
have a look at the [contribution guidelines](CONTRIBUTING.md).

## License

Copyright (c) 2018 - 2024, Netherlands eScience Center & Delft University of
Technology

Apache Software License 2.0

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "ewatercycle",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "BMI, FAIR, Geoscience, ewatercycle",
    "author": null,
    "author_email": "Stefan Verhoeven <s.verhoeven@esciencecenter.nl>",
    "download_url": "https://files.pythonhosted.org/packages/cc/f2/cb97157fd52e6e867ea8d99dc1675899f15e51f2f128cc5f050a69df7d8b/ewatercycle-2.4.0.tar.gz",
    "platform": null,
    "description": "# ewatercycle\n\n![image](https://github.com/eWaterCycle/ewatercycle/raw/main/docs/examples/logo.png)\n\nA Python package for running hydrological models.\n\n[![Test CI](https://github.com/eWaterCycle/ewatercycle/actions/workflows/test.yml/badge.svg)](https://github.com/eWaterCycle/ewatercycle/actions/workflows/test.yml)\n[![Lint CI](https://github.com/eWaterCycle/ewatercycle/actions/workflows/lint.yml/badge.svg)](https://github.com/eWaterCycle/ewatercycle/actions/workflows/lint.yml)\n[![Build CI](https://github.com/eWaterCycle/ewatercycle/actions/workflows/build.yml/badge.svg)](https://github.com/eWaterCycle/ewatercycle/actions/workflows/build.yml)\n[![codecov](https://codecov.io/gh/eWaterCycle/ewatercycle/graph/badge.svg?token=dAZma01eVz)](https://codecov.io/gh/eWaterCycle/ewatercycle)\n[![Documentation Status](https://readthedocs.org/projects/ewatercycle/badge/?version=latest)](https://ewatercycle.readthedocs.io/en/latest/?badge=latest)\n[![PyPI](https://img.shields.io/pypi/v/ewatercycle)](https://pypi.org/project/ewatercycle/)\n[![image](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B-yellow)](https://fair-software.eu)\n[![image](https://zenodo.org/badge/DOI/10.5281/zenodo.5119389.svg)](https://doi.org/10.5281/zenodo.5119389)\n[![Research Software Directory Badge](https://img.shields.io/badge/rsd-ewatercycle-00a3e3.svg)](https://www.research-software.nl/software/ewatercycle)\n[![SQAaaS badge shields.io](https://img.shields.io/badge/sqaaas%20software-silver-lightgrey)](https://api.eu.badgr.io/public/assertions/1iy8I58zRvm7P9en2q0Egg \"SQAaaS silver badge achieved\")\n[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/eWaterCycle/ewatercycle)\n\nThe eWaterCycle package makes it easier to use hydrological models\nwithout having intimate knowledge about how to install and run the\nmodels.\n\n- Uses container for running models in an isolated and portable way\n    with [grpc4bmi](https://github.com/eWaterCycle/grpc4bmi)\n- Generates rain and sunshine required for the model using\n    [ESMValTool](https://www.esmvaltool.org/)\n- Supports observation data from [GRDC or\n    USGS](https://ewatercycle.readthedocs.io/en/latest/observations.html)\n- Exposes [simple\n    interface](https://ewatercycle.readthedocs.io/en/latest/user_guide.html)\n    to quickly get up and running\n\n## Install\n\nThe ewatercycle package needs some geospatial non-python packages to\ngenerate forcing data. It is preferred to create a Conda environment to\ninstall those dependencies:\n\n```shell\ncurl -o conda-lock.yml https://raw.githubusercontent.com/eWaterCycle/ewatercycle/main/conda-lock.yml\nconda install mamba conda-lock -n base -c conda-forge -y\nconda-lock install --no-dev -n ewatercycle\nconda activate ewatercycle\n```\n\nThe ewatercycle package is installed with\n\n```shell\npip install ewatercycle\n```\n\nThe ewatercycle package ships without any models. Models are packaged in [plugins](https://ewatercycle.readthedocs.io/en/latest/plugins.html). To install all endorsed plugins use\n\n```shell\npip install ewatercycle-hype ewatercycle-lisflood ewatercycle-marrmot ewatercycle-pcrglobwb ewatercycle-wflow ewatercycle-leakybucket\n```\n\nBesides installing software you will need to create a configuration\nfile, download several data sets and get container images. See the\n[system setup\nchapter](https://ewatercycle.readthedocs.org/en/latest/system_setup.html)\nfor instructions.\n\n## Usage\n\nExample using the [Marrmot M14\n(TOPMODEL)](https://github.com/wknoben/MARRMoT/blob/master/MARRMoT/Models/Model%20files/m_14_topmodel_7p_2s.m)\nhydrological model on Rhine catchment to generate forcing, run it\nand produce a hydrograph.\n\n<details>\n\n<summary>\nIn condensed code:\n\n```python\nforcing = ewatercycle.forcing.sources['MarrmotForcing'].generate(...)\nmodel = ewatercycle.models.sources['MarrmotM14'](forcing)\nmodel.setup(...)\nmodel.initialize()\nwhile (model.time < model.end_time):\n    model.update()\n    value = model.get_value_as_xarray('flux_out_Q')\nmodel.finalize()\newatercycle.analysis.hydrograph(...)\n```\n\n(Click to see real code)\n</summary>\nIn real code:\n\n```python\nimport ewatercycle.analysis\nimport ewatercycle.forcing\nimport ewatercycle.models\nimport ewatercycle.observation.grdc\nfrom ewatercycle.testing.fixtures import rhine_shape\nimport shapefile\nimport xarray as xr\n\nforcing = ewatercycle.forcing.sources['MarrmotForcing'].generate(\n    dataset='ERA5',\n    start_time='2010-01-01T00:00:00Z',\n    end_time='2010-12-31T00:00:00Z',\n    shape=rhine_shape()\n)\n\nmodel = ewatercycle.models.sources['MarrmotM14'](version='2020.11', forcing=forcing)\n\ncfg_file, cfg_dir = model.setup(\n    threshold_flow_generation_evap_change=0.1,\n)\n\nmodel.initialize(cfg_file)\n\n# flux_out_Q unit conversion factor from mm/day to m3/s\nsf = shapefile.Reader(rhine_shape())\narea = sf.record(0)['SUB_AREA'] * 1e6 # from shapefile in m2\nconversion_mmday2m3s = 1 / (1000 * 24 * 60 * 60)\nconversion = conversion_mmday2m3s * area\n\nsimulated_discharge = []\nwhile (model.time < model.end_time):\n    model.update()\n    simulated_discharge.append(\n        model.get_value_as_xarray('flux_out_Q')\n    )\n\nobservations_ds = ewatercycle.observation.grdc.get_grdc_data(\n    station_id=6335020,  # Rees, Germany\n    start_time=model.start_time_as_isostr,\n    end_time=model.end_time_as_isostr,\n    column='observation',\n)\n\n# Combine the simulated discharge with the observations\nsim_da = xr.concat(simulated_discharge, dim='time') * conversion\nsim_da.name = 'simulated'\ndischarge = xr.merge([sim_da, observations_ds[\"observation\"]]).to_dataframe()\ndischarge = discharge[[\"observation\", \"simulated\"]].dropna()\n\newatercycle.analysis.hydrograph(discharge, reference='observation')\n\nmodel.finalize()\n```\n\n</details>\n\nMore examples can be found in the plugins listed in the\n[documentation](https://ewatercycle.readthedocs.io/en/latest/plugins.html).\n\n## Contributing\n\nIf you want to contribute to the development of ewatercycle package,\nhave a look at the [contribution guidelines](CONTRIBUTING.md).\n\n## License\n\nCopyright (c) 2018 - 2024, Netherlands eScience Center & Delft University of\nTechnology\n\nApache Software License 2.0\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "A Python package for running and validating a hydrology model",
    "version": "2.4.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/eWaterCycle/ewatercycle/issues",
        "Documentation": "https://ewatercycle.readthedocs.io/",
        "Homepage": "https://www.ewatercycle.org/",
        "Source Code": "https://github.com/eWaterCycle/ewatercycle"
    },
    "split_keywords": [
        "bmi",
        " fair",
        " geoscience",
        " ewatercycle"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4a2030bdde879a5697ee4118cd25406e24059e6a7e5c6c5f5a04b3e1c4e9143a",
                "md5": "e41a1912f31e44d24207723058d87fe7",
                "sha256": "02c4c74391aa30b479680929d4f8f34a5297334c35e074fba48d80d37e721adf"
            },
            "downloads": -1,
            "filename": "ewatercycle-2.4.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e41a1912f31e44d24207723058d87fe7",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 122467,
            "upload_time": "2024-12-04T12:18:30",
            "upload_time_iso_8601": "2024-12-04T12:18:30.709555Z",
            "url": "https://files.pythonhosted.org/packages/4a/20/30bdde879a5697ee4118cd25406e24059e6a7e5c6c5f5a04b3e1c4e9143a/ewatercycle-2.4.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "ccf2cb97157fd52e6e867ea8d99dc1675899f15e51f2f128cc5f050a69df7d8b",
                "md5": "d73ce9a1a2c03001328783196a95f3ff",
                "sha256": "6cd6323cc00d1c0c33cbb50d5feb558ae360dcb5e8df5aa274f006cde0fe76e7"
            },
            "downloads": -1,
            "filename": "ewatercycle-2.4.0.tar.gz",
            "has_sig": false,
            "md5_digest": "d73ce9a1a2c03001328783196a95f3ff",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 233477,
            "upload_time": "2024-12-04T12:18:33",
            "upload_time_iso_8601": "2024-12-04T12:18:33.016387Z",
            "url": "https://files.pythonhosted.org/packages/cc/f2/cb97157fd52e6e867ea8d99dc1675899f15e51f2f128cc5f050a69df7d8b/ewatercycle-2.4.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-04 12:18:33",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "eWaterCycle",
    "github_project": "ewatercycle",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "ewatercycle"
}
None
Elapsed time: 2.50277s