diff --git a/dev/Dam/index.html b/dev/Dam/index.html index 57642ba..7648b8c 100644 --- a/dev/Dam/index.html +++ b/dev/Dam/index.html @@ -1,3 +1,3 @@ Dam (Storage Level) · Streamfall Documentation
Edit on GitHub

Dam (Storage Level)

Streamfall.run_node! — Method
run_node!(node::DamNode, climate::Climate, timestep::Int; 
-          inflow=nothing, extraction=nothing, exchange=nothing)

Run a specific node for a specified time step.

Arguments

  • node::DamNode :
  • climate::Climate :
  • timestep::Int : current time step
  • inflow::DataFrame : Time series of inflows from any upstream node.
  • extraction::DataFrame : Time series of water orders (expects column of _releases)
  • exchange::DataFrame : Time series of groundwater flux
source
Streamfall.run_node! — Method

Calculate outflow for the dam node for a single time step.

Parameters

  • node : DamNode
  • rain : rainfall in mm
  • et : evapotranspiration data in mm
  • irrig_ext : irrigation extractions
  • extractions : extraction data in ML
  • gw_flux : groundwater interaction

Returns

  • outflow from dam
source
Streamfall.update_volume — Method
update_volume(volume, node_inflow, gamma, rain, evap, area, extractions, discharge, max_store)::Float64

Update dam volume for timestep.

Arguments

  • volume : current water volume in ML
  • node_inflow : inflow from previous node in ML
  • gamma : groundwater exchange (positive is gain from gw flow, negative is loss to infiltration)
  • rain : rainfall input
  • evap : evaporation loss
  • infiltration : infiltration loss
  • area : dam surface area in square kilometers
  • extractions : water extraction from dam in ML
  • discharge : discharge from dam in ML
  • max_store : maximum dam storage in ML

Returns

volume of water stored in dam

source
+ inflow=nothing, extraction=nothing, exchange=nothing)

Run a specific node for a specified time step.

Arguments

source
Streamfall.run_node! — Method

Calculate outflow for the dam node for a single time step.

Parameters

  • node : DamNode
  • rain : rainfall in mm
  • et : evapotranspiration data in mm
  • irrig_ext : irrigation extractions
  • extractions : extraction data in ML
  • gw_flux : groundwater interaction

Returns

  • outflow from dam
source
Streamfall.update_params! — Method
update_params!(node::DamNode, storage_coef::Float64)::Nothing
source
Streamfall.update_volume — Method
update_volume(volume, node_inflow, gamma, rain, evap, area, extractions, discharge, max_store)::Float64

Update dam volume for timestep.

Arguments

  • volume : current water volume in ML
  • node_inflow : inflow from previous node in ML
  • gamma : groundwater exchange (positive is gain from gw flow, negative is loss to infiltration)
  • rain : rainfall input
  • evap : evaporation loss
  • infiltration : infiltration loss
  • area : dam surface area in square kilometers
  • extractions : water extraction from dam in ML
  • discharge : discharge from dam in ML
  • max_store : maximum dam storage in ML

Returns

volume of water stored in dam

source
Streamfall.DamNode — Method
DamNode(name::String, spec::Dict)

Create DamNode from a given specification.

source
diff --git a/dev/EnsembleNode/index.html b/dev/EnsembleNode/index.html index cd897a5..75c6251 100644 --- a/dev/EnsembleNode/index.html +++ b/dev/EnsembleNode/index.html @@ -1,2 +1,2 @@ -GR4J · Streamfall Documentation
Edit on GitHub
+GR4J · Streamfall Documentation
Edit on GitHub
diff --git a/dev/GR4J/index.html b/dev/GR4J/index.html index 8d0d8b1..f4f5802 100644 --- a/dev/GR4J/index.html +++ b/dev/GR4J/index.html @@ -1,5 +1,5 @@ -GR4J · Streamfall Documentation
Edit on GitHub

GR4J

Streamfall.reset! — Method
reset!(node::GR4JNode)::Nothing

Reset node. Clears all states back to their initial values.

source
Streamfall.run_gr4j — Function
run_gr4j(P::Float64, E::Float64,
+GR4J · Streamfall Documentation
Edit on GitHub
GR4J
Streamfall.reset! — Method
reset!(node::GR4JNode)::Nothing
Reset node. Clears all states back to their initial values.
source
Streamfall.run_gr4j — Function
run_gr4j(P::Float64, E::Float64,
          X1::Float64, X2::Float64, X3::Float64, X4::Float64, area::Float64,
-         p_store::Float64=0.0, r_store::Float64=0.0)::Tuple
Generated simulated streamflow for given rainfall and potential evaporation.
Parameters
  • P : Catchment average rainfall
  • E : Catchment average potential evapotranspiration
  • X1 - X4 : X parameters
  • area : Catchment area
  • p_store : Initial production store
  • r_store : Initial state store
Returns
  • tuple of simulated outflow [ML/day], and intermediate states: pstore, rstore, UH1, UH2
source
Streamfall.run_node! — Method
run_node!(node::GR4JNode, climate::Climate)
Run GR4J node for all time steps in given climate sequence.
source
Streamfall.run_timestep! — Method
run_timestep!(node::GR4JNode, climate::Climate, timestep::Int;
-              inflow::Float64, extraction::Float64, exchange::Float64)
Run given GR4J node for a time step.
source
Streamfall.s_curve — Method
s_curve(t::Float64, x4::Float64, uh2::Bool = false)::Float64
Determine unit hydrograph ordinates.
source
Streamfall.GR4JNode — Type
GR4J Node
A four-parameter model with two stores.
Parameters
  • x1 : maximum capacity of the production store (mm) (> 0)
  • x2 : groundwater exchange coefficient (mm) (value < and > 0 possible)
  • x3 : one day ahead maximum capacity of the routing store (mm, > 0)
  • x4 : time base of unit hydrograph UH1 (days, > 0.5)
References
  1. Perrin, C., Michel, C., Andréassian, V., 2003.   Improvement of a parsimonious model for streamflow simulation.   Journal of Hydrology 279, 275-289.  https://doi.org/10.1016/S0022-1694(03)00225-7
  2. MacDonald, A. 2014.   Python GR4J  https://github.com/amacd31/gr4j
source

+         p_store::Float64=0.0, r_store::Float64=0.0)::Tuple

Generated simulated streamflow for given rainfall and potential evaporation.

Parameters

  • P : Catchment average rainfall
  • E : Catchment average potential evapotranspiration
  • X1 - X4 : X parameters
  • area : Catchment area
  • p_store : Initial production store
  • r_store : Initial state store

Returns

  • tuple of simulated outflow [ML/day], and intermediate states: pstore, rstore, UH1, UH2
source
Streamfall.run_node! — Method
run_node!(node::GR4JNode, climate::Climate)

Run GR4J node for all time steps in given climate sequence.

source
Streamfall.run_timestep! — Method
run_timestep!(node::GR4JNode, climate::Climate, timestep::Int;
+              inflow::Float64, extraction::Float64, exchange::Float64)

Run given GR4J node for a time step.

source
Streamfall.s_curve — Method
s_curve(t::Float64, x4::Float64, uh2::Bool = false)::Float64

Determine unit hydrograph ordinates.

source
Streamfall.GR4JNode — Type

GR4J Node

A four-parameter model with two stores.

Parameters

  • x1 : maximum capacity of the production store (mm) (> 0)
  • x2 : groundwater exchange coefficient (mm) (value < and > 0 possible)
  • x3 : one day ahead maximum capacity of the routing store (mm, > 0)
  • x4 : time base of unit hydrograph UH1 (days, > 0.5)

References

  1. Perrin, C., Michel, C., Andréassian, V., 2003. Improvement of a parsimonious model for streamflow simulation. Journal of Hydrology 279, 275-289. https://doi.org/10.1016/S0022-1694(03)00225-7

  2. MacDonald, A. 2014. Python GR4J https://github.com/amacd31/gr4j

source
diff --git a/dev/HyMod/index.html b/dev/HyMod/index.html index a71539b..a814be5 100644 --- a/dev/HyMod/index.html +++ b/dev/HyMod/index.html @@ -1,4 +1,4 @@ HyMod · Streamfall Documentation
Edit on GitHub

HyMod

