Standard Suite (v1) Metrics -- Usage Examples

This notebook will demonstrate how to call the specific functions defined in the Standard Suite (v1) Metrics notebook, using a small demonstration dataset.

import pandas as pd
import numpy as np

Sample Data¶

sampleData = pd.read_csv(r"../streamflow/NWM_Benchmark_SampleData.csv", index_col='date').dropna()
print(len(sampleData.index), " Records")
sampleData.head()

Import Metric Functions¶

The functions are defined in an Standard Suite (v1) Metrics.
They are imported for use here by running that notebook from within the following cell:

%run ../../Metrics_StdSuite_v1.ipynb
# This brings functions defined in external notebook into this notebook's namespace.

The functions are now available here, to run against our sample data. These are called with two arguments: an array/series of observed values and an array/series of modeled/simulated values.

A couple of examples:

# Mean Square Error
MSE(obs=sampleData['obs'], sim=sampleData['nwm'])

# Kling-Gupta efficiency
KGE(obs=sampleData['obs'], sim=sampleData['nwm'])

Create Composite Benchmark¶

It is useful to combine several of these metrics into a single benchmark routine, which returns a pandas Series of the assembled metrics.

This example computes those metrics which might apply to the streamflow variable.

def compute_benchmark(df):
    obs = df['obs']
    sim = df['nwm']
    return pd.Series(
        data={
            'NSE': NSE(obs, sim),
            'KGE': KGE(obs, sim),
            'logNSE': logNSE(obs, sim),
            'pbias': pbias(obs, sim),
            'rSD': rSD(obs, sim),
            'pearson': pearson_r(obs, sim),
            'spearman': spearman_r(obs, sim), 
            'pBiasFMS': pBiasFMS(obs, sim),
            'pBiasFLV': pBiasFLV(obs, sim),
            'pBiasFHV': pBiasFHV(obs, sim)
        },
        name=df['site_no'].iloc[0], # special case -- 'site_no' column
        dtype='float64'
    )

compute_benchmark(sampleData)

Streamflow and FDC plots¶

In the case of streamflow, the NWM standard suite offers a way to plot the Flow Duration Curve when calculating the pBias metrics per Yilmaz et al. This mechanism uses matplotlib to implement the figures.

Some examples:

import matplotlib.pyplot as plt
fig, ax = plt.subplots(1, 1, figsize=(6, 3), dpi=150)
ax = FDCplot(sampleData['obs'], sampleData['nwm'], ax, segment='mid')
ax.set_title("Gage 1104200 - Mid")
plt.show()

# Same fig, but with "segment='lo'"
fig, ax = plt.subplots(1, 1, figsize=(6, 3), dpi=150)
ax = FDCplot(sampleData['obs'], sampleData['nwm'], ax, segment='lo')
ax.set_title("Gage 1104200 - Low")
plt.show()

# Same fig, but with "segment='hi'"
fig, ax = plt.subplots(1, 1, figsize=(6, 3), dpi=150)
ax = FDCplot(sampleData['obs'], sampleData['nwm'], ax, segment='hi')
ax.set_title("Gage 1104200 - High")
plt.show()

The default behavior is to plot the Y axis log-scale, and to leave units off of the flow rate. If you would like to manipulate these parameters, you may adjust the ax after calling FDCplot() (see example, next cell). In general, any of the matplotlib parameters can be adjusted after FDCplot() in order to customize the figure.

fig, ax = plt.subplots(1, 1, figsize=(6, 3), dpi=150)
ax = FDCplot(sampleData['obs'], sampleData['nwm'], ax, segment='mid')
ax.set_yscale('linear')
ax.set_ylabel("Flow Rate $m^3 / s$") # << labels can contain LaTex-style math between $ chars
plt.show()