Skip to content

Hydrology-IFH/diag-eff

Repository files navigation

diag-eff

Info: diag-eff needs Python >= 3.6!

Build Status Documentation Status codecov PyPI version shields.io GPLv3 license Binder Maintenance DOI

How to cite

In case you use diag-eff in other software or scientific publications, please reference this package. It is published and has a DOI. It can be cited as:

Schwemmle, R., Demand, D., and Weiler, M.: Technical note: Diagnostic
efficiency – specific evaluation of model performance, Hydrol. Earth Syst.
Sci., 25, 2187–2198, https://doi.org/10.5194/hess-25-2187-2021, 2021.

Full Documentation

The full documentation can be found at: https://diag-eff.readthedocs.io

License

This software can be distributed freely under the GPL v3 license. Please read the LICENSE for further information.

© 2021, Robin Schwemmle ([email protected])

Description

diag-eff is an open-source toolbox written in Python for specific evaluation of model performance. The toolbox provides functions to calculate the Diagnostic Efficiency metric and and functions to visualize contribution of metric terms by diagnostic polar plots. Additionally, functions to calculate KGE and NSE are available.

Installation

PyPI:

pip install diag-eff

GIT:

git clone https://github.com/Hydrology-IFH/diag-eff.git
cd diag-eff
pip install -r requirements.txt
pip install -e .

Usage

from pathlib import Path  # OS-independent path handling
from de import de
from de import util

# set path to example data
path_cam = Path('./examples/13331500_94_model_output.txt')

# import example data as dataframe
df_cam = util.import_camels_obs_sim(path_cam)

# make arrays
obs_arr = df_cam['Qobs'].values
sim_arr = df_cam['Qsim'].values

# calculate diagnostic efficiency
eff_de = de.calc_de(obs_arr, sim_arr)

# diagnostic polar plot
de.diag_polar_plot(obs_arr, sim_arr)

Usage in R

In order to run diag-eff in R, reticulate can be used as an interface to Python.

Non-interactive mode:

install.packages("reticulate")
library(reticulate)

# pip installation
py_install("numpy")
py_install("pandas")
py_install("scipy")
py_install("matplotlib")
py_install("seaborn")
py_install("diag-eff")

# import Python modules
np <- import("numpy")
pd <- import("pandas")
sp <- import("scipy")
mpl <- import("matplotlib")
plt <- import("matplotlib.pyplot")
sns <- import("seaborn")
de <- import("de")

# set path to example data
path_cam <- file.path('./examples/13331500_94_model_output.txt')

# import example data as dataframe
df_cam <- import_camels_obs_sim(path_cam)

# calculate diagnostic efficiency
eff_de <- calc_de(df_cam$Qobs, df_cam$Qsim)

# diagnostic polar plot
fig <- diag_polar_plot(df_cam$Qobs, df_cam$Qsim)
# currently figures cannot be displayed interactively in a R environment
fig$savefig('diagnostic_polar_plot.png')

Interactive mode using a Python interpreter in R:

install.packages("reticulate")
library(reticulate)

# pip installation
py_install("numpy")
py_install("pandas")
py_install("scipy")
py_install("matplotlib")
py_install("seaborn")
py_install("tk")
py_install("diag-eff")

# start Python interpreter in R
repl_python()
# copy+paste the lines below to the interpreter
from pathlib import Path  # OS-independent path handling
from de import de
from de import util
import matplotlib
matplotlib.use('TkAgg')
import matplotlib.pyplot as plt

# set path to example data
path = Path('./examples/13331500_94_model_output.txt')

# import example data as dataframe
df_cam = util.import_camels_obs_sim(path)

# make arrays
obs_arr = df_cam['Qobs'].values
sim_arr = df_cam['Qsim'].values

plt.plot(obs_arr)
plt.show()

# calculate diagnostic efficiency
eff_de = de.calc_de(obs_arr, sim_arr)

# diagnostic polar plot
de.diag_polar_plot(obs_arr, sim_arr)
plt.show()

# quit the interpreter
exit