Streamfall.run_node! — Method
run_node!(node::HyModNode, climate::Climate;
-          inflow=nothing, extraction=nothing, exchange=nothing)

Run given HyMod node for entire simulation period.

source
Streamfall.run_timestep! — Method
run_timestep!(node::HyModNode, climate::Climate, timestep::Int,
-              inflow::Float64, extraction::Float64, exchange::Float64)

Run given HyMod node for a time step.

source
Streamfall.SimpleHyModNode — Type

Simple implementation of HyMod - does not include snow melt processes (see [1]).

Adapted with kind permission from: https://github.com/jdherman/GRA-2020-SALib

References

  1. Gharari, S., Hrachowitz, M., Fenicia, F., Savenije, H.H.G., 2013. An approach to identify time consistent model parameters: sub-period calibration. Hydrology and Earth System Sciences 17, 149-161. https://doi.org/10.5194/hess-17-149-2013
source
+ inflow=nothing, extraction=nothing, exchange=nothing)

Run given HyMod node for entire simulation period.

source
Streamfall.run_timestep! — Method
run_timestep!(node::HyModNode, climate::Climate, timestep::Int,
+              inflow::Float64, extraction::Float64, exchange::Float64)

Run given HyMod node for a time step.

source
Streamfall.SimpleHyModNode — Type

Simple implementation of HyMod - does not include snow melt processes (see [1]).

Adapted with kind permission from: https://github.com/jdherman/GRA-2020-SALib

References

  1. Gharari, S., Hrachowitz, M., Fenicia, F., Savenije, H.H.G., 2013. An approach to identify time consistent model parameters: sub-period calibration. Hydrology and Earth System Sciences 17, 149-161. https://doi.org/10.5194/hess-17-149-2013
source
diff --git a/dev/IHACRES/index.html b/dev/IHACRES/index.html index 3fd100f..d0d93ef 100644 --- a/dev/IHACRES/index.html +++ b/dev/IHACRES/index.html @@ -1,6 +1,6 @@ -IHACRES · Streamfall Documentation
Edit on GitHub

IHACRES

Streamfall.param_info — Method
param_info(node::IHACRESNode; with_level::Bool = true)::Tuple

Extract node parameter names, values, and bounds for IHACRESNode types.

source
Streamfall.reset! — Method
reset!(s_node::IHACRESNode)::Nothing

Reset node. Clears all states back to their initial values.

source
Streamfall.run_node! — Method
run_node!(node::IHACRESNode, climate::Climate, timestep::Int;
-              inflow=nothing, extraction=nothing, exchange=nothing)

Run a specific node for a specified time step.

Arguments

  • node::IHACRESNode :
  • climate::Climate :
  • ts::Int : current time step
  • inflow::DataFrame : Time series of inflows from any upstream node.
  • extraction::DataFrame : Time series of water orders (expects column of _releases)
  • exchange::DataFrame : Time series of groundwater flux
source
Streamfall.run_node_with_temp! — Function
run_node_with_temp!(s_node::BilinearNode,
+IHACRES · Streamfall Documentation
Edit on GitHub
IHACRES
Streamfall.param_info — Method
param_info(node::IHACRESNode; with_level::Bool = true)::Tuple
Extract node parameter names, values, and bounds for IHACRESNode types.
source
Streamfall.reset! — Method
reset!(s_node::IHACRESNode)::Nothing
Reset node. Clears all states back to their initial values.
source
Streamfall.run_node! — Method
run_node!(node::IHACRESNode, climate::Climate, timestep::Int;
+              inflow=nothing, extraction=nothing, exchange=nothing)
Run a specific node for a specified time step.
Arguments
  • node::IHACRESNode :
  • climate::Climate :
  • ts::Int : current time step
  • inflow::DataFrame : Time series of inflows from any upstream node.
  • extraction::DataFrame : Time series of water orders (expects column of _releases)
  • exchange::DataFrame : Time series of groundwater flux
source
Streamfall.run_node_with_temp! — Function
run_node_with_temp!(s_node::BilinearNode,
                     rain::Float64,
                     temp::Float64,
                     inflow::Float64,
@@ -9,7 +9,7 @@
                     current_store=nothing,
                     quick_store=nothing,
                     slow_store=nothing
-                    gw_store=nothing)::Tuple{Float64, Float64}
Run node with temperature data to calculate outflow and update state.
source
Streamfall.run_step! — Method
run_step!(s_node::BilinearNode,
+                    gw_store=nothing)::Tuple{Float64, Float64}
Run node with temperature data to calculate outflow and update state.
source
Streamfall.run_step! — Method
run_step!(s_node::BilinearNode,
           rain::Float64,
           evap::Float64,
           inflow::Float64,
@@ -18,20 +18,20 @@
           current_store::Float64,
           quick_store::Float64,
           slow_store::Float64,
-          gw_store::Float64)::Tuple{Float64, Float64}
Run node with ET data to calculate outflow and update state.
Arguments
  • s_node::BilinearNode : IHACRESNode
  • rain : rainfall for time step
  • evap : evapotranspiration for time step
  • inflow : inflow from previous node
  • ext : irrigation and other water extractions
  • gw_exchange : flux in ML where positive is contribution to stream, negative is infiltration
  • current_store : replacement cmd state value (uses last known state if not provided)
  • quick_store : replacement quick store state value
  • slow_store : replacement slow store state value
  • gw_store : replacement groundwater store state value
Returns
  • float, outflow from node [ML/day], stream level
source
Streamfall.run_timestep! — Method
run_timestep!(s_node::IHACRESNode,
+          gw_store::Float64)::Tuple{Float64, Float64}
Run node with ET data to calculate outflow and update state.
Arguments
  • s_node::BilinearNode : IHACRESNode
  • rain : rainfall for time step
  • evap : evapotranspiration for time step
  • inflow : inflow from previous node
  • ext : irrigation and other water extractions
  • gw_exchange : flux in ML where positive is contribution to stream, negative is infiltration
  • current_store : replacement cmd state value (uses last known state if not provided)
  • quick_store : replacement quick store state value
  • slow_store : replacement slow store state value
  • gw_store : replacement groundwater store state value
Returns
  • float, outflow from node [ML/day], stream level
source
Streamfall.run_timestep! — Method
run_timestep!(s_node::IHACRESNode,
               rain::Float64,
               evap::Float64,
               timestep::Union{Int64, Nothing};
               inflow::Float64,
               extraction::Float64,
-              exchange::Float64)::Tuple{Float64, Float64}
Run node for a given time step.
source
Streamfall.update_params! — Method
update_params!(node::BilinearNode, d::Float64, d2::Float64, e::Float64, f::Float64,
+              exchange::Float64)::Tuple{Float64, Float64}
Run node for a given time step.
source
Streamfall.update_params! — Method
update_params!(node::BilinearNode, d::Float64, d2::Float64, e::Float64, f::Float64,
                a::Float64, b::Float64, s_coef::Float64, alpha::Float64,
-               p1::Float64, p2::Float64, p3::Float64, p4::Float64, p5::Float64, p6::Float64, p7::Float64, p8::Float64, CTF::Float64)::Nothing
Update all parameters.
source
Streamfall.update_params! — Method
update_params!(node::BilinearNode, d::Float64, d2::Float64, e::Float64, f::Float64,
-               a::Float64, b::Float64, s_coef::Float64, alpha::Float64)::Nothing
Update model parameters.
source
Streamfall.BilinearNode — Method
BilinearNode(name::String, area::Float64, d::Float64, d2::Float64, e::Float64, f::Float64,
+               p1::Float64, p2::Float64, p3::Float64, p4::Float64, p5::Float64, p6::Float64, p7::Float64, p8::Float64, CTF::Float64)::Nothing
Update all parameters.
source
Streamfall.update_params! — Method
update_params!(node::BilinearNode, d::Float64, d2::Float64, e::Float64, f::Float64,
+               a::Float64, b::Float64, s_coef::Float64, alpha::Float64)::Nothing
Update model parameters.
source
Streamfall.BilinearNode — Method
BilinearNode(name::String, area::Float64, d::Float64, d2::Float64, e::Float64, f::Float64,
             a::Float64, b::Float64, s_coef::Float64, alpha::Float64,
-            store::Float64, quick::Float64, slow::Float64, gw_store::Float64)
Create a IHACRES node that adopts the bilinear CMD module.
source
IHACRES - Expuh
Streamfall.run_node! — Method
run_node!(s_node::ExpuhNode, rain::Float64, evap::Float64, 
+            store::Float64, quick::Float64, slow::Float64, gw_store::Float64)
Create a IHACRES node that adopts the bilinear CMD module.
source
IHACRES - Expuh
Streamfall.run_node! — Method
run_node!(s_node::ExpuhNode, rain::Float64, evap::Float64, 
           inflow::Float64, ext::Float64, gw_exchange::Float64;
           current_store=nothing,
           quick_store=nothing,
           slow_store=nothing,
-        )::Tuple
Run given IHACRES ExpuhNode for a time step based on last known state.
source

+        )::Tuple

