easy_vic_build.tools.calibrate_func.evaluate_metrics

Evaluation metrics for continuous, categorical, and signature analysis.

The module provides:

Functions

create_test_data([seed])

Create synthetic spatiotemporal fields for metric testing.

create_test_data2()

Create synthetic dataset pair with time-varying noise.

Classes

CategoricalEvaluationMetric(sim, obs)

Event-based verification metrics from a contingency table.

EvaluationMetric(sim, obs)

Continuous-value evaluation metrics.

SignatureEvaluationMetric(sim, obs)

Hydrologic signature metrics based on discharge series.
class easy_vic_build.tools.calibrate_func.evaluate_metrics.EvaluationMetric(sim, obs)[source]

Bases: object

Continuous-value evaluation metrics.

Initialize the metric class with simulated and observed values.

Parameters:

  • sim (array-like) – Simulated values.

  • obs (array-like) – Observed values.

__init__(sim, obs)[source]

Initialize the metric class with simulated and observed values.

Parameters:

  • sim (array-like) – Simulated values.

  • obs (array-like) – Observed values.

MSE()[source]

Computes the Mean Squared Error (MSE) between the simulated and observed values.

Returns:

The calculated MSE.

Return type:

float

RMSE()[source]

Computes the Root Mean Squared Error (RMSE) between the simulated and observed values.

Returns:

The calculated RMSE.

Return type:

float

RRMSE()[source]

Computes the Relative Root Mean Squared Error (RRMSE) between the simulated and observed values.

Returns:

The calculated RRMSE.

Return type:

float

R(confidence: float = 0.95)[source]

Computes the Pearson correlation coefficient (R) and its significance.

Parameters:

confidence (float, optional) – The confidence level to determine the significance, by default 0.95.

Returns:

A tuple containing the correlation coefficient (r), p-value, and significance: - r : float

The Pearson correlation coefficient.

  • p_valuefloat

    The p-value corresponding to the correlation coefficient.

  • significanceint

    A value indicating the significance of the correlation: 1 for positive correlation, -1 for negative, and 0 for no significant correlation.

Return type:

tuple

R2()[source]

Computes the R-squared (R2) value of the linear fit between the simulated and observed values.

Returns:

The calculated R2 value.

Return type:

float

NSE()[source]

Computes the Nash-Sutcliffe Efficiency (NSE) coefficient.

The NSE measures how well the simulated values match the observed values, with higher values indicating better performance.

Returns:

The calculated NSE value.

Return type:

float

Bias()[source]

Computes the bias between the simulated and observed values.

The bias is the mean difference between the observed and simulated values.

Returns:

The calculated bias.

Return type:

float

PBias()[source]

Computes the Percent Bias (PBias) between the simulated and observed values.

Returns:

The calculated PBias.

Return type:

float

KGE(components=False)[source]

Computes the Kling-Gupta Efficiency (KGE) metric between the simulated and observed values.

The KGE metric is based on the correlation coefficient (r), the ratio of means (beta), and the ratio of standard deviations (gamma).

Returns:

The calculated KGE value.

Return type:

float

KGE_m(components=False)[source]

Computes the modified Kling-Gupta Efficiency (KGE-m) metric between the simulated and observed values.

The KGE-m metric is similar to KGE but adjusts the gamma term to account for the relative standard deviations of the observed and simulated values.

Returns:

The calculated KGE-m value.

Return type:

float

ESS(lats=None, n_modes=None, remove_mean=True, mask=None)[source]

Compute EOF-based error similarity score for spatiotemporal fields.

Parameters:

  • lats (array-like, optional) – Latitude values used to build cosine-latitude weights.

  • n_modes (int, optional) – Number of EOF modes used in the score.

  • remove_mean (bool, optional) – Whether to remove the temporal mean before EOF decomposition.

  • mask (ndarray of bool, optional) – Spatial mask of shape (nlat, nlon). Masked cells are excluded.

Returns:

Score series with length ntime.

Return type:

numpy.ndarray

spatialPCC(mask=None)[source]

Compute spatial Pearson correlation for each time step.

Parameters:

mask (ndarray of bool, optional) – Spatial mask of shape (nlat, nlon). True cells are ignored.

Returns:

One correlation value per time step.

Return type:

numpy.ndarray

class easy_vic_build.tools.calibrate_func.evaluate_metrics.CategoricalEvaluationMetric(sim, obs)[source]

Bases: object

Event-based verification metrics from a contingency table.

Initialize the metric class with simulated and observed values.

