Standardize docstrings

More docstring changes

examples/calibration/alt_calibration.jl

@@ -38,7 +38,7 @@ function calibrate(sn, v_id, climate, calib_data)
                   TraceInterval=30.0,
                   PopulationSize=75,
                   )
-    
+
     res = bboptimize(opt)
 
     bs = best_candidate(res)

src/Nodes/DamNode.jl

@@ -210,21 +210,25 @@ end
 
 
 """
-    run_node!(node::DamNode, climate::Climate, timestep::Int;
-              inflow=nothing, extraction=nothing, exchange=nothing)
+    run_node!(
+        node::DamNode, climate::Climate, timestep::Int;
+        inflow=nothing, extraction=nothing, exchange=nothing
+    )::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
+- `node` : DamNode
+- `climate` : Climate dataset
+- `timestep` : Current time step
+- `inflow` : Time series of inflows from any upstream node.
+- `extraction` : Time series of water orders (expects column of `_releases`)
+- `exchange` : Time series of groundwater flux
 """
-function run_node!(node::DamNode, climate::Climate, timestep::Int;
-                   inflow=nothing, extraction=nothing, exchange=nothing)::Nothing
+function run_node!(
+    node::DamNode, climate::Climate, timestep::Int;
+    inflow=nothing, extraction=nothing, exchange=nothing
+)::Nothing
     ts = timestep
     # if checkbounds(Bool, node.outflow, ts)
     #     if node.outflow[ts] != undef
@@ -247,27 +251,40 @@ end
 
 
 """
+    run_node!(
+        node::DamNode,
+        ts::Int64,
+        rain::Float64,
+        et::Float64,
+        volume::Float64,
+        inflow::Float64,
+        extractions::Float64,
+        gw_flux::Float64
+    )
+
 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
+# Arguments
+- `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
+Outflow from dam
 """
-function run_node!(node::DamNode,
-                   ts::Int64,
-                   rain::Float64,
-                   et::Float64,
-                   volume::Float64,
-                   inflow::Float64,
-                   extractions::Float64,
-                   gw_flux::Float64)
+function run_node!(
+    node::DamNode,
+    ts::Int64,
+    rain::Float64,
+    et::Float64,
+    volume::Float64,
+    inflow::Float64,
+    extractions::Float64,
+    gw_flux::Float64
+)
     dam_area = node.calc_dam_area(volume)
     discharge = node.calc_dam_discharge(volume, node.max_storage)
 
@@ -297,6 +314,12 @@ end
 
 """
     update_params!(node::DamNode, storage_coef::Float64)::Nothing
+
+Method to update `DamNode` specific parameters.
+
+# Arguments
+- `node` : DamNode
+- `storage_coef` : Storage coefficient value
 """
 function update_params!(node::DamNode, storage_coef::Float64)::Nothing
     node.storage_coef = Param(storage_coef, bounds=node.storage_coef.bounds)

src/calibration.jl

@@ -39,7 +39,6 @@ Objective function which considers performance of next node and current node.
 The weighting factor places equal emphasis on both nodes by default (0.5).
 The weighting value places a \$x\$ weight on the current node, and \$1 - x\$ on the next
 node.
-
 """
 function dependent_obj_func(
     params, climate::Climate, this_node::NetworkNode, next_node::NetworkNode, calib_data::DataFrame;
@@ -106,43 +105,50 @@ end
 
 
 """
-    calibrate!(sn, v_id, climate, calib_data,
-               metric::Function=Streamfall.RMSE;
-               kwargs...)
+    calibrate!(
+        sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame;
+        metric::Function=Streamfall.RMSE, kwargs...
+    )
 
 Calibrate a given node, recursing upstream, using the BlackBoxOptim package.
 
 # Arguments
 - `sn::StreamfallNetwork` : Network
 - `v_id::Int` : node identifier
 - `climate::Climate` : Climate data
-- `calib_data::Array` : calibration data for target node by its id
+- `calib_data::Array` : Calibration data for target node by its name.
 - `metric::Function` : Optimization function to use. Defaults to RMSE.
+- `kwargs` : Additional arguments to use.
 """
-function calibrate!(sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame;
-                    metric::Function=Streamfall.RMSE,
-                    kwargs...)
+function calibrate!(
+    sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame;
+    metric::Function=Streamfall.RMSE, kwargs...
+)
     calibrate!(sn, v_id, climate, calib_data; metric=metric, kwargs...)
 end
 
 
 """
-    calibrate!(sn, v_id, climate, calib_data,
-               metric::Function=Streamfall.RMSE;
-               kwargs...)
+    calibrate!(
+        sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame;
+        metric::Function=Streamfall.RMSE, kwargs...
+    )
 
 Calibrate a given node, recursing upstream, using the BlackBoxOptim package.
 
 # Arguments
