signatures

neuralhydrology.evaluation.signatures.baseflow_index(da: xarray.core.dataarray.DataArray, alpha: float = 0.98, warmup: int = 30, n_passes: int = None, datetime_coord: str = None) → Tuple[float, xarray.core.dataarray.DataArray]

Calculate baseflow index.

Ratio of mean baseflow to mean discharge [1]. If da contains NaN values, the baseflow is calculated for each consecutive segment of more than warmup non-NaN values.

Parameters:

• da (DataArray) – Array of flow values.

• alpha (float, optional) – alpha filter parameter.

• warmup (int, optional) – Number of warmup steps.

• n_passes (int, optional) – Number of passes (alternating forward and backward) to perform. Should be an odd number. If None, will use 3 for daily and 9 for hourly data and fail for all other input frequencies.

• datetime_coord (str, optional) – Datetime coordinate in the passed DataArray. Tried to infer automatically if not specified. Used to infer the frequency if n_passes is None.

Returns:

Baseflow index and baseflow array. The baseflow array contains NaNs wherever no baseflow was calculated due to NaNs in da.

Return type:

Tuple[float, DataArray]

Raises:

ValueError – If da has a frequency other than daily or hourly and n_passes is None.

References

[1]

Ladson, T. R., Brown, R., Neal, B., and Nathan, R.: A Standard Approach to Baseflow Separation Using The Lyne and Hollick Filter. Australasian Journal of Water Resources, Taylor & Francis, 2013, 17, 25–34, doi:10.7158/13241583.2013.11465417

neuralhydrology.evaluation.signatures.calculate_all_signatures(da: xarray.core.dataarray.DataArray, prcp: xarray.core.dataarray.DataArray, datetime_coord: str = None) → Dict[str, float]

Calculate all signatures with default values.

Parameters:

• da (DataArray) – Array of discharge values for which the signatures will be calculated.

• prcp (DataArray) – Array of precipitation values.

• datetime_coord (str, optional) – Datetime coordinate in the passed DataArray. Tried to infer automatically if not specified.

Returns:

Dictionary with signature names as keys and signature values as values.

Return type:

Dict[str, float]

neuralhydrology.evaluation.signatures.calculate_signatures(da: xarray.core.dataarray.DataArray, signatures: List[str], datetime_coord: str = None, prcp: xarray.core.dataarray.DataArray = None) → Dict[str, float]

Calculate the specified signatures with default values.

Parameters:

• da (DataArray) – Array of discharge values for which the signatures will be calculated.

• signatures (List[str]) – List of names of the signatures to calculate.

• datetime_coord (str, optional) – Datetime coordinate in the passed DataArray. Tried to infer automatically if not specified.

• prcp (DataArray, optional) – Array of precipitation values. Required for signatures ‘runoff_ratio’ and ‘streamflow_elas’.

Returns:

Dictionary with signature names as keys and signature values as values.

Return type:

Dict[str, float]

Raises:

ValueError – If a passed signature name does not exist.

neuralhydrology.evaluation.signatures.get_available_signatures() → List[str]

Return a list of available signatures.

Returns:

List of all available signatures.

Return type:

List[str]

neuralhydrology.evaluation.signatures.hfd_mean(da: xarray.core.dataarray.DataArray, datetime_coord: str = None) → float

Calculate mean half-flow duration.

Mean half-flow date (step on which the cumulative discharge since October 1st reaches half of the annual discharge) [2].

Parameters:

• da (DataArray) – Array of flow values.

• datetime_coord (str, optional) – Datetime coordinate in the passed DataArray. Tried to infer automatically if not specified.

Returns:

Mean half-flow duration

Return type:

float

References

[2]

Court, A.: Measures of streamflow timing. Journal of Geophysical Research (1896-1977), 1962, 67, 4335–4339, doi:10.1029/JZ067i011p04335

neuralhydrology.evaluation.signatures.high_q_dur(da: xarray.core.dataarray.DataArray, threshold: float = 9.0) → float

Calculate high-flow duration.

Average duration of high-flow events (number of consecutive steps >`threshold` times the median flow) [3], [4] (Table 2).

Parameters:

• da (DataArray) – Array of flow values.

• threshold (float, optional) – High-flow threshold. Values larger than threshold * median are considered high flows.

Returns:

High-flow duration

Return type:

float

References

[3]

Clausen, B. and Biggs, B. J. F.: Flow variables for ecological studies in temperate streams: groupings based on covariance. Journal of Hydrology, 2000, 237, 184–197, doi:10.1016/S0022-1694(00)00306-1

[4]

Westerberg, I. K. and McMillan, H. K.: Uncertainty in hydrological signatures. Hydrology and Earth System Sciences, 2015, 19, 3951–3968, doi:10.5194/hess-19-3951-2015

neuralhydrology.evaluation.signatures.high_q_freq(da: xarray.core.dataarray.DataArray, datetime_coord: str = None, threshold: float = 9.0) → float

Calculate high-flow frequency.

Frequency of high-flow events (>`threshold` times the median flow) [5], [6] (Table 2).

Parameters:

• da (DataArray) – Array of flow values.

• datetime_coord (str, optional) – Datetime coordinate in the passed DataArray. Tried to infer automatically if not specified.

• threshold (float, optional) – High-flow threshold. Values larger than threshold * median are considered high flows.

Returns:

High-flow frequency

Return type:

float

References

[5]

Clausen, B. and Biggs, B. J. F.: Flow variables for ecological studies in temperate streams: groupings based on covariance. Journal of Hydrology, 2000, 237, 184–197, doi:10.1016/S0022-1694(00)00306-1

[6]

Westerberg, I. K. and McMillan, H. K.: Uncertainty in hydrological signatures. Hydrology and Earth System Sciences, 2015, 19, 3951–3968, doi:10.5194/hess-19-3951-2015

