ewatercycle.base.forcing

Base classes for eWaterCycle forcings.

Configuring ESMValTool

To download data from ESFG via ESMValTool you will need a ~/.esmvaltool/config-user.yml file with something like:

search_esgf: when_missing
download_dir: ~/climate_data
rootpath:
    CMIP6: ~/climate_data/CMIP6
drs:
    CMIP6: ESGF

A config file can be generated with:

esmvaltool config get-config-user

See ESMValTool configuring docs for more information.

Module Contents

ewatercycle.base.forcing.logger
ewatercycle.base.forcing.FORCING_YAML = 'ewatercycle_forcing.yaml'
ewatercycle.base.forcing.AnyForcing
class ewatercycle.base.forcing.DefaultForcing

Bases: pydantic.BaseModel

Container for forcing data.

Parameters:
  • directory – Directory where forcing data files are stored.

  • start_time – Start time of forcing in UTC and ISO format string e.g. ‘YYYY-MM-DDTHH:MM:SSZ’.

  • end_time – End time of forcing in UTC and ISO format string e.g. ‘YYYY-MM-DDTHH:MM:SSZ’.

  • shape – Path to a shape file. Used for spatial selection. If relative then it is relative to the given directory.

start_time: str
end_time: str
directory: Annotated[pathlib.Path, AfterValidator(_to_absolute_path)]
shape: pathlib.Path | None
classmethod generate(dataset: str | ewatercycle.esmvaltool.schema.Dataset | dict, start_time: str, end_time: str, shape: str, directory: str | None = None, **model_specific_options) AnyForcing

Generate forcings for a model.

The forcing is generated with help of ESMValTool.

Parameters:
  • dataset – Dataset to get forcing data from. When string is given a predefined dataset is looked up in ewatercycle.esmvaltool.datasets.DATASETS. When dict given it is passed to ewatercycle.esmvaltool.models.Dataset constructor.

  • start_time – Start time of forcing in UTC and ISO format string e.g. ‘YYYY-MM-DDTHH:MM:SSZ’.

  • end_time – nd time of forcing in UTC and ISO format string e.g. ‘YYYY-MM-DDTHH:MM:SSZ’.

  • shape – Path to a shape file. Used for spatial selection.

  • directory – Directory in which forcing should be written. If not given will create timestamped directory.

save()

Export forcing data for later use.

classmethod load(directory: str | pathlib.Path)

Load previously generated or imported forcing data.

Parameters:

directory – forcing data directory; must contain ewatercycle_forcing.yaml file

Returns: Forcing object

class ewatercycle.base.forcing.GenericDistributedForcing

Bases: DefaultForcing

Generic forcing data for a distributed model.

pr

Path to NetCDF file with precipitation data.

tas

Path to NetCDF file with air temperature data.

tasmin

Path to NetCDF file with minimum air temperature data.

tasmax

Path to NetCDF file with maximum air temperature data.

Examples

To generate forcing from ERA5 for the Rhine catchment for 2000-2001:

from pathlib import Path
from rich import print
from ewatercycle.base.forcing import GenericDistributedForcing

shape = Path("./src/ewatercycle/testing/data/Rhine/Rhine.shp")
forcing = GenericDistributedForcing.generate(
    dataset='ERA5',
    start_time='2000-01-01T00:00:00Z',
    end_time='2001-01-01T00:00:00Z',
    shape=shape.absolute(),
)
print(forcing)

Gives something like:

GenericDistributedForcing(
    model='generic_distributed',
    start_time='2000-01-01T00:00:00Z',
    end_time='2001-01-01T00:00:00Z',
    directory=PosixPath('/home/verhoes/git/eWaterCycle/ewatercycle/esmvaltool_output/tmp05upitxoewcrep_20230815_154640/work/diagnostic/script'),
    shape=PosixPath('/home/verhoes/git/eWaterCycle/ewatercycle/src/ewatercycle/testing/data/Rhine/Rhine.shp'),
    pr='OBS6_ERA5_reanaly_1_day_pr_2000-2001.nc',
    tas='OBS6_ERA5_reanaly_1_day_tas_2000-2001.nc',
    tasmin='OBS6_ERA5_reanaly_1_day_tasmin_2000-2001.nc',
    tasmax='OBS6_ERA5_reanaly_1_day_tasmax_2000-2001.nc'
)