Run given IHACRES ExpuhNode for a time step based on last known state.

source
diff --git a/dev/Node/index.html b/dev/Node/index.html index af355bd..4b11340 100644 --- a/dev/Node/index.html +++ b/dev/Node/index.html @@ -1,2 +1,2 @@ -Generic node methods · Streamfall Documentation
Edit on GitHub

Generic node methods

Streamfall.get_node — Method
get_node(sn::StreamfallNetwork, node_name::String)

Retrieve node_id and node property for a specified gauge.

Arguments

  • sn : Streamfall Network
  • node_name : name of node of interest

Returns

Tuple, node position id and node object

source
Streamfall.param_info — Method
param_info(node::NetworkNode)

Generic parameter information extractor.

Extracts parameter names, values, and bounds

source
Streamfall.reset! — Method
reset!(node::SYMHYDNode)::Nothing

Reset node. Clears all states back to their initial values.

source
+Generic node methods · Streamfall Documentation
Edit on GitHub

Generic node methods

Streamfall.get_node — Method
get_node(sn::StreamfallNetwork, node_name::String)

Retrieve node_id and node property for a specified gauge.

Arguments

  • sn : Streamfall Network
  • node_name : name of node of interest

Returns

Tuple, node position id and node object

source
Streamfall.param_info — Method
param_info(node::NetworkNode)

Generic parameter information extractor.

Extracts parameter names, values, and bounds

source
Streamfall.reset! — Method
reset!(node::SYMHYDNode)::Nothing

Reset node. Clears all states back to their initial values.

source
diff --git a/dev/SYMHYD/index.html b/dev/SYMHYD/index.html index 9c8e9ec..195e3bc 100644 --- a/dev/SYMHYD/index.html +++ b/dev/SYMHYD/index.html @@ -1,2 +1,2 @@ -SYMHYD · Streamfall Documentation
Edit on GitHub
+SYMHYD · Streamfall Documentation
Edit on GitHub
diff --git a/dev/calibration/index.html b/dev/calibration/index.html index f6d6dd3..e9dea9d 100644 --- a/dev/calibration/index.html +++ b/dev/calibration/index.html @@ -106,4 +106,4 @@ # a: 5.923379062122229 # b: 0.0989925603647026 # storage_coef: 1.8613364808233752 # gw storage factor -# alpha: 0.7279050097363565

+# alpha: 0.7279050097363565

diff --git a/dev/calibration_setup/index.html b/dev/calibration_setup/index.html index bfb4dca..d136604 100644 --- a/dev/calibration_setup/index.html +++ b/dev/calibration_setup/index.html @@ -121,4 +121,4 @@ reset!(sn) return score -end +end diff --git a/dev/expected_data_formats/index.html b/dev/expected_data_formats/index.html index 080d487..032ef48 100644 --- a/dev/expected_data_formats/index.html +++ b/dev/expected_data_formats/index.html @@ -12,4 +12,4 @@ 1981-01-03, 10.5, 5.3, 7.2, 2.3 1981-01-04, 9.89, 7.9, 6.1, 4.3 1981-01-05, 0.3, 4.2, 0.2, 6.4 -... snip ...

Climate data functions

Streamfall.climate_values — Method
climate_values(node::NetworkNode, climate::Climate, timestep::Int)

Extract climate related data for a given time step.

source
Streamfall.climate_values — Method
climate_values(node::NetworkNode, climate::Climate)

Extract climate related data for a given time step.

source
Streamfall.rainfall_data — Method
rainfall_data(node::NetworkNode, climate::Climate)::DataFrame

Extract rainfall data for a given node.

source
Streamfall.sim_length — Method
sim_length(climate::Climate)::Int64

Simulation length is dependent on available climate data.

source
Streamfall.subcatchment_data — Method
subcatchment_data(node::NetworkNode, climate::Climate)

Extract all data for a given node from climate object.

source
+... snip ...

Climate data functions

Streamfall.climate_values — Method
climate_values(node::NetworkNode, climate::Climate, timestep::Int)

Extract climate related data for a given time step.

source
Streamfall.climate_values — Method
climate_values(node::NetworkNode, climate::Climate)

Extract climate related data for a given time step.

source
Streamfall.rainfall_data — Method
rainfall_data(node::NetworkNode, climate::Climate)::DataFrame

Extract rainfall data for a given node.

source
Streamfall.sim_length — Method
sim_length(climate::Climate)::Int64

Simulation length is dependent on available climate data.

source
Streamfall.subcatchment_data — Method
subcatchment_data(node::NetworkNode, climate::Climate)

Extract all data for a given node from climate object.

source
diff --git a/dev/index.html b/dev/index.html index b8908d5..35d53aa 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Streamfall.jl Documentation · Streamfall Documentation
Edit on GitHub

Streamfall.jl Documentation

Streamfall: An experimental graph-based streamflow modelling system written in Julialang.

Aims of the project are to leverage the Julia language and ecosystem to allow/enable:

  • Quick application and exploratory analysis
  • Use of different rainfall-runoff models in tandem
  • Modelling and assessment of interacting socio-environmental systems [aspiration]
  • Parallel scenario runs

Streamfall currently includes implementations of:

  • IHACRES, leveraging ihacres_nim
  • HyMOD (without the snowmelt component)
  • GR4J
  • SYMHYD

LightGraphs and MetaGraphs are used underneath for network traversal/analysis.

+Streamfall.jl Documentation · Streamfall Documentation
Edit on GitHub

Streamfall.jl Documentation

Streamfall: An experimental graph-based streamflow modelling system written in Julialang.

Aims of the project are to leverage the Julia language and ecosystem to allow/enable:

  • Quick application and exploratory analysis
  • Use of different rainfall-runoff models in tandem
  • Modelling and assessment of interacting socio-environmental systems [aspiration]
  • Parallel scenario runs

Streamfall currently includes implementations of:

  • IHACRES, leveraging ihacres_nim
  • HyMOD (without the snowmelt component)
  • GR4J
  • SYMHYD

LightGraphs and MetaGraphs are used underneath for network traversal/analysis.

diff --git a/dev/metrics/index.html b/dev/metrics/index.html index 61cd5f3..785c3b6 100644 --- a/dev/metrics/index.html +++ b/dev/metrics/index.html @@ -1,11 +1,11 @@ -Included metrics · Streamfall Documentation
Edit on GitHub

Included metrics

Streamfall.ADJ_R2 — Method

Adjusted R^2

Arguments

  • obs::Vector : observations
  • sim::Vector : modeled results
  • p::Int : number of explanatory variables
source
Streamfall.BKGE — Method

Bounded KGE, bounded between -1 and 1.

Arguments

  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.BmKGE — Method

Bounded modified KGE between -1 and 1.

Arguments

  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.BnpKGE — Method

Bounded non-parametric KGE between -1 and 1.

Arguments

  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.EV — Method
EV(obs, sim)

Explained Variance.

Indicates the amount of variation in the observations which the predictions are able to explain.

source
Streamfall.KGE — Method
KGE(obs::Vector, sim::Vector; scaling::Tuple=nothing)::Float64

Calculate the 2009 Kling-Gupta Efficiency (KGE) metric.

Decomposes NSE into correlation (r), relative variability (α), and bias (β) terms.

A KGE score of 1 means perfect fit. A score < -0.41 indicates that the mean of observations provides better estimates (see Knoben et al., [2]).

The scaling argument expects a three-valued tuple which scales r, α and β factors respectively. If not specified, defaults to 1.

Note: Although similar, NSE and KGE cannot be directly compared.