neuralhydrology.evaluation.signatures.low_q_dur(da: xarray.core.dataarray.DataArray, threshold: float = 0.2) → float

Calculate low-flow duration.

Average duration of low-flow events (number of consecutive steps <threshold times the median flow) [7], [8] (Table 2).

Parameters:

• da (DataArray) – Array of flow values.

• threshold (float, optional) – Low-flow threshold. Values below threshold * median are considered low flows.

Returns:

Low-flow duration

Return type:

float

References

[7]

Olden, J. D. and Poff, N. L.: Redundancy and the choice of hydrologic indices for characterizing streamflow regimes. River Research and Applications, 2003, 19, 101–121, doi:10.1002/rra.700

[8]

Westerberg, I. K. and McMillan, H. K.: Uncertainty in hydrological signatures. Hydrology and Earth System Sciences, 2015, 19, 3951–3968, doi:10.5194/hess-19-3951-2015

neuralhydrology.evaluation.signatures.low_q_freq(da: xarray.core.dataarray.DataArray, datetime_coord: str = None, threshold: float = 0.2) → float

Calculate Low-flow frequency.

Frequency of low-flow events (<threshold times the median flow) [9], [10] (Table 2).

Parameters:

• da (DataArray) – Array of flow values.

• datetime_coord (str, optional) – Datetime coordinate in the passed DataArray. Tried to infer automatically if not specified.

• threshold (float, optional) – Low-flow threshold. Values below threshold * median are considered low flows.

Returns:

Low-flow frequency

Return type:

float

References

[9]

Olden, J. D. and Poff, N. L.: Redundancy and the choice of hydrologic indices for characterizing streamflow regimes. River Research and Applications, 2003, 19, 101–121, doi:10.1002/rra.700

[10]

Westerberg, I. K. and McMillan, H. K.: Uncertainty in hydrological signatures. Hydrology and Earth System Sciences, 2015, 19, 3951–3968, doi:10.5194/hess-19-3951-2015

neuralhydrology.evaluation.signatures.q5(da: xarray.core.dataarray.DataArray) → float

Calculate 5th flow quantile.

Parameters:

da (DataArray) – Array of flow values.

Returns:

5th flow quantile.

Return type:

float

neuralhydrology.evaluation.signatures.q95(da: xarray.core.dataarray.DataArray) → float

Calculate 95th flow quantile.

Parameters:

da (DataArray) – Array of flow values.

Returns:

95th flow quantile.

Return type:

float

neuralhydrology.evaluation.signatures.q_mean(da: xarray.core.dataarray.DataArray) → float

Calculate mean discharge.

Parameters:

da (DataArray) – Array of flow values.

Returns:

Mean discharge.

Return type:

float

neuralhydrology.evaluation.signatures.runoff_ratio(da: xarray.core.dataarray.DataArray, prcp: xarray.core.dataarray.DataArray, datetime_coord: str = None) → float

Calculate runoff ratio.

Runoff ratio (ratio of mean discharge to mean precipitation) [11] (Eq. 2).

Parameters:

• da (DataArray) – Array of flow values.

• prcp (DataArray) – Array of precipitation values.

• datetime_coord (str, optional) – Datetime coordinate in the passed DataArray. Tried to infer automatically if not specified.

Returns:

Runoff ratio.

Return type:

float

References

[11]

Sawicz, K., Wagener, T., Sivapalan, M., Troch, P. A., and Carrillo, G.: Catchment classification: empirical analysis of hydrologic similarity based on catchment function in the eastern USA. Hydrology and Earth System Sciences, 2011, 15, 2895–2911, doi:10.5194/hess-15-2895-2011

neuralhydrology.evaluation.signatures.slope_fdc(da: xarray.core.dataarray.DataArray, lower_quantile: float = 0.33, upper_quantile: float = 0.66) → float

Calculates flow duration curve slope.

Slope of the flow duration curve (between the log-transformed lower_quantile and upper_quantile) [12] (Eq. 3).

Parameters:

• da (DataArray) – Array of flow values.

• lower_quantile (float, optional) – Lower quantile to use in slope calculation.

• upper_quantile (float, optional) – Upper quantile to use in slope calculation.

Returns:

Slope of the flow duration curve.

Return type:

float

References

[12]

Sawicz, K., Wagener, T., Sivapalan, M., Troch, P. A., and Carrillo, G.: Catchment classification: empirical analysis of hydrologic similarity based on catchment function in the eastern USA. Hydrology and Earth System Sciences, 2011, 15, 2895–2911, doi:10.5194/hess-15-2895-2011

neuralhydrology.evaluation.signatures.stream_elas(da: xarray.core.dataarray.DataArray, prcp: xarray.core.dataarray.DataArray, datetime_coord: str = None) → float

Calculate stream elasticity.

Streamflow precipitation elasticity (sensitivity of streamflow to changes in precipitation at the annual time scale) [13].

Parameters:

• da (DataArray) – Array of flow values.

• prcp (DataArray) – Array of precipitation values.

• datetime_coord (str, optional) – Datetime coordinate in the passed DataArray. Tried to infer automatically if not specified.

Returns:

Stream elasticity.

Return type:

float

References

[13]

Sankarasubramanian, A., Vogel, R. M., and Limbrunner, J. F.: Climate elasticity of streamflow in the United States. Water Resources Research, 2001, 37, 1771–1781, doi:10.1029/2000WR900330

neuralhydrology.evaluation.signatures.zero_q_freq(da: xarray.core.dataarray.DataArray) → float

Calculate zero-flow frequency.

Frequency of steps with zero discharge.

Parameters:

da (DataArray) – Array of flow values.

Returns:

Zero-flow frequency.

Return type:

float