Utils

Documentation of all functions defined within the rrmpg.utils module.

Plot utils

rrmpg.utils.plot_utils.plot_qsim_range(qsim, x_vals=None, qobs=None)

Plot the range of multiple simulations and their mean.

This function plots the quantiles of multiple simulations as a filled area and the mean as a line. The (0.05, 0.95) and the (0.25, 0.75) quantile are plotted as different colored areas and the mean as a solid line. If observations are also passed, they are plotted as well as a solid line.

Parameters

• qsim – 2D array of simulations. Shape must be (num_timesteps, num_sims)

• x_vals – (optional) 1D array, that will be used as x-axes values. (e.g. date)

• qobs – (optional) 1D arary of oversations.

Returns

A handle to the matplotlib figure.

Raises

ValueError – For incorrect inputs.

Metrics

rrmpg.utils.metrics.calc_mse(obs, sim)

Calculate the mean squared error.

Parameters

• obs – Array of the observed values

• sim – Array of the simulated values

Returns

The MSE value for the simulation, compared to the observation.

Raises

• ValueError – If the arrays are not of equal size or have non-numeric values.

• TypeError – If the arrays is not a supported datatype.

rrmpg.utils.metrics.calc_rmse(obs, sim)

Calculate the root mean squared error.

Parameters

• obs – Array of the observed values

• sim – Array of the simulated values

Returns

The RMSE value for the simulation, compared to the observation.

Raises

• ValueError – If the arrays are not of equal size or have non-numeric values.

• TypeError – If the arrays is not a supported datatype.

rrmpg.utils.metrics.calc_nse(obs, sim)

Calculate the Nash-Sutcliffe model efficiency coefficient.

Original Publication: Nash, J. Eamonn, and Jonh V. Sutcliffe. “River flow forecasting through conceptual models part I—A discussion of principles.” Journal of hydrology 10.3 (1970): 282-290.

Parameters

• obs – Array of the observed values

• sim – Array of the simulated values

Returns

The NSE value for the simulation, compared to the observation.

Raises

• ValueError – If the arrays are not of equal size or have non-numeric values.

• TypeError – If the arrays is not a supported datatype.

• RuntimeError – If all values in qobs are equal. The NSE is not defined for this cases.

rrmpg.utils.metrics.calc_kge(obs, sim)

Calculate the Kling-Gupta-Efficiency.

Calculate the original KGE value following [1].

Parameters

• obs – Array of the observed values

• sim – Array of the simulated values

Returns

The KGE value for the simulation, compared to the observation.

Raises

• ValueError – If the arrays are not of equal size or have non-numeric values.

• TypeError – If the arrays is not a supported datatype.

• RuntimeError – If the mean or the standard deviation of the observations equal 0.

[1] Gupta, H. V., Kling, H., Yilmaz, K. K., & Martinez, G. F. (2009). Decomposition of the mean squared error and NSE performance criteria: Implications for improving hydrological modelling. Journal of Hydrology, 377(1-2), 80-91.

rrmpg.utils.metrics.calc_alpha_nse(obs, sim)

Calculate the alpha decomposition of the NSE.

Calculate the alpha decomposition of the NSE following [1].

Parameters

• obs – Array of the observed values

• sim – Array of the simulated values

Returns

The alpha decomposition of the NSE of the simulation compared to the observation.

Raises

• ValueError – If the arrays are not of equal size or have non-numeric values.

• TypeError – If the arrays is not a supported datatype.

• RuntimeError – If the standard deviation of the observations equal 0.

[1] Gupta, H. V., Kling, H., Yilmaz, K. K., & Martinez, G. F. (2009). Decomposition of the mean squared error and NSE performance criteria: Implications for improving hydrological modelling. Journal of Hydrology, 377(1-2), 80-91.

rrmpg.utils.metrics.calc_beta_nse(obs, sim)

Calculate the beta decomposition of the NSE.

Calculate the beta decomposition of the NSE following [1].

Parameters

• obs – Array of the observed values

• sim – Array of the simulated values

Returns

The beta decomposition of the NSE of the simulation compared to the observation.

Raises

• ValueError – If the arrays are not of equal size or have non-numeric values.

• TypeError – If the arrays is not a supported datatype.

• RuntimeError – If the mean or the standard deviation of the observations equal 0.

[1] Gupta, H. V., Kling, H., Yilmaz, K. K., & Martinez, G. F. (2009). Decomposition of the mean squared error and NSE performance criteria: Implications for improving hydrological modelling. Journal of Hydrology, 377(1-2), 80-91.

rrmpg.utils.metrics.calc_r(obs, sim)

Calculate the pearson r coefficient.

Interface to the scipy implementation of the pearson r coeffienct.

Parameters

• obs – Array of the observed values

• sim – Array of the simulated values

Returns

The pearson r coefficient of the simulation compared to the observation.

Array Checks

rrmpg.utils.array_checks.check_for_negatives(arr)

Check if array contains negative number.

Numba optimized function to check if a numpy array containes a negative value. Returns, whenever the first negative function is found.

Parameters

arr – Numpy array

Returns

True, if the array contains at least on negative number and False, if the array contains no negative number.

rrmpg.utils.array_checks.validate_array_input(arr, dtype, arr_name)

Check if array has correct type and is numerical.

This function checks if the input is either a list, numpy.ndarray or pandas.Series of numerical values, converts it to a numpy.ndarray and throws an error in case of incorrect data.

Parameters

• arr – Array of data

• dtype – One of numpy’s dtypes

• arr_name – String specifing the variable name, so that the error message can be adapted correctly.

Returns

A as numpy.ndarray converted array of values with a datatype specified in the input argument.

Raises

• ValueError – In case non-numerical data is passed

• TypeError – If the error is neither a list, a numpy.ndarray nor a pandas.Series