hydrosignatures.hydrosignatures#

Function for computing hydrologic signature.

Module Contents#

class hydrosignatures.hydrosignatures.HydroSignatures#

Hydrological signatures.

Parameters:
  • q_mmpt (pandas.Series) – Discharge in mm per unit time (the same timescale as precipitation).

  • p_mmpt (pandas.Series) – Precipitation in mm per unit time (the same timescale as discharge).

  • si_method (str, optional) – Seasonality index method. Either walsh or markham. Default is walsh.

  • fdc_slope_bins (tuple of int, optional) – The percentage bins between 1-100 to compute the slope of FDC within it, defaults to (33, 67).

  • bfi_alpha (float, optional) – Alpha parameter for baseflow separation filter using Lyne and Hollick method. Default is 0.925.

property signature_names: dict[str, str]#

Return a dictionary with the hydrological signatures.

property values: SignaturesFloat#

Return a dictionary with the hydrological signatures.

bfi()#

Compute Baseflow Index.

diff(other)#

Compute absolute difference between two hydrological signatures.

fdc()#

Compute exceedance probability (for flow duration curve).

fdc_slope()#

Compute FDC slopes between a list of lower and upper percentiles.

isclose(other)#

Check if the signatures are close between with a tolerance of 1e-3.

mean_annual_flood()#

Compute mean annual flood.

mean_monthly()#

Compute mean monthly flow (for regime curve).

runoff_ratio()#

Compute total runoff ratio.

seasonality_index()#

Compute seasonality index.

streamflow_elasticity()#

Compute streamflow elasticity.

to_dict()#

Return a dictionary with the hydrological signatures.

to_json()#

Return a JSON string with the hydrological signatures.

hydrosignatures.hydrosignatures.aridity_index(pet: pandas.Series, prcp: pandas.Series) numpy.float64#
hydrosignatures.hydrosignatures.aridity_index(pet: pandas.DataFrame, prcp: pandas.DataFrame) pandas.Series
hydrosignatures.hydrosignatures.aridity_index(pet: xarray.DataArray, prcp: xarray.DataArray) xarray.DataArray

Compute (Budyko) aridity index (PET/Prcp).

Parameters:
Returns:

float or pandas.Series or xarray.DataArray – The aridity index.

hydrosignatures.hydrosignatures.baseflow(discharge, alpha=0.925, n_passes=3, pad_width=10)#

Extract baseflow using the Lyne and Hollick filter (Ladson et al., 2013).

Parameters:
  • discharge (numpy.ndarray or pandas.DataFrame or pandas.Series or xarray.DataArray) – Discharge time series that must not have any missing values. It can also be a 2D array where each row is a time series.

  • n_passes (int, optional) – Number of filter passes, defaults to 3. It must be an odd number greater than 3.

  • alpha (float, optional) – Filter parameter that must be between 0 and 1, defaults to 0.925.

  • pad_width (int, optional) – Padding width for extending the data from both ends to address the warm up issue.

Returns:

numpy.ndarray or pandas.DataFrame or pandas.Series or xarray.DataArray – Same discharge input array-like but values replaced with computed baseflow values.

Return type:

ArrayVar

hydrosignatures.hydrosignatures.baseflow_index(discharge, alpha=0.925, n_passes=3, pad_width=10)#

Compute the baseflow index using the Lyne and Hollick filter (Ladson et al., 2013).

Parameters:
  • discharge (numpy.ndarray or pandas.DataFrame or pandas.Series or xarray.DataArray) – Discharge time series that must not have any missing values. It can also be a 2D array where each row is a time series.

  • n_passes (int, optional) – Number of filter passes, defaults to 3. It must be an odd number greater than 3.

  • alpha (float, optional) – Filter parameter that must be between 0 and 1, defaults to 0.925.

  • pad_width (int, optional) – Padding width for extending the data from both ends to address the warm up issue.

Returns:

numpy.float64 – The baseflow index.

Return type:

numpy.float64

hydrosignatures.hydrosignatures.exceedance(daily, threshold=0.001)#

Compute exceedance probability from daily data.

Parameters:
  • daily (pandas.Series or pandas.DataFrame) – The data to be processed

  • threshold (float, optional) – The threshold to compute exceedance probability, defaults to 1e-3.

Returns:

pandas.Series or pandas.DataFrame – Exceedance probability.

Return type:

pandas.DataFrame

hydrosignatures.hydrosignatures.extract_extrema(ts, var_name, n_pts)#

Get local extrema in a time series.

Parameters:
  • ts (pandas.Series) – Variable time series.

  • var_name (str) – Variable name.

  • n_pts (int) – Number of points to consider for detecting local extrema on both sides of each point.

Returns:

pandas.DataFrame – A dataframe with three columns: var_name, peak (bool) and trough (bool).

Return type:

pandas.DataFrame

hydrosignatures.hydrosignatures.flashiness_index(daily)#

Compute flashiness index from daily data following Baker et al. (2004).

Parameters:

daily (pandas.Series or pandas.DataFrame or numpy.ndarray or xarray.DataArray) – The data to be processed

Returns:

numpy.ndarray – Flashiness index.

Return type:

FloatArray

References

Baker, D.B., Richards, R.P., Loftus, T.T. and Kramer, J.W., 2004. A new flashiness index: Characteristics and applications to midwestern rivers and streams 1. JAWRA Journal of the American Water Resources Association, 40(2), pp.503-522.

hydrosignatures.hydrosignatures.flood_moments(streamflow)#

Compute flood moments (MAF, CV, CS) from streamflow.

Parameters:

streamflow (pandas.DataFrame) – The streamflow data to be processed

Returns:

pandas.DataFrame – Flood moments; mean annual flood (MAF), coefficient of variation (CV), and coefficient of skewness (CS).

Return type:

pandas.DataFrame

hydrosignatures.hydrosignatures.flow_duration_curve_slope(discharge, bins, log)#

Compute FDC slopes between the given lower and upper percentiles.

Parameters:
Returns:

numpy.ndarray – The slopes between the given percentiles.

Return type:

FloatArray

hydrosignatures.hydrosignatures.mean_monthly(daily, index_abbr=False, cms=False)#

Compute mean monthly summary from daily data.

Parameters:
  • daily (pandas.Series or pandas.DataFrame) – The data to be processed

  • index_abbr (bool, optional) – Whether to use abbreviated month names as index instead of numbers, defaults to False.

  • cms (bool, optional) – Whether the input data is in cubic meters per second (cms), defaults to False. If True, the mean monthly summary will be computed by taking the mean of the daily data, otherwise the sum of the daily data will be used.

Returns:

pandas.Series or pandas.DataFrame – Mean monthly summary.

Return type:

DF

hydrosignatures.hydrosignatures.rolling_mean_monthly(daily)#

Compute rolling mean monthly.

hydrosignatures.hydrosignatures.seasonality_index_markham(data)#

Compute seasonality index based on Markham, 1970.

hydrosignatures.hydrosignatures.seasonality_index_walsh(data)#

Compute seasonality index based on Walsh and Lawler, 1981 method.