References

  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, 80–91. https://doi.org/10.1016/j.jhydrol.2009.08.003

  2. Knoben, W.J.M., Freer, J.E., Woods, R.A., 2019. Technical note: Inherent benchmark or not? Comparing Nash-Sutcliffe and Kling-Gupta efficiency scores (preprint). Catchment hydrology/Modelling approaches. https://doi.org/10.5194/hess-2019-327

  3. Mizukami, N., Rakovec, O., Newman, A.J., Clark, M.P., Wood, A.W., Gupta, H.V., Kumar, R., 2019. On the choice of calibration metrics for “high-flow” estimation using hydrologic models. Hydrology and Earth System Sciences 23, 2601–2614. https://doi.org/10.5194/hess-23-2601-2019

source
Streamfall.LME — Method

Liu Mean Efficiency metric (LME).

Reformulation of the KGE metric said to be advantageous for capturing extreme flow events.

Arguments

  • obs::Vector : observations
  • sim::Vector : modeled results

References

  1. Liu, D., 2020. A rational performance criterion for hydrological model. Journal of Hydrology 590, 125488. https://doi.org/10.1016/j.jhydrol.2020.125488
source
Streamfall.NKGE — Method

Normalized KGE between 0 and 1.

Arguments

  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.NNSE — Method

Normalized Nash-Sutcliffe Efficiency score (bounded between 0 and 1).

References

  1. Nossent, J., Bauwens, W., 2012. Application of a normalized Nash-Sutcliffe efficiency to improve the accuracy of the Sobol’ sensitivity analysis of a hydrological model. EGU General Assembly Conference Abstracts 237.
source
Streamfall.NSE_logbias — Method
NSE_logbias(obs, sim; metric::Function=NSE, bias_threshold::Float64=5.0, shape::Float64=2.5)

The NSE_logbias meta-metric provides a weighted combination of a least-squares approach and a logarithmic function of bias. The metric penalizes predictions with an overall bias above a threshold (defined as 5% in [1]).

It is also referred to as the Viney F score.

Extended help

The penalty applied is non-symmetrical (or multiplicatively symmetrical) in that predictions that are double the observed are penalized identically to predictions that are half the observed volume.

Arguments

  • obs::Vector : Historic observations to compare against
  • sim::Vector : Modeled time series
  • metric::Function : least-squares method to use, defaults to NSE
  • bias_threshold::Float64 : Bias threshold after which the score given by metric is penalized, defaults to 5 (%)
  • shape::Float64 : Exponent value controlling shape of penalization (see Figure 2 in [1]).

References

  1. Viney, N. R., Perraud, J., Vaze, J., Chiew, F.H.S., Post, D.A., Yang, A. 2009 The usefulness of bias constraints in model calibration for regionalisation to ungauged catchments 18th World IMACS / MODSIM Congress, Cairns, Australia, 13 - 17 July 2009 Available at: https://www.researchgate.net/publication/294697092Theusefulnessofbiasconstraintsinmodelcalibrationforregionalisationtoungauged_catchments

  2. Teng, J., Potter, N.J., Chiew, F.H.S., Zhang, L., Wang, B., Vaze, J., Evans, J.P., 2015. How does bias correction of regional climate model precipitation affect modelled runoff? Hydrology and Earth System Sciences 19, 711–728. https://doi.org/10.5194/hess-19-711-2015

source
Streamfall.NmKGE — Method

Normalized modified KGE between 0 and 1.

Arguments

  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.NnpKGE — Method

Normalized non-parametric KGE between 0 and 1.

Arguments

  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.PBIAS — Method
PBIAS(obs::Vector, sim::Vector)::Float64

Percent bias between sim and obs

Model performance for streamflow can be determined to be satisfactory if the Nash-Sutcliffe Efficiency (NSE) score > 0.5, the RMSE standard deviation ratio (RSR) < 0.7 and percent bias (PBIAS) is +/- 25% (see [1]).

References

  1. Moriasi, D.N., Arnold, J.G., Liew, M.W.V., Bingner, R.L., Harmel, R.D., Veith, T.L., 2007. Model Evaluation Guidelines for Systematic Quantification of Accuracy in Watershed Simulations. Transactions of the ASABE 50, 885–900. https://doi.org/10.13031/2013.23153
source
Streamfall.RSR — Method
RSR(obs::Vector, sim::Vector)::Float64

The RMSE-observations standard deviation ratio (RSR).

Varies between 0 and a large positive value, where 0 indicates an RMSE value of 0.

References

  1. Moriasi, D.N., Arnold, J.G., Liew, M.W.V., Bingner, R.L., Harmel, R.D., Veith, T.L., 2007. Model Evaluation Guidelines for Systematic Quantification of Accuracy in Watershed Simulations. Transactions of the ASABE 50, 885–900. https://doi.org/10.13031/2013.23153
source
Streamfall.inverse_metric — Method
inverse_metric(obs, sim; metric, comb_method::Function=mean)

A meta-objective function which combines the performance of the given metric as applied to the discharge and the inverse of the discharge.

By default, the combination method is to take the mean.

Arguments

  • obs : observed
  • sim : modeled results
  • metric::Function : objective function
  • comb_method::Function : mean
  • ϵ : offset value to use (enables use with zero-flow time steps), defaults to 1e-2

References

  1. Garcia, F., Folton, N., Oudin, L., 2017. Which objective function to calibrate rainfall–runoff models for low-flow index simulations? Hydrological Sciences Journal 62, 1149–1166. https://doi.org/10.1080/02626667.2017.1308511
source
Streamfall.mKGE — Method

Calculate the modified KGE metric (2012).