To generate forcing from CMIP6 for the Rhine catchment for 2000-2001 (make sure ESMValTool is configured correctly):

from pathlib import Path
from rich import print
from ewatercycle.base.forcing import GenericDistributedForcing

shape = Path("./src/ewatercycle/testing/data/Rhine/Rhine.shp")
cmip_dataset = {
    "dataset": "EC-Earth3",
    "project": "CMIP6",
    "grid": "gr",
    "exp": ["historical",],
    "ensemble": "r6i1p1f1",
}

forcing = GenericDistributedForcing.generate(
    dataset=cmip_dataset,
    start_time="2000-01-01T00:00:00Z",
    end_time="2001-01-01T00:00:00Z",
    shape=shape.absolute(),
)
print(forcing)

Gives something like:

GenericDistributedForcing(
    start_time='2000-01-01T00:00:00Z',
    end_time='2001-01-01T00:00:00Z',
    directory=PosixPath('/home/verhoes/git/eWaterCycle/ewatercycle/esmvaltool_output/ewcrep0ibzlds__20230904_082748/work/diagnostic/script'),
    shape=PosixPath('/home/verhoes/git/eWaterCycle/ewatercycle/src/ewatercycle/testing/data/Rhine/Rhine.shp'),
    pr='CMIP6_EC-Earth3_day_historical_r6i1p1f1_pr_gr_2000-2001.nc',
    tas='CMIP6_EC-Earth3_day_historical_r6i1p1f1_tas_gr_2000-2001.nc',
    tasmin='CMIP6_EC-Earth3_day_historical_r6i1p1f1_tasmin_gr_2000-2001.nc',
    tasmax='CMIP6_EC-Earth3_day_historical_r6i1p1f1_tasmax_gr_2000-2001.nc'
)
pr: str
tas: str
tasmin: str
tasmax: str
class ewatercycle.base.forcing.GenericLumpedForcing

Bases: GenericDistributedForcing

Generic forcing data for a lumped model.

pr

Path to NetCDF file with precipitation data.

tas

Path to NetCDF file with air temperature data.

tasmin

Path to NetCDF file with minimum air temperature data.

tasmax

Path to NetCDF file with maximum air temperature data.

Example

To generate forcing from ERA5 for the Rhine catchment for 2000-2001:

from pathlib import Path
from rich import print
from ewatercycle.base.forcing import GenericLumpedForcing

shape = Path("./src/ewatercycle/testing/data/Rhine/Rhine.shp")
forcing = GenericLumpedForcing.generate(
    dataset='ERA5',
    start_time='2000-01-01T00:00:00Z',
    end_time='2001-01-01T00:00:00Z',
    shape=shape.absolute(),
)
print(forcing)

Gives something like:

GenericLumpedForcing(
    model='generic_distributed',
    start_time='2000-01-01T00:00:00Z',
    end_time='2001-01-01T00:00:00Z',
    directory=PosixPath('/home/verhoes/git/eWaterCycle/ewatercycle/esmvaltool_output/ewcrep90hmnvat_20230816_124951/work/diagnostic/script'),
    shape=PosixPath('/home/verhoes/git/eWaterCycle/ewatercycle/src/ewatercycle/testing/data/Rhine/Rhine.shp'),
    pr='OBS6_ERA5_reanaly_1_day_pr_2000-2001.nc',
    tas='OBS6_ERA5_reanaly_1_day_tas_2000-2001.nc',
    tasmin='OBS6_ERA5_reanaly_1_day_tasmin_2000-2001.nc',
    tasmax='OBS6_ERA5_reanaly_1_day_tasmax_2000-2001.nc'
)

To generate forcing from CMIP6 for the Rhine catchment for 2000-2001 (make sure ESMValTool is configured correctly):

from pathlib import Path
from rich import print
from ewatercycle.base.forcing import GenericLumpedForcing

shape = Path("./src/ewatercycle/testing/data/Rhine/Rhine.shp")
cmip_dataset = {
    "dataset": "EC-Earth3",
    "project": "CMIP6",
    "grid": "gr",
    "exp": ["historical",],
    "ensemble": "r6i1p1f1",
}

forcing = GenericLumpedForcing.generate(
    dataset=cmip_dataset,
    start_time="2000-01-01T00:00:00Z",
    end_time="2001-01-01T00:00:00Z",
    shape=shape.absolute(),
)
print(forcing)