ewatercycle


Nameewatercycle JSON
Version 2.1.0 PyPI version JSON
download
home_pagehttps://www.ewatercycle.org/
SummaryA Python package for running and validating a hydrology model
upload_time2024-03-25 12:48:06
maintainerNone
docs_urlNone
authorStefan Verhoeven
requires_python>=3.10
licenseApache-2.0
keywords ewatercycle fair bmi geoscience
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.

[![image](https://github.com/eWaterCycle/ewatercycle/actions/workflows/ci.yml/badge.svg)](https://github.com/eWaterCycle/ewatercycle/actions/workflows/ci.yml)
[![image](https://sonarcloud.io/api/project_badges/measure?project=eWaterCycle_ewatercycle&metric=alert_status)](https://sonarcloud.io/dashboard?id=eWaterCycle_ewatercycle)
[![image](https://sonarcloud.io/api/project_badges/measure?project=eWaterCycle_ewatercycle&metric=coverage)](https://sonarcloud.io/component_measures?id=eWaterCycle_ewatercycle&metric=coverage)
[![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")

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
wget https://raw.githubusercontent.com/eWaterCycle/ewatercycle/main/environment.yml
conda install mamba -n base -c conda-forge -y
mamba env create --file environment.yml
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 Merrimack catchment to generate forcing, run it
and produce a hydrograph.

```python
import pandas as pd
import ewatercycle.analysis
import ewatercycle.forcing
import ewatercycle.models
import ewatercycle.observation.grdc

forcing = ewatercycle.forcing.generate(
    target_model='marrmot',
    dataset='ERA5',
    start_time='2010-01-01T00:00:00Z',
    end_time='2010-12-31T00:00:00Z',
    shape='Merrimack/Merrimack.shp'
)

model = ewatercycle.models.MarrmotM14(version="2020.11", forcing=forcing)

cfg_file, cfg_dir = model.setup(
    threshold_flow_generation_evap_change=0.1,
    leakage_saturated_zone_flow_coefficient=0.99,
    zero_deficit_base_flow_speed=150.0,
    baseflow_coefficient=0.3,
    gamma_distribution_phi_parameter=1.8
)

model.initialize(cfg_file)

observations_df, station_info = ewatercycle.observation.grdc.get_grdc_data(
    station_id=4147380,
    start_time=model.start_time_as_isostr,
    end_time=model.end_time_as_isostr,
    column='observation',
)

simulated_discharge = []
timestamps = []
while (model.time < model.end_time):
    model.update()
    value = model.get_value('flux_out_Q')[0]
    # flux_out_Q unit conversion factor from mm/day to m3/s
    area = 13016500000.0  # from shapefile in m2
    conversion_mmday2m3s = 1 / (1000 * 24 * 60 * 60)
    simulated_discharge.append(value * area * conversion_mmday2m3s)
    timestamps.append(model.time_as_datetime.date())
simulated_discharge_df = pd.DataFrame({'simulated': simulated_discharge}, index=pd.to_datetime(timestamps))

ewatercycle.analysis.hydrograph(simulated_discharge_df.join(observations_df), reference='observation')

model.finalize()
```

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, Netherlands eScience Center & Delft University of
Technology

Apache Software License 2.0

Raw data

            {
    "_id": null,
    "home_page": "https://www.ewatercycle.org/",
    "name": "ewatercycle",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "ewatercycle, FAIR, BMI, Geoscience",
    "author": "Stefan Verhoeven",
    "author_email": "s.verhoeven@esciencecenter.nl",
    "download_url": "https://files.pythonhosted.org/packages/0f/26/3a7166fc0373135083e0eca08e6abb7469f7c308581591c48118e992fb09/ewatercycle-2.1.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[![image](https://github.com/eWaterCycle/ewatercycle/actions/workflows/ci.yml/badge.svg)](https://github.com/eWaterCycle/ewatercycle/actions/workflows/ci.yml)\n[![image](https://sonarcloud.io/api/project_badges/measure?project=eWaterCycle_ewatercycle&metric=alert_status)](https://sonarcloud.io/dashboard?id=eWaterCycle_ewatercycle)\n[![image](https://sonarcloud.io/api/project_badges/measure?project=eWaterCycle_ewatercycle&metric=coverage)](https://sonarcloud.io/component_measures?id=eWaterCycle_ewatercycle&metric=coverage)\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\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\nwget https://raw.githubusercontent.com/eWaterCycle/ewatercycle/main/environment.yml\nconda install mamba -n base -c conda-forge -y\nmamba env create --file environment.yml\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 Merrimack catchment to generate forcing, run it\nand produce a hydrograph.\n\n```python\nimport pandas as pd\nimport ewatercycle.analysis\nimport ewatercycle.forcing\nimport ewatercycle.models\nimport ewatercycle.observation.grdc\n\nforcing = ewatercycle.forcing.generate(\n    target_model='marrmot',\n    dataset='ERA5',\n    start_time='2010-01-01T00:00:00Z',\n    end_time='2010-12-31T00:00:00Z',\n    shape='Merrimack/Merrimack.shp'\n)\n\nmodel = ewatercycle.models.MarrmotM14(version=\"2020.11\", forcing=forcing)\n\ncfg_file, cfg_dir = model.setup(\n    threshold_flow_generation_evap_change=0.1,\n    leakage_saturated_zone_flow_coefficient=0.99,\n    zero_deficit_base_flow_speed=150.0,\n    baseflow_coefficient=0.3,\n    gamma_distribution_phi_parameter=1.8\n)\n\nmodel.initialize(cfg_file)\n\nobservations_df, station_info = ewatercycle.observation.grdc.get_grdc_data(\n    station_id=4147380,\n    start_time=model.start_time_as_isostr,\n    end_time=model.end_time_as_isostr,\n    column='observation',\n)\n\nsimulated_discharge = []\ntimestamps = []\nwhile (model.time < model.end_time):\n    model.update()\n    value = model.get_value('flux_out_Q')[0]\n    # flux_out_Q unit conversion factor from mm/day to m3/s\n    area = 13016500000.0  # from shapefile in m2\n    conversion_mmday2m3s = 1 / (1000 * 24 * 60 * 60)\n    simulated_discharge.append(value * area * conversion_mmday2m3s)\n    timestamps.append(model.time_as_datetime.date())\nsimulated_discharge_df = pd.DataFrame({'simulated': simulated_discharge}, index=pd.to_datetime(timestamps))\n\newatercycle.analysis.hydrograph(simulated_discharge_df.join(observations_df), reference='observation')\n\nmodel.finalize()\n```\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, 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.1.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": [
        "ewatercycle",
        " fair",
        " bmi",
        " geoscience"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "7e0d6a1fc515db275a74c9351cd3c0d04a131e7c91ca84d567c06193c0a67f63",
                "md5": "cb8c4323390a6d3f39ca067d1e48765d",
                "sha256": "41311f75edde6db07aec759083ec7686de546ec6a6d7b3817a90b58743e73386"
            },
            "downloads": -1,
            "filename": "ewatercycle-2.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "cb8c4323390a6d3f39ca067d1e48765d",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 110242,
            "upload_time": "2024-03-25T12:48:04",
            "upload_time_iso_8601": "2024-03-25T12:48:04.138454Z",
            "url": "https://files.pythonhosted.org/packages/7e/0d/6a1fc515db275a74c9351cd3c0d04a131e7c91ca84d567c06193c0a67f63/ewatercycle-2.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "0f263a7166fc0373135083e0eca08e6abb7469f7c308581591c48118e992fb09",
                "md5": "6fdbfb32bfed81458e28eff8edf124ad",
                "sha256": "9c7d3c91c037e7ee693c808ed7b8153a738bdae6fe9037fbe5680bd657309ecf"
            },
            "downloads": -1,
            "filename": "ewatercycle-2.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "6fdbfb32bfed81458e28eff8edf124ad",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 105183,
            "upload_time": "2024-03-25T12:48:06",
            "upload_time_iso_8601": "2024-03-25T12:48:06.168806Z",
            "url": "https://files.pythonhosted.org/packages/0f/26/3a7166fc0373135083e0eca08e6abb7469f7c308581591c48118e992fb09/ewatercycle-2.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-25 12:48:06",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "eWaterCycle",
    "github_project": "ewatercycle",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "ewatercycle"
}
Stefan Verhoeven
Elapsed time: 0.22004s