-- `sn::StreamfallNetwork` : Network
-- `v_id::Int` : node identifier
-- `climate::Climate` : Climate data
-- `calib_data::DataFrame` : calibration data for target node by its id
-- `metric::Function` : Optimization function to use. Defaults to RMSE.
+- `sn` : Streamfall Network
+- `v_id` : node identifier
+- `climate` : Climate data
+- `calib_data` : Calibration data for target node by its name.
+- `metric` : Optimization function to use. Defaults to RMSE.
+- `kwargs` : Additional calibration arguments.
+             BlackBoxOptim arguments will be passed through.
 """
-function calibrate!(sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame;
-                    metric::Function=Streamfall.RMSE,
-                    kwargs...)
+function calibrate!(
+    sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_data::DataFrame;
+    metric::Function=Streamfall.RMSE, kwargs...
+)
     # Set defaults as necessary
     defaults = (;
         MaxTime=900,
@@ -161,7 +167,15 @@ function calibrate!(sn::StreamfallNetwork, v_id::Int64, climate::Climate, calib_
     end
 
     this_node = sn[v_id]
-    next_node = sn[first(outlets(sn, this_node.name))]
+    next_node = try
+        sn[first(outlets(sn, this_node.name))]
+    catch err
+        if !(err isa BoundsError)
+            throw(err)
+        end
+
+        nothing
+    end
 
     extraction = get(kwargs, :extraction, nothing)
     exchange = get(kwargs, :exchange, nothing)
@@ -207,9 +221,11 @@ end
 
 # TODO : Clean the next two methods up as they are rough duplicates.
 """
-    calibrate!(node, climate::Climate, calib_data::Array;
-               metric::Function=Streamfall.RMSE,
-               kwargs...)
+    calibrate!(
+        node::NetworkNode, climate::Climate, calib_data::Array;
+        metric::Function=Streamfall.RMSE,
+        kwargs...
+    )
 
 Calibrate a given node using the BlackBoxOptim package.
 
@@ -220,9 +236,11 @@ Calibrate a given node using the BlackBoxOptim package.
 - `extractor::Function` : Calibration extraction method, define a custom one to change behavior
 - `metric::Function` : Optimization function to use. Defaults to RMSE.
 """
-function calibrate!(node::NetworkNode, climate::Climate, calib_data::Array;
-                    metric::Function=Streamfall.RMSE,
-                    kwargs...)
+function calibrate!(
+    node::NetworkNode, climate::Climate, calib_data::Array;
+    metric::Function=Streamfall.RMSE,
+    kwargs...
+)
     # Set defaults as necessary
     defaults = (;
         MaxTime=900,
@@ -268,9 +286,10 @@ end
 
 
 """
-    calibrate!(node, climate::Climate, calib_data::DataFrame;
-               metric::Function=Streamfall.RMSE,
-               kwargs...)
+    calibrate!(
+        node::NetworkNode, climate::Climate, calib_data::DataFrame;
+        metric::Function=Streamfall.RMSE, kwargs...
+    )
 
 Calibrate a given node using the BlackBoxOptim package.
 
@@ -281,9 +300,10 @@ Calibrate a given node using the BlackBoxOptim package.
 - `extractor::Function` : Calibration extraction method, define a custom one to change behavior
 - `metric::Function` : Optimization function to use. Defaults to RMSE.
 """
-function calibrate!(node::NetworkNode, climate::Climate, calib_data::DataFrame;
-                    metric::Function=Streamfall.RMSE,
-                    kwargs...)
+function calibrate!(
+    node::NetworkNode, climate::Climate, calib_data::DataFrame;
+    metric::Function=Streamfall.RMSE, kwargs...
+)
     # Set defaults as necessary
     defaults = (;
         MaxTime=900,
@@ -315,15 +335,17 @@ end
 
 
 """
-    calibrate!(sn::StreamfallNetwork, climate::Climate, calib_data::DataFrame;
-               metric::Function=Streamfall.RMSE,
-               kwargs...)
+    calibrate!(
+        sn::StreamfallNetwork, climate::Climate, calib_data::DataFrame;
+        metric::Function=Streamfall.RMSE, kwargs...
+    )
 
 Calibrate a stream network.
 """
-function calibrate!(sn::StreamfallNetwork, climate::Climate, calib_data::DataFrame;
-                   metric::Function=Streamfall.RMSE,
-                   kwargs...)
+function calibrate!(
+    sn::StreamfallNetwork, climate::Climate, calib_data::DataFrame;
+    metric::Function=Streamfall.RMSE, kwargs...
+)
     _, outlets = find_inlets_and_outlets(sn)
     calib_states = Dict()
     for out in outlets