Skip to main content

A Python package for running and validating a hydrology model

Project description

https://github.com/eWaterCycle/ewatercycle/raw/main/docs/examples/logo.png

A Python package for running hydrological models.

https://github.com/eWaterCycle/ewatercycle/actions/workflows/ci.yml/badge.svg https://sonarcloud.io/api/project_badges/measure?project=eWaterCycle_ewatercycle&metric=alert_status https://sonarcloud.io/api/project_badges/measure?project=eWaterCycle_ewatercycle&metric=coverage Documentation Status https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B%20%20%E2%97%8F%20%20%E2%97%8B-orange

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

  • Generates rain and sunshine required for the model using ESMValTool

  • Supports observation data from GRDC or USGS

  • Exposes simple interface 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:

wget https://raw.githubusercontent.com/eWaterCycle/ewatercycle/main/environment.yml
conda env create --file environment.yml
conda activate ewatercycle

The ewatercycle package is installed with

pip install git+https://github.com/eWaterCycle/ewatercycle.git#egg=ewatercycle

Besides installing software you will need to create a configuration file, download several data sets and get container images. See the system setup chapter for instructions.

Usage

Example using the Marrmot M14 (TOPMODEL) hydrological model on Merrimack catchment to generate forcing, run it and produce a hydrograph.

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,
)
observations_df = observations_df.rename(columns={'streamflow': '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 documentation.

Contributing

If you want to contribute to the development of ewatercycle package, have a look at the contribution guidelines.

License

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

Apache Software License 2.0

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ewatercycle-1.0.0.tar.gz (57.4 kB view details)

Uploaded Source

Built Distribution

ewatercycle-1.0.0-py3-none-any.whl (55.3 kB view details)

Uploaded Python 3

File details

Details for the file ewatercycle-1.0.0.tar.gz.

File metadata

  • Download URL: ewatercycle-1.0.0.tar.gz
  • Upload date:
  • Size: 57.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.6.1 pkginfo/1.7.1 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.2

File hashes

Hashes for ewatercycle-1.0.0.tar.gz
Algorithm Hash digest
SHA256 ae4cf5501d20afcd862ef8c84215e2752cfa5be80485489516507cfcdfea3082
MD5 4705ec39306c33de095f12841aea311c
BLAKE2b-256 281bd6fe410aaeb4f780e0659f67de4d87fbc4b0d9819bf97e1254406ba1beae

See more details on using hashes here.

File details

Details for the file ewatercycle-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: ewatercycle-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 55.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.6.1 pkginfo/1.7.1 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.2

File hashes

Hashes for ewatercycle-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 800c4ce73c9f1b87646ace07e44153e092831868bfaad3d7a3994b2a0a61ec4e
MD5 f5a949e9c068847434d3411657dcfd33
BLAKE2b-256 baa355a91b12f7c23dd1ebda429a8e6fde53fbfe4c5882e49397bddce664b5bd

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page