ewatercycle_HBV.forcing

Forcing related functionality for HBV, see eWaterCyle documentation for more detail.

Module Contents

ewatercycle_HBV.forcing.RENAME_CAMELS

ewatercycle_HBV.forcing.REQUIRED_PARAMS = ['pr', 'evspsblpot', 'tas']

class ewatercycle_HBV.forcing.HBVForcing

Bases: ewatercycle.base.forcing.DefaultForcing

Class for HBV forcing data, mainly focused on using CAMELS dataset.

Parameters:

camels_file – .txt file that contains CAMELS forcing from https://hess.copernicus.org/articles/21/5293/2017/
pr – Path to a NetCDF (.nc) file containing precipitation - ensure yourself that these already match start_time & end time
evspsblpot – Path to a NetCDF (.nc) file containing potential evaporation
alpha – float provided in camels dataset but not in the forcing file, instead in the model results.
test_data_bool – False by default, set True if instead of a camels file, a test files is passed for HBV including precipitation and evaporation contains columns: [“year”, “month”, “day”, “pr”, “evspsblpot”] seperated by a space

Examples

From existing forcing data:

from ewatercycle.forcing import sources

forcing = sources.HBVForcing(
    directory='/home/davidhaasnoot/Code/Forcing/',
    start_time='1997-08-01T00:00:00Z',
    end_time='2000-08-31T00:00:00Z',
    camels_file='01620500_lump_cida_forcing_leap.txt',
    alpha = 1.20
)

Or provide forcing yourself as a NetCDF file

forcing = sources.HBVForcing(
    directory='/home/davidhaasnoot/Code/Forcing/',
    start_time='1997-08-01T00:00:00Z',
    end_time='2000-08-31T00:00:00Z',
    pr="precipitation_file.nc"
    evspsblpot="potential_evaporation_file.nc"
)

where precipitation_file & potential_evaporation_file can be the same aslong as they contain a pr & evspsblpot variable

Inherited from base forcing:: shape: Path to a shape file. Used for spatial selection. 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’.

camels_file: str | None = '.txt'

pr: str | None = '.nc'

evspsblpot: str | None = '.nc'

tas: str | None = '.nc'

alpha: float | None = 1.26

test_data_bool: bool = False

camels_txt_defined(): test whether user defined forcing file, used converting text forcing file to netcdf

forcing_nc_defined(): test whether user defined forcing file

from_test_txt() → xarray.Dataset

Load forcing data from a txt file into an xarray dataset.

Information:

Must contain [“year”, “month”, “day”, “pr”,”Q”, “evspsblpot”] in columns

Will convert date to pandas.Timestamp()

pr (precipitation), Q (discharge), evspsblpot (potential evaportaion) - all im mm’s

Returns:

xr.Dataset: Dataset with forcing data.

Return type:

ds

from_camels_txt() → xarray.Dataset

Load forcing data from a txt file into a xarray dataset.

Note

This is only tested with the daymet files. The other two sources (NLDAS/maurer) can pose some issues, for more details see this repo . Instead, use the eWaterCycle CAMELS functionality which utilises OpenDAP .

Requirements:

Must be in the same format as the CAMELS dataset:

3 lines containing: lat, elevation and area.

4th line with headers: ‘Year Mnth Day Hr dayl(s) prcp(mm/day) srad(W/m2) swe(mm) tmax(C) tmin(C) vp(Pa)’

Takes from the 5th line onwards with delimiter.

Will convert date to pandas.Timestamp()

Then convert from pandas to a xarray.

Returns:

xr.Dataset: Dataset with forcing data.

Return type:

ds

from_external_source(): Runs checks on externally provided forcing

crop_ds(ds: xarray.Dataset, name: str)

file_not_found_error()

ewatercycle_HBV.forcing.calc_pet(s_rad, t_min, t_max, doy, alpha, elev, lat) → numpy.ndarray

Calculates Potential Evaporation using Priestly–Taylor PET estimate, callibrated with longterm P-T trends from the camels data set (alpha).

Parameters:

s_rad – np.ndarray net radiation estimate in W/m^2. Function converts this to J/m^2/d
t_min – np.ndarray daily minimum temperature (degree C)
t_max – np.ndarray daily maximum temperature (degree C)
doy – np.ndarray day of year: use xt.DataArray.dt.dayofyear - used to approximate daylight amount
alpha – float factor callibrated from longterm P-T trend compensating for lack of other data.
elev – float elevation in m as provided by camels
lat – float latitude in degree

Assumptions:: G = 0 in a day: no loss to ground.

Returns:

np.ndarray: Array containing PET estimates in mm/day

Return type:

pet

Reference:

based on code from:: kratzert et al. 2022 NeuralHydrology — A Python library for Deep Learning research in hydrology, Frederik Kratzert and Martin Gauch and Grey Nearing and Daniel Klotz https://doi.org/10.21105/joss.04050

Who base on allen et al. (1998) ‘FOA 56’ & Newman et al (2015)