ewatercycle_HBV.forcing ======================= .. py:module:: ewatercycle_HBV.forcing .. autoapi-nested-parse:: Forcing related functionality for HBV, see `eWaterCyle documentation `_ for more detail. Module Contents --------------- .. py:data:: RENAME_CAMELS .. py:data:: REQUIRED_PARAMS :value: ['pr', 'evspsblpot', 'tas'] .. py:class:: HBVForcing Bases: :py:obj:`ewatercycle.base.forcing.DefaultForcing` Class for HBV forcing data, mainly focused on using CAMELS dataset. :param camels_file: .txt file that contains CAMELS forcing from https://hess.copernicus.org/articles/21/5293/2017/ :param pr: Path to a NetCDF (.nc) file containing precipitation - ensure yourself that these already match start_time & end time :param evspsblpot: Path to a NetCDF (.nc) file containing potential evaporation :param alpha: float provided in camels dataset but not in the forcing file, instead in the model results. :param 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 .. rubric:: Examples From existing forcing data: .. code-block:: python 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 .. code-block:: python 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 :py:const:`precipitation_file` & :py:const:`potential_evaporation_file` can be the same aslong as they contain a :py:const:`pr` & :py:const:`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'. .. py:attribute:: camels_file :type: Optional[str] :value: '.txt' .. py:attribute:: pr :type: Optional[str] :value: '.nc' .. py:attribute:: evspsblpot :type: Optional[str] :value: '.nc' .. py:attribute:: tas :type: Optional[str] :value: '.nc' .. py:attribute:: alpha :type: Optional[float] :value: 1.26 .. py:attribute:: test_data_bool :type: bool :value: False .. py:method:: camels_txt_defined() test whether user defined forcing file, used converting text forcing file to netcdf .. py:method:: forcing_nc_defined() test whether user defined forcing file .. py:method:: 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. :rtype: ds .. py:method:: 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. :rtype: ds .. py:method:: from_external_source() Runs checks on externally provided forcing .. py:method:: crop_ds(ds: xarray.Dataset, name: str) .. py:method:: file_not_found_error() .. py:function:: 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). :param s_rad: np.ndarray net radiation estimate in W/m^2. Function converts this to J/m^2/d :param t_min: np.ndarray daily minimum temperature (degree C) :param t_max: np.ndarray daily maximum temperature (degree C) :param doy: np.ndarray day of year: use `xt.DataArray.dt.dayofyear` - used to approximate daylight amount :param alpha: float factor callibrated from longterm P-T trend compensating for lack of other data. :param elev: float elevation in m as provided by camels :param 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 :rtype: 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) `_