Also known as KGE prime (KGE').

Extended help

It is not recommended to apply KGE' with log-transformed flows (see [2]). Numerical instabilities arise as flow approaches values close to zero. This is possible under extreme dry conditions or by chance when sub-sampling.

In cases where observations are constant or otherwise displays zero variance or zero mean flow, this implementation applies a simple logistic function (ℯ⁻ˣ) to gain an indication of simulated data's distance to zero.

This is to:

  • avoid NaNs influencing subsequent calculations
  • allow use with split methods which may partition streamflows into periods of 0 flows.

Arguments

  • obs::Vector: observations
  • sim::Vector : modeled results
  • scaling::Tuple : scaling factors in order of timing (r), magnitude (β), variability (γ). Defaults to (1,1,1).

References

  1. Kling, H., Fuchs, M., Paulin, M., 2012. Runoff conditions in the upper Danube basin under an ensemble of climate change scenarios. Journal of Hydrology 424–425, 264–277. https://doi.org/10.1016/j.jhydrol.2012.01.011

  2. Santos, L., Thirel, G., Perrin, C., 2018. Technical note: Pitfalls in using log-transformed flows within the KGE criterion. Hydrology and Earth System Sciences 22, 4583–4591. https://doi.org/10.5194/hess-22-4583-2018

source
Streamfall.mean_NmKGE — Method

Mean Inverse NmKGE

Said to produce better fits for low-flow indices compared to mKGE (see [1]).

Arguments

  • obs::Vector : observations
  • sim::Vector : modeled results
  • scaling::Tuple : scaling factors for r, α, and β (defaults to 1.0)
  • ϵ::Float64 : small constant to use with inverse flow to allow consideration of periods with no flow. Defaults to 1e-2.

References

  1. Garcia, F., Folton, N., Oudin, L., 2017. Which objective function to calibrate rainfall–runoff models for low-flow index simulations? Hydrological Sciences Journal 62, 1149–1166. https://doi.org/10.1080/02626667.2017.1308511
source
Streamfall.naive_split_metric — Method

Naive approach to split metrics.

Split metrics are a meta-objective optimization approach which "splits" data into subperiods. The objective function is calculated for each subperiod and then recombined. The approach addresses the lack of consideration of dry years with least-squares.

In Fowler et al., [1] the subperiod is one year. The implementation offered here is "naive" in that the data is partitioned into N chunks of n_members and does not consider date/time.

Arguments

  • obs::Vector : Historic observations to compare against
  • sim::Vector : Modeled time series
  • n_members::Int : number of members per chunk (i.e., sub-samples), defaults to 365
  • metric::Function : Objective function to apply, defaults to NNSE
  • comb_method::Function : Recombination method, defaults to mean

References

  1. Fowler, K., Peel, M., Western, A., Zhang, L., 2018. Improved Rainfall-Runoff Calibration for Drying Climate: Choice of Objective Function. Water Resources Research 54, 3392–3408. https://doi.org/10.1029/2017WR022466
source
Streamfall.npKGE — Method

Calculate the non-parametric Kling-Gupta Efficiency (KGE) metric.

Arguments

  • obs::Vector : observations
  • sim::Vector : modeled
  • scaling::Tuple : scaling factors for timing (s), variability (α), magnitude (β)

References

  1. Pool, S., Vis, M., Seibert, J., 2018. Evaluating model performance: towards a non-parametric variant of the Kling-Gupta efficiency. Hydrological Sciences Journal 63, 1941–1953. https://doi.org/10.1080/02626667.2018.1552002
source
Streamfall.relative_skill_score — Method

Relative Skill Score.

Provides an indication of model performance relative to a known benchmark score.

Suitable for use with least-squares approaches that provide skill scores ranging from 1 to -∞.

Arguments

  • Sb : Benchmark score
  • Sm : Model score

References

  1. Knoben, W.J.M., Freer, J.E., Woods, R.A., 2019. Technical note: Inherent benchmark or not? Comparing Nash-Sutcliffe and Kling-Gupta efficiency scores (preprint). Catchment hydrology/Modelling approaches. https://doi.org/10.5194/hess-2019-327
source
Streamfall.skill_score — Method

Allows comparison of any model compared against a pre-defined benchmark, assuming both scores were obtained with the same objective function.

Positive values indicate a model is better than the benchmark, and negative values indicate a model performs worse.

Extended help

It is noted in Knoben et al., [1] that the skill score should always be contextualized with the original benchmark value. Interpreting skill scores by themselves may become difficult if the benchmark score is already quite high. A small improvement of no real practical value could be misconstrued as a large improvement. As an example, if the benchmark has an KGE score of 0.999 and its counterpart 0.9995, then a skill score of 0.5 will be reported.

References

  1. Knoben, W.J.M., Freer, J.E., Woods, R.A., 2019. Technical note: Inherent benchmark or not? Comparing Nash-Sutcliffe and Kling-Gupta efficiency scores (preprint). Catchment hydrology/Modelling approaches. https://doi.org/10.5194/hess-2019-327

  2. Towner, J., Cloke, H.L., Zsoter, E., Flamig, Z., Hoch, J.M., Bazo, J., Coughlan de Perez, E., Stephens, E.M., 2019. Assessing the performance of global hydrological models for capturing peak river flows in the Amazon basin. Hydrology and Earth System Sciences 23, 3057–3080. https://doi.org/10.5194/hess-23-3057-2019

source
Streamfall.@bound — Macro

Bounds given metric between -1.0 and 1.0, where 1.0 is perfect fit.

Suitable for use with any metric that ranges from 1 to -∞.

References

  1. Mathevet, T., Michel, C., Andréassian, V., Perrin, C., 2006. A bounded version of the Nash-Sutcliffe criterion for better model assessment on large sets of basins. IAHS-AISH Publication 307, 211-219. https://iahs.info/uploads/dms/13614.21–211-219-41-MATHEVET.pdf

Example

julia> import Streamfall: @bound, KGE
+Included metrics · Streamfall Documentation
Edit on GitHub
Included metrics
Streamfall.ADJ_R2 — Method
Adjusted R^2
Arguments
  • obs::Vector : observations
  • sim::Vector : modeled results
  • p::Int : number of explanatory variables
source
Streamfall.BKGE — Method
Bounded KGE, bounded between -1 and 1.
Arguments
  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.BmKGE — Method
Bounded modified KGE between -1 and 1.
Arguments
  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.BnpKGE — Method
Bounded non-parametric KGE between -1 and 1.
Arguments
  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.EV — Method
EV(obs, sim)
Explained Variance.
Indicates the amount of variation in the observations which the predictions are able to explain.
source
Streamfall.KGE — Method
KGE(obs::Vector, sim::Vector; scaling::Tuple=nothing)::Float64
Calculate the 2009 Kling-Gupta Efficiency (KGE) metric.
Decomposes NSE into correlation (r), relative variability (α), and bias (β) terms.
A KGE score of 1 means perfect fit. A score < -0.41 indicates that the mean of observations provides better estimates (see Knoben et al., [2]).
The scaling argument expects a three-valued tuple which scales r, α and β factors respectively. If not specified, defaults to 1.
Note: Although similar, NSE and KGE cannot be directly compared.
References
  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, 80–91.  https://doi.org/10.1016/j.jhydrol.2009.08.003
  2. Knoben, W.J.M., Freer, J.E., Woods, R.A., 2019.  Technical note: Inherent benchmark or not? Comparing Nash-Sutcliffe and Kling-Gupta efficiency scores (preprint).  Catchment hydrology/Modelling approaches.  https://doi.org/10.5194/hess-2019-327
  3. Mizukami, N., Rakovec, O., Newman, A.J., Clark, M.P., Wood, A.W.,  Gupta, H.V., Kumar, R., 2019.  On the choice of calibration metrics for “high-flow”      estimation using hydrologic models.  Hydrology and Earth System Sciences 23, 2601–2614.  https://doi.org/10.5194/hess-23-2601-2019
source
Streamfall.LME — Method
Liu Mean Efficiency metric (LME).
Reformulation of the KGE metric said to be advantageous for capturing extreme flow events.
Arguments
  • obs::Vector : observations
  • sim::Vector : modeled results
References
  1. Liu, D., 2020.  A rational performance criterion for hydrological model.  Journal of Hydrology 590, 125488.  https://doi.org/10.1016/j.jhydrol.2020.125488
source
Streamfall.NKGE — Method
Normalized KGE between 0 and 1.
Arguments
  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.NNSE — Method
Normalized Nash-Sutcliffe Efficiency score (bounded between 0 and 1).
References
  1. Nossent, J., Bauwens, W., 2012.  Application of a normalized Nash-Sutcliffe efficiency to improve the accuracy of the Sobol’ sensitivity analysis of a hydrological model.  EGU General Assembly Conference Abstracts 237.
source
Streamfall.NSE_logbias — Method
NSE_logbias(obs, sim; metric::Function=NSE, bias_threshold::Float64=5.0, shape::Float64=2.5)
The NSE_logbias meta-metric provides a weighted combination of a least-squares approach and a logarithmic function of bias. The metric penalizes predictions with an overall bias above a threshold (defined as 5% in [1]).
It is also referred to as the Viney F score.
Extended help
The penalty applied is non-symmetrical (or multiplicatively symmetrical) in that predictions that are double the observed are penalized identically to predictions that are half the observed volume.
Arguments
  • obs::Vector : Historic observations to compare against
  • sim::Vector : Modeled time series
  • metric::Function : least-squares method to use, defaults to NSE
  • bias_threshold::Float64 : Bias threshold after which the score given by metric is penalized, defaults to 5 (%)
  • shape::Float64 : Exponent value controlling shape of penalization (see Figure 2 in [1]).
References
  1. Viney, N. R., Perraud, J., Vaze, J., Chiew, F.H.S., Post, D.A., Yang, A. 2009  The usefulness of bias constraints in model calibration for regionalisation      to ungauged catchments  18th World IMACS / MODSIM Congress, Cairns, Australia, 13 - 17 July 2009  Available at:  https://www.researchgate.net/publication/294697092Theusefulnessofbiasconstraintsinmodelcalibrationforregionalisationtoungauged_catchments
  2. Teng, J., Potter, N.J., Chiew, F.H.S., Zhang, L., Wang, B., Vaze, J., Evans, J.P., 2015.  How does bias correction of regional climate model precipitation affect modelled runoff?  Hydrology and Earth System Sciences 19, 711–728.  https://doi.org/10.5194/hess-19-711-2015
source
Streamfall.NmKGE — Method
Normalized modified KGE between 0 and 1.
Arguments
  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.NnpKGE — Method
Normalized non-parametric KGE between 0 and 1.
Arguments
  • obs::Vector : observations
  • sim::Vector : modeled results
source
Streamfall.PBIAS — Method
PBIAS(obs::Vector, sim::Vector)::Float64
Percent bias between sim and obs
Model performance for streamflow can be determined to be satisfactory if the Nash-Sutcliffe Efficiency (NSE) score > 0.5, the RMSE standard deviation ratio (RSR) < 0.7 and percent bias (PBIAS) is +/- 25% (see [1]).
References
  1. Moriasi, D.N., Arnold, J.G., Liew, M.W.V., Bingner, R.L.,  Harmel, R.D., Veith, T.L., 2007.  Model Evaluation Guidelines for Systematic Quantification  of Accuracy in Watershed Simulations.  Transactions of the ASABE 50, 885–900.  https://doi.org/10.13031/2013.23153
source
Streamfall.RSR — Method
RSR(obs::Vector, sim::Vector)::Float64
The RMSE-observations standard deviation ratio (RSR).
Varies between 0 and a large positive value, where 0 indicates an RMSE value of 0.
References
  1. Moriasi, D.N., Arnold, J.G., Liew, M.W.V., Bingner, R.L.,  Harmel, R.D., Veith, T.L., 2007.  Model Evaluation Guidelines for Systematic Quantification  of Accuracy in Watershed Simulations.  Transactions of the ASABE 50, 885–900.  https://doi.org/10.13031/2013.23153
source
Streamfall.inverse_metric — Method
inverse_metric(obs, sim; metric, comb_method::Function=mean)
A meta-objective function which combines the performance of the given metric as applied to the discharge and the inverse of the discharge.
By default, the combination method is to take the mean.
Arguments
  • obs : observed
  • sim : modeled results
  • metric::Function : objective function
  • comb_method::Function : mean
  • ϵ : offset value to use (enables use with zero-flow time steps), defaults to 1e-2
References
  1. Garcia, F., Folton, N., Oudin, L., 2017.  Which objective function to calibrate rainfall–runoff models      for low-flow index simulations?  Hydrological Sciences Journal 62, 1149–1166.  https://doi.org/10.1080/02626667.2017.1308511
source
Streamfall.mKGE — Method
Calculate the modified KGE metric (2012).
Also known as KGE prime (KGE').
Extended help
It is not recommended to apply KGE' with log-transformed flows (see [2]). Numerical instabilities arise as flow approaches values close to zero. This is possible under extreme dry conditions or by chance when sub-sampling.
In cases where observations are constant or otherwise displays zero variance or zero mean flow, this implementation applies a simple logistic function (ℯ⁻ˣ) to gain an  indication of simulated data's distance to zero.
This is to:
  • avoid NaNs influencing subsequent calculations 
  • allow use with split methods which may partition streamflows into periods of 0 flows.
Arguments
  • obs::Vector: observations
  • sim::Vector : modeled results
  • scaling::Tuple : scaling factors in order of timing (r), magnitude (β), variability (γ).                    Defaults to (1,1,1).
References
  1. Kling, H., Fuchs, M., Paulin, M., 2012.  Runoff conditions in the upper Danube basin under an ensemble of climate change scenarios.  Journal of Hydrology 424–425, 264–277.  https://doi.org/10.1016/j.jhydrol.2012.01.011
  2. Santos, L., Thirel, G., Perrin, C., 2018.  Technical note: Pitfalls in using log-transformed flows within the KGE criterion.  Hydrology and Earth System Sciences 22, 4583–4591.  https://doi.org/10.5194/hess-22-4583-2018
source
Streamfall.mean_NmKGE — Method
Mean Inverse NmKGE
Said to produce better fits for low-flow indices compared to mKGE (see [1]).
Arguments
  • obs::Vector : observations
  • sim::Vector : modeled results
  • scaling::Tuple : scaling factors for r, α, and β (defaults to 1.0)
  • ϵ::Float64 : small constant to use with inverse flow to allow consideration of periods with no flow. Defaults to 1e-2.
References
  1. Garcia, F., Folton, N., Oudin, L., 2017.  Which objective function to calibrate rainfall–runoff      models for low-flow index simulations?  Hydrological Sciences Journal 62, 1149–1166.  https://doi.org/10.1080/02626667.2017.1308511
source
Streamfall.naive_split_metric — Method
Naive approach to split metrics.
Split metrics are a meta-objective optimization approach which "splits" data into subperiods. The objective function is calculated for each subperiod and then recombined. The approach addresses the lack of consideration of dry years with least-squares.
In Fowler et al., [1] the subperiod is one year. The implementation offered here is "naive" in that the data is partitioned into N chunks of n_members and does not consider date/time.
Arguments
  • obs::Vector : Historic observations to compare against
  • sim::Vector : Modeled time series
  • n_members::Int : number of members per chunk (i.e., sub-samples), defaults to 365
  • metric::Function : Objective function to apply, defaults to NNSE
  • comb_method::Function : Recombination method, defaults to mean
References
  1. Fowler, K., Peel, M., Western, A., Zhang, L., 2018.  Improved Rainfall-Runoff Calibration for Drying Climate: Choice of Objective Function.  Water Resources Research 54, 3392–3408.  https://doi.org/10.1029/2017WR022466
source
Streamfall.npKGE — Method
Calculate the non-parametric Kling-Gupta Efficiency (KGE) metric.
Arguments
  • obs::Vector : observations
  • sim::Vector : modeled
  • scaling::Tuple : scaling factors for timing (s), variability (α), magnitude (β)
References
  1. Pool, S., Vis, M., Seibert, J., 2018.  Evaluating model performance: towards a non-parametric variant of the Kling-Gupta efficiency.  Hydrological Sciences Journal 63, 1941–1953.  https://doi.org/10.1080/02626667.2018.1552002
source
Streamfall.relative_skill_score — Method
Relative Skill Score.
Provides an indication of model performance relative to a known benchmark score.
Suitable for use with least-squares approaches that provide skill scores ranging from 1 to -∞.
Arguments
  • Sb : Benchmark score
  • Sm : Model score
References
  1. Knoben, W.J.M., Freer, J.E., Woods, R.A., 2019.  Technical note: Inherent benchmark or not?      Comparing Nash-Sutcliffe and Kling-Gupta efficiency scores (preprint).  Catchment hydrology/Modelling approaches.  https://doi.org/10.5194/hess-2019-327
source
Streamfall.skill_score — Method
Allows comparison of any model compared against a pre-defined benchmark, assuming both scores were obtained with the same objective function.
Positive values indicate a model is better than the benchmark, and negative values indicate a model performs worse.
Extended help
It is noted in Knoben et al., [1] that the skill score should always be contextualized with the original benchmark value. Interpreting skill scores by themselves may become difficult if the benchmark score is already quite high. A small improvement of no real practical value could be misconstrued as a large improvement. As an example, if the benchmark has an KGE score of 0.999 and its counterpart 0.9995, then a skill score of 0.5 will be reported.
References
  1. Knoben, W.J.M., Freer, J.E., Woods, R.A., 2019.   Technical note: Inherent benchmark or not? Comparing Nash-Sutcliffe and Kling-Gupta efficiency scores (preprint).   Catchment hydrology/Modelling approaches.   https://doi.org/10.5194/hess-2019-327
  2. Towner, J., Cloke, H.L., Zsoter, E., Flamig, Z., Hoch, J.M., Bazo, J., Coughlan de Perez, E., Stephens, E.M., 2019.   Assessing the performance of global hydrological models for capturing peak river flows in the Amazon basin.   Hydrology and Earth System Sciences 23, 3057–3080.   https://doi.org/10.5194/hess-23-3057-2019
source
Streamfall.@bound — Macro
Bounds given metric between -1.0 and 1.0, where 1.0 is perfect fit.
Suitable for use with any metric that ranges from 1 to -∞.
References
  1. Mathevet, T., Michel, C., Andréassian, V., Perrin, C., 2006.  A bounded version of the Nash-Sutcliffe criterion for better model  assessment on large sets of basins.  IAHS-AISH Publication 307, 211-219.  https://iahs.info/uploads/dms/13614.21–211-219-41-MATHEVET.pdf
Example
julia> import Streamfall: @bound, KGE
 julia> @bound KGE([1,2], [3,2])
--0.35653767993482094
source
Streamfall.@mean_inverse — Macro
Applies mean inverse approach to a metric.
Suitable for use with any metric that ranges from 1 to -∞.
If using with other macros such as @normalize or @bound, these must come first.
References
  1. Garcia, F., Folton, N., Oudin, L., 2017.  Which objective function to calibrate rainfall–runoff      models for low-flow index simulations?  Hydrological Sciences Journal 62, 1149–1166.  https://doi.org/10.1080/02626667.2017.1308511
Example
julia> import Streamfall: @normalize, @mean_inverse, KGE
+-0.35653767993482094
source
Streamfall.@mean_inverse — Macro
Applies mean inverse approach to a metric.
Suitable for use with any metric that ranges from 1 to -∞.
If using with other macros such as @normalize or @bound, these must come first.
References
  1. Garcia, F., Folton, N., Oudin, L., 2017.  Which objective function to calibrate rainfall–runoff      models for low-flow index simulations?  Hydrological Sciences Journal 62, 1149–1166.  https://doi.org/10.1080/02626667.2017.1308511
Example
julia> import Streamfall: @normalize, @mean_inverse, KGE
 julia> @normalize @mean_inverse KGE [1,2] [3,2] 1e-6
-0.3193506006429825
source
Streamfall.@normalize — Macro
Normalizes given metric between 0.0 and 1.0, where 1.0 is perfect fit.
Suitable for use with any metric that ranges from 1 to -∞.
References
  1. Nossent, J., Bauwens, W., 2012.  Application of a normalized Nash-Sutcliffe efficiency to improve the  accuracy of the Sobol' sensitivity analysis of a hydrological model.  EGU General Assembly Conference Abstracts 237.
Example
julia> import Streamfall: @normalize, KGE
+0.3193506006429825
source
Streamfall.@normalize — Macro
Normalizes given metric between 0.0 and 1.0, where 1.0 is perfect fit.
Suitable for use with any metric that ranges from 1 to -∞.
References
  1. Nossent, J., Bauwens, W., 2012.  Application of a normalized Nash-Sutcliffe efficiency to improve the  accuracy of the Sobol' sensitivity analysis of a hydrological model.  EGU General Assembly Conference Abstracts 237.
Example
julia> import Streamfall: @normalize, KGE
 julia> @normalize KGE([1,2], [3,2])
-0.1111111111111111
source
Streamfall.@split — Macro
Applies split meta metric approach
If using with other macros such as @normalize or @bound, these must come first.
References
  1. Fowler, K., Peel, M., Western, A., Zhang, L., 2018.  Improved Rainfall-Runoff Calibration for Drying Climate:  Choice of Objective Function.  Water Resources Research 54, 3392–3408.  https://doi.org/10.1029/2017WR022466
Example
julia> using Statistics
+0.1111111111111111
source
Streamfall.@split — Macro
Applies split meta metric approach
If using with other macros such as @normalize or @bound, these must come first.
References
  1. Fowler, K., Peel, M., Western, A., Zhang, L., 2018.  Improved Rainfall-Runoff Calibration for Drying Climate:  Choice of Objective Function.  Water Resources Research 54, 3392–3408.  https://doi.org/10.1029/2017WR022466
Example
julia> using Statistics
 julia> import Streamfall: @normalize, @split, KGE
 julia> @normalize @split KGE repeat([1,2], 365) repeat([3,2], 365) 365 mean
-0.3217309561946589
source

+0.3217309561946589
source
diff --git a/dev/model_comparison/index.html b/dev/model_comparison/index.html index 0bb30c7..a543776 100644 --- a/dev/model_comparison/index.html +++ b/dev/model_comparison/index.html @@ -69,4 +69,4 @@ display(combined_plot) -# savefig("multi_model_comparison.png")

+# savefig("multi_model_comparison.png")

diff --git a/dev/multisystem_showcase/index.html b/dev/multisystem_showcase/index.html index 58f07e3..d7f2793 100644 --- a/dev/multisystem_showcase/index.html +++ b/dev/multisystem_showcase/index.html @@ -1,2 +1,2 @@ -A simple showcase of multi-system considerations · Streamfall Documentation
Edit on GitHub

A simple showcase of multi-system considerations

This page is a draft.

Here we showcase a two-node network representing a river and a dam downstream.

The Lower Campaspe catchment - a small semi-arid basin in North-Central Victoria, Australia - is used for the example here.

  • Figure of catchment

As a graph, the network looks like this:

  • Figure of two-node network

The dam is the primary water store for farmers in the area but is also used for recreational activities (camping, boating, fishing, etc) by local enthusiasts and vacationers. The Campaspe river is also home to a culturally and ecologically significant population of fish. A certain level of flow must be ensured at key times during the year to support and maintain their population levels.

In this hypothetical study, local stakeholders would like to have an idea of the range of possible dam levels under a range of environmental watering policies, farmer water use, and how this may impact the level of enjoyment by vacationers.

The possible environmental watering strategies are defined as:

  • Implicit watering: No purposeful releases for environmental demands. Assume natural inflows and agricultural water orders provide sufficient water flow for ecological purposes.

  • Explicit watering: Assume agricultural water orders partially fulfill environmental needs. Water is released as needed to meet any deficit.

  • Prioritized watering: Water for environmental purposes are prioritised and are managed separately from agricultural demands.

For the purpose of this example, the farm water requirements are given as a volume of daily water releases throughout a growing season; the period of time over which a crop can grow. This figure may be provided by another model in practice. The growing season is assumed to be between X and Y, with the daily water requirements over that period being between X and Y.

An index value is used to provide indications of the suitability of dam levels for recreational purposes.

  • explain how recreational index works

Another indicator model is used to show how often environmental needs are met.

  • explain how the environmental indicator model works

An overview of the system under investigation can then be conceptualized like:

  • Conceptual figure of the system

Where water flows into the dam, and water is released to fulfill water needs of the users downstream. Note that "water users" as defined here includes the environment itself.

First, we define a two-node Streamfall Network which represents the river and dam:

We can then generate a number of scenarios representing a mix of the management strategies and water demands, as listed above.

# Code to generate scenarios
# code showing how to run the model(s)

Analysis and wrap up...

+A simple showcase of multi-system considerations · Streamfall Documentation
Edit on GitHub

A simple showcase of multi-system considerations

This page is a draft.

Here we showcase a two-node network representing a river and a dam downstream.

The Lower Campaspe catchment - a small semi-arid basin in North-Central Victoria, Australia - is used for the example here.

  • Figure of catchment

As a graph, the network looks like this:

  • Figure of two-node network

The dam is the primary water store for farmers in the area but is also used for recreational activities (camping, boating, fishing, etc) by local enthusiasts and vacationers. The Campaspe river is also home to a culturally and ecologically significant population of fish. A certain level of flow must be ensured at key times during the year to support and maintain their population levels.

In this hypothetical study, local stakeholders would like to have an idea of the range of possible dam levels under a range of environmental watering policies, farmer water use, and how this may impact the level of enjoyment by vacationers.

The possible environmental watering strategies are defined as:

  • Implicit watering: No purposeful releases for environmental demands. Assume natural inflows and agricultural water orders provide sufficient water flow for ecological purposes.

  • Explicit watering: Assume agricultural water orders partially fulfill environmental needs. Water is released as needed to meet any deficit.

  • Prioritized watering: Water for environmental purposes are prioritised and are managed separately from agricultural demands.

For the purpose of this example, the farm water requirements are given as a volume of daily water releases throughout a growing season; the period of time over which a crop can grow. This figure may be provided by another model in practice. The growing season is assumed to be between X and Y, with the daily water requirements over that period being between X and Y.

An index value is used to provide indications of the suitability of dam levels for recreational purposes.

  • explain how recreational index works

Another indicator model is used to show how often environmental needs are met.

  • explain how the environmental indicator model works

An overview of the system under investigation can then be conceptualized like:

  • Conceptual figure of the system

Where water flows into the dam, and water is released to fulfill water needs of the users downstream. Note that "water users" as defined here includes the environment itself.

First, we define a two-node Streamfall Network which represents the river and dam:

We can then generate a number of scenarios representing a mix of the management strategies and water demands, as listed above.

# Code to generate scenarios
# code showing how to run the model(s)

Analysis and wrap up...

diff --git a/dev/network/index.html b/dev/network/index.html index cf44265..5798930 100644 --- a/dev/network/index.html +++ b/dev/network/index.html @@ -1,3 +1,3 @@ -Defining a network · Streamfall Documentation
Edit on GitHub

Defining a network

Streamfall.create_network — Method
create_network(name::String, network::Dict)::StreamfallNetwork

Create a StreamNetwork from a YAML-derived specification.

Example

julia> network_spec = YAML.load_file("example_network.yml")
-julia> sn = create_network("Example Network", network_spec)
source
Streamfall.create_node — Method
create_node(mg::MetaDiGraph, node_name::String, details::Dict, nid::Int)

Create a node specified with given name (if it does not exist).

Returns

  • this_id, ID of node (if pre-existing) and
  • nid, incremented node id for entire network (equal to this_id if exists)
source
Streamfall.inlets — Method
inlets(sn::StreamfallNetwork, node_name::String)

Find nodes which provides inflows for given node.

source
Streamfall.outlets — Method
outlets(sn::StreamfallNetwork, node_name::String)

Find node immediately downstream from given node.

source
+Defining a network · Streamfall Documentation
Edit on GitHub

Defining a network

Streamfall.create_network — Method
create_network(name::String, network::Dict)::StreamfallNetwork

Create a StreamNetwork from a YAML-derived specification.

Example

julia> network_spec = YAML.load_file("example_network.yml")
+julia> sn = create_network("Example Network", network_spec)
source
Streamfall.create_node — Method
create_node(mg::MetaDiGraph, node_name::String, details::Dict, nid::Int)

Create a node specified with given name (if it does not exist).

Returns

  • this_id, ID of node (if pre-existing) and
  • nid, incremented node id for entire network (equal to this_id if exists)
source
Streamfall.inlets — Method
inlets(sn::StreamfallNetwork, node_name::String)

Find nodes which provides inflows for given node.

source
Streamfall.outlets — Method
outlets(sn::StreamfallNetwork, node_name::String)

Find node immediately downstream from given node.

source
diff --git a/dev/primer/index.html b/dev/primer/index.html index d7423ab..8038dd0 100644 --- a/dev/primer/index.html +++ b/dev/primer/index.html @@ -112,4 +112,4 @@ exchange = another_model(...) # Obtain outflow and level for this time step -outflow, level = run_node!(target_node, climate, this_timestep; inflow=inflow, extraction=extractions, exchange=exchange)

Specific examples can be found in the Examples section.

+outflow, level = run_node!(target_node, climate, this_timestep; inflow=inflow, extraction=extractions, exchange=exchange)

Specific examples can be found in the Examples section.

diff --git a/dev/search/index.html b/dev/search/index.html index 6938ce7..5f1de3c 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · Streamfall Documentation

Loading search...

    +Search · Streamfall Documentation

    Loading search...

      diff --git a/dev/simple_showcase/index.html b/dev/simple_showcase/index.html index 5f774d3..b55fd87 100644 --- a/dev/simple_showcase/index.html +++ b/dev/simple_showcase/index.html @@ -28,4 +28,4 @@ title="Calibrated IHACRES\n(RMSE: $(rmse); NSE: $(nse))", label="Historic", xlabel="Day", ylabel="Dam Level [mAHD]") -plot!(n_data, label="IHACRES")

      +plot!(n_data, label="IHACRES")

      diff --git a/dev/use_methods/index.html b/dev/use_methods/index.html index c335196..396b5f9 100644 --- a/dev/use_methods/index.html +++ b/dev/use_methods/index.html @@ -1,6 +1,6 @@ -Methods to run a network or node · Streamfall Documentation
      Edit on GitHub

      Methods to run a network or node

      Streamfall.align_time_frame — Method
      align_time_frame(timeseries::T...)

      Subset an arbitrary number of DataFrames to their shared period of time.

      Returns subsetted copy of data in same order as input.

      Example

      julia> climate, streamflow = align_time_frame(climate, streamflow)
      source
      Streamfall.run_basin! — Method
      run_basin!(sn::StreamfallNetwork, climate::Climate; inflow=nothing, extraction=nothing, exchange=nothing)

      Run scenario for an entire catchment/basin.

      source
      Streamfall.run_node! — Method
      run_node!(node::NetworkNode, climate::Climate;
-          inflow=nothing, extraction=nothing, exchange=nothing)

      Run a specific node, and only that node, for all time steps.

      Arguments

      • node::NetworkNode : Any Streamfall NetworkNode
      • climate : Climate data
      • inflow::Union{DataFrame, Vector, Number} : Inflow to node
      • extraction::Union{DataFrame, Vector, Number} : Extractions from this subcatchment
      • exchange::Union{DataFrame, Vector, Number} : Groundwater flux
      source
      Streamfall.run_node! — Method
      run_node!(sn::StreamfallNetwork, node_id::Int, climate::Climate, timestep::Int;
+Methods to run a network or node · Streamfall Documentation
      Edit on GitHub
      Methods to run a network or node
      Streamfall.align_time_frame — Method
      align_time_frame(timeseries::T...)
      Subset an arbitrary number of DataFrames to their shared period of time.
      Returns subsetted copy of data in same order as input.
      Example
      julia> climate, streamflow = align_time_frame(climate, streamflow)
      source
      Streamfall.run_basin! — Method
      run_basin!(sn::StreamfallNetwork, climate::Climate; inflow=nothing, extraction=nothing, exchange=nothing)
      Run scenario for an entire catchment/basin.
      source
      Streamfall.run_node! — Method
      run_node!(node::NetworkNode, climate::Climate;
+          inflow=nothing, extraction=nothing, exchange=nothing)
      Run a specific node, and only that node, for all time steps.
      Arguments
      • node::NetworkNode : Any Streamfall NetworkNode
      • climate : Climate data
      • inflow::Union{DataFrame, Vector, Number} : Inflow to node
      • extraction::Union{DataFrame, Vector, Number} : Extractions from this subcatchment
      • exchange::Union{DataFrame, Vector, Number} : Groundwater flux
      source
      Streamfall.run_node! — Method
      run_node!(sn::StreamfallNetwork, node_id::Int, climate::Climate, timestep::Int;
           extraction::Union{DataFrame, Nothing}=nothing,
-          exchange::Union{DataFrame, Nothing}=nothing)
      Run a model attached to a node for a given time step. Recurses upstream as needed.
      Arguments
      • sn::StreamfallNetwork
      • node_id::Int
      • climate::Climate
      • timestep::Int
      • inflow::DataFrame : Additional inflow to consider (in ML/timestep)
      • extraction::DataFrame : Volume of water to be extracted (in ML/timestep)
      • exchange::DataFrame : Volume of flux (in ML/timestep), where negative values are losses to the groundwater system
      source
      Streamfall.run_node! — Method
      run_node!(sn::StreamfallNetwork, node_id::Int, climate::Climate;
-          extraction=nothing, exchange=nothing)::Nothing
      Generic run method that runs a model attached to a given node for all time steps. Recurses upstream as needed.
      Arguments
      • sn::StreamfallNetwork
      • node_id::Int : node to run in the network
      • climate::Climate : Climate object holding rainfall and evaporation data (or temperature)
      • extraction::DataFrame : water orders for each time step (defaults to nothing)
      • exchange::DataFrame : exchange with groundwater system at each time step (defaults to nothing)
      source
      
+          exchange::Union{DataFrame, Nothing}=nothing)

      Run a model attached to a node for a given time step. Recurses upstream as needed.

      Arguments

      • sn::StreamfallNetwork
      • node_id::Int
      • climate::Climate
      • timestep::Int
      • inflow::DataFrame : Additional inflow to consider (in ML/timestep)
      • extraction::DataFrame : Volume of water to be extracted (in ML/timestep)
      • exchange::DataFrame : Volume of flux (in ML/timestep), where negative values are losses to the groundwater system
      source
      Streamfall.run_node! — Method
      run_node!(sn::StreamfallNetwork, node_id::Int, climate::Climate;
+          extraction=nothing, exchange=nothing)::Nothing

      Generic run method that runs a model attached to a given node for all time steps. Recurses upstream as needed.

      Arguments

      • sn::StreamfallNetwork
      • node_id::Int : node to run in the network
      • climate::Climate : Climate object holding rainfall and evaporation data (or temperature)
      • extraction::DataFrame : water orders for each time step (defaults to nothing)
      • exchange::DataFrame : exchange with groundwater system at each time step (defaults to nothing)
      source