Parameters:

  • sim (array-like) – Simulated values.

  • obs (array-like) – Observed values.

__init__(sim, obs)[source]

Initialize the metric class with simulated and observed values.

Parameters:

  • sim (array-like) – Simulated values.

  • obs (array-like) – Observed values.

binarize(threshold=0.0)[source]

Convert continuous values to binary events based on threshold Values > threshold are considered ‘event occurred’ (1), else ‘no event’ (0).

Parameters:

threshold (float) – Threshold for event occurrence.

POD()[source]

POD (Probability of Detection)

FAR()[source]

FAR (False Alarm Ratio)

CSI()[source]

CSI (Critical Success Index)

HSS()[source]

HSS (Heidke Skill Score)

ETS()[source]

ETS (Equitable Threat Score)

class easy_vic_build.tools.calibrate_func.evaluate_metrics.SignatureEvaluationMetric(sim, obs)[source]

Bases: object

Hydrologic signature metrics based on discharge series.

Initialize the metric class with simulated and observed values.

Parameters:

  • sim (array-like) – Simulated values.

  • obs (array-like) – Observed values.

__init__(sim, obs)[source]

Initialize the metric class with simulated and observed values.

Parameters:

  • sim (array-like) – Simulated values.

  • obs (array-like) – Observed values.

BiasRR(precip)[source]

Compute runoff-ratio bias in percent.

Parameters:

precip (array-like) – Precipitation series aligned with sim and obs.

Returns:

Relative runoff-ratio bias in percent.

Return type:

float

BiasFHV(q_high=0.02)[source]

High-flow volume bias (FHV), computed from the upper segment of the flow duration curve.

BiasFLV(q_low=0.7, eps=1e-06)[source]

Low-flow volume bias (FLV), computed in log space.

Parameters:

  • q_low (float, optional (default=0.7)) – Quantile threshold defining low flows on the FDC (e.g., q_low=0.7 corresponds to the lowest 30% flows).

  • eps (float, optional) – Small constant added to avoid log(0).

Returns:

Relative bias of low flows in log space.

Return type:

float

BiasFMS(p1=0.2, p2=0.7, eps=1e-06)[source]

Flow duration curve mid-segment slope bias (BiasFMS).

Parameters:

  • p1 (float) – Exceedance probability bounds defining the mid-segment of the FDC (default: 0.2-0.7).

  • p2 (float) – Exceedance probability bounds defining the mid-segment of the FDC (default: 0.2-0.7).

  • eps (float) – Small constant to avoid log(0).

Returns:

Relative bias of the FDC mid-segment slope.

Return type:

float

BiasFMM()[source]

Flow duration curve median magnitude bias (BiasFMM).

Defined as:

(median(FDC_sim) - median(FDC_obs)) / median(FDC_obs)

get_fdc(plot_bool=False)[source]

Compute FDC curves for observed and simulated series.

Returns:

  • fdc (dict) – Dictionary containing FDC data: {

    ’obs’: {‘p’: p_obs, ‘q’: q_obs}, ‘sim’: {‘p’: p_sim, ‘q’: q_sim}

    }

  • example – plt.plot(r[“obs”][“p”], r[“obs”][“q”], “r-”, label=”Observed”) plt.plot(r[“sim”][“p”], r[“sim”][“q”], “b-”, label=”sim”) xs = [0.02, 0.2, 0.7] for x in xs:

    plt.axvline(x, color=”gray”, linestyle=”–”, linewidth=1.0, alpha=0.7) plt.text(

    x+0.01, plt.ylim()[1], f”{x:.2f}”, rotation=90, va=”top”, ha=”left”, fontsize=9, color=”gray”, weight=”bold”,

    )

    plt.yscale(“log”) plt.legend() plt.xlim(0, 1) plt.ylabel(“Discharge (m$^3$/s)”) plt.xlabel(“Flow exceedance probability [-]”) plt.show(block=True)

easy_vic_build.tools.calibrate_func.evaluate_metrics.create_test_data(seed=42)[source]

Create synthetic spatiotemporal fields for metric testing.

Parameters:

seed (int, optional) – Random seed.

Returns:

(reference, perturbed) with shape (T, H, W).

Return type:

tuple of numpy.ndarray

easy_vic_build.tools.calibrate_func.evaluate_metrics.create_test_data2()[source]

Create synthetic dataset pair with time-varying noise.

Returns:

(obs_data, sim_data) with shape (n_time, n_lat, n_lon).

Return type:

tuple of numpy.ndarray