Update all examples

README.md

@@ -16,7 +16,7 @@ This package includes implementations of the following:
 - GR4J
 - HyMod
 - IHACRES
-- SYMHYD
+- SIMHYD
 
 Performance is expected to be similar to implementations in C and Fortran.
 
@@ -26,7 +26,7 @@ Naive timings (using `@time`) for an example dataset spanning 1963-07-05 - 2014-
   0.016502 seconds (469.25 k allocations: 12.902 MiB)
 - GR4JNode \
   0.015274 seconds (224.75 k allocations: 5.584 MiB)
-- SYMHYDNode \
+- SIMHYDNode \
   0.039540 seconds (638.01 k allocations: 15.190 MiB, 46.99% gc time)
 - IHACRESBilinearNode \
   0.021734 seconds (675.63 k allocations: 17.773 MiB)
@@ -92,11 +92,11 @@ using CSV, DataFrames, YAML
 using StatsPlots
 using Streamfall
 
-example_data_dir = joinpath(dirname(dirname(pathof(Streamfall))), "test/data")
+data_dir = joinpath(dirname(dirname(pathof(Streamfall))), "test/data")
 
 # Load data file which holds observed streamflow, precipitation and PET data
 obs_data = CSV.read(
-    joinpath(example_data_dir, "cotter/climate/CAMELS-AUS_410730.csv"), 
+    joinpath(data_dir, "cotter/climate/CAMELS-AUS_410730.csv"), 
     DataFrame; 
     comment="#"
 )
@@ -225,12 +225,12 @@ using Streamfall
 
 # Load a network from a file, providing a name for the network and the file path.
 # Creates a graph representation of the stream with associated metadata.
-example_data_dir = joinpath(dirname(dirname(pathof(Streamfall))), "test/data")
-sn = load_network("Example Network", joinpath(example_data_dir, "campaspe/campaspe_network.yml"))
+data_dir = joinpath(dirname(dirname(pathof(Streamfall))), "test/data")
+sn = load_network("Example Network", joinpath(data_dir, "campaspe/campaspe_network.yml"))
 
 # Load climate data, in this case from a CSV file with data for all nodes.
 # Indicate which columns are precipitation and evaporation data based on partial identifiers
-climate = Climate(joinpath(example_data_dir, "campaspe/climate/climate.csv"), "_rain", "_evap")
+climate = Climate(joinpath(data_dir, "campaspe/climate/climate.csv"), "_rain", "_evap")
 
 # This runs an entire stream network
 @info "Running an example stream..."

docs/make.jl

@@ -1,4 +1,4 @@
-push!(LOAD_PATH,"../src/")
+push!(LOAD_PATH, "../src/")
 
 # using Pkg
 
@@ -8,28 +8,29 @@ using Documenter, Streamfall
 
 
 makedocs(sitename="Streamfall Documentation",
-    format = Documenter.HTML(
-        prettyurls = get(ENV, "CI", nothing) == "true"
+    format=Documenter.HTML(
+        prettyurls=get(ENV, "CI", nothing) == "true"
     ),
-    pages = [
+    pages=[
         "index.md",
         "primer.md",
         "expected_data_formats.md",
         "Examples" => [
             "examples/examples.md",
             "examples/node_creation.md",
             "examples/network_loading.md",
+            "Model evaluation" => [
+                "examples/evaluation/simple_showcase.md",
+                "examples/evaluation/model_comparison.md",
+                "examples/evaluation/simple_multisystem.md",
+            ],
             "Calibration" => [
                 # "examples/calibration_setup.md",
-                "examples/calibration.md",
-            ],
-            "Model evaluation" => [
-                "examples/simple_showcase.md",
-                "examples/model_comparison.md",
-                "examples/simple_multisystem.md",
+                "examples/calibration/calibration.md",
+                "examples/calibration/custom_calibration.md",
             ],
             "Ensemble modeling" => [
-                "examples/weighted_ensembles.md"
+                "examples/ensembles/weighted_ensembles.md"
             ]
         ],
         "API" => [
@@ -39,7 +40,7 @@ makedocs(sitename="Streamfall Documentation",
                 "API/nodes/IHACRES.md",
                 "API/nodes/HyMod.md",
                 "API/nodes/GR4J.md",
-                "API/nodes/SYMHYD.md",
+                "API/nodes/SIMHYD.md",
                 "API/nodes/Dam.md"
             ],
             "API/plotting.md",
@@ -51,8 +52,8 @@ makedocs(sitename="Streamfall Documentation",
 )
 
 deploydocs(
-    repo = "github.com/ConnectedSystems/Streamfall.jl.git",
-    devbranch = "main",
+    repo="github.com/ConnectedSystems/Streamfall.jl.git",
+    devbranch="main",
     target="build",
     deps=nothing,
     make=nothing

docs/src/API/nodes/SYMHYD.md → docs/src/API/nodes/SIMHYD.md

@@ -1,7 +1,7 @@
-# SYMHYD
+# SIMHYD
 
 ```@autodocs
 Modules = [Streamfall]
 Order   = [:function, :type]
-Pages   = ["Nodes/SYMHYD/SYMHYDNode.jl"]
+Pages   = ["Nodes/SIMHYD/SIMHYDNode.jl"]
 ```

docs/src/examples/calibration.md → docs/src/examples/calibration/calibration.md

@@ -9,36 +9,41 @@ Data is prepped with the script `campaspe_data_prep.jl` in the `test/data/campas
 directory.
 """
 
-using OrderedCollections
-using Glob
-
 using Statistics
-using CSV, DataFrames, YAML
+using CSV, YAML, DataFrames
 using Streamfall
 
 # Import visualization packages to compile extensions
-using Plots, GraphPlot
-
+using StatsPlots, GraphPlot
 
-sn = load_network("Example Network", "../test/data/campaspe/campaspe_network.yml")
+example_data_dir = joinpath(dirname(dirname(pathof(Streamfall))), "test/data")
+sn = load_network(
+    "Example Network", 
+    joinpath(example_data_dir, "campaspe/campaspe_network.yml")
+)
 
 # The Campaspe catchment is represented as a network of eight nodes, including one dam.
 # All nodes use the IHACRES_CMD rainfall-runoff model.
 plot_network(sn)
 
 # Load climate data - in this case from a CSV file with data for all nodes.
 # Indicate which columns are precipitation and evaporation data based on partial identifiers
-climate = Climate("../test/data/campaspe/climate/climate.csv", "_rain", "_evap")
+example_data_dir = joinpath(dirname(dirname(pathof(Streamfall))), "test/data/campaspe")
+climate = Climate(joinpath(example_data_dir, "climate/climate.csv"), "_rain", "_evap")
 
 # Historic flows and dam level data
 calib_data = CSV.read(
-    "../test/data/campaspe/gauges/outflow_and_level.csv",
+    joinpath(example_data_dir, "gauges/outflow_and_level.csv"),
     DataFrame;
     comment="#"
 )
 
 # Historic extractions from the dam
-extraction_data = CSV.read("../test/data/campaspe/gauges/dam_extraction.csv", DataFrame; comment="#")
+extraction_data = CSV.read(
+    joinpath(example_data_dir, "gauges/dam_extraction.csv"), 
+    DataFrame; 
+    comment="#"
+)
 
 # We now have a dataset for calibration (`calib_data`) and a dataset indicating the
 # historic dam extractions (`extraction_data`).
@@ -79,8 +84,9 @@ calibrate!(
     MaxTime=60.0
 );
 
-# Could calibrate a specific node, assuming all nodes upstream have already been calibrated
-# Set `calibrate_all=true` to calibrate all upstream nodes as well.
+# A specific node can also be calibrated, assuming all nodes upstream have already been 
+# calibrated.
+# Otherwise, set `calibrate_all=true` to calibrate all upstream nodes as well.
 # To produce the results shown below, the node upstream from the dam was calibrated an
 # additional 2 hours.
 # calibrate!(
@@ -102,11 +108,11 @@ Streamfall.NSE(dam_obs[366:end], dam_sim[366:end])
 Streamfall.mKGE(dam_obs[366:end], dam_sim[366:end])
 
 # Plot results
-f = quickplot(dam_obs, dam_sim, climate, "Modelled - 406000", false; burn_in=366)
-savefig(f, "example_dam_level.png")
+f = quickplot(dam_obs, dam_sim, climate; label="Modelled - 406000", log=false, burn_in=366)
+# savefig(f, "example_dam_level.png")
 
 # Save calibrated network to a file
-save_network(sn, "example_network_calibrated.yml")
+# save_network(sn, "example_network_calibrated.yml")
 
 # Illustrating that the re-loaded network reproduces the results as above
 sn2 = load_network("Calibrated Example", "example_network_calibrated.yml")
@@ -128,13 +134,13 @@ temporal_cross_section(sim_dates, calib_data[:, "406000"], sn2[3].level)
 
 The last two lines produces the plots below
 
-![](../assets/calibrated_example.png)
+![](../../assets/calibrated_example.png)
 
 The `quickplot()` function creates the figure displayed above which shows dam levels on the
 left (observed and modelled) with a [Q-Q plot](https://en.wikipedia.org/wiki/Q%E2%80%93Q_plot)
 on the right.
 
-![](../assets/temporal_xsection_historic_calibrated.png)
+![](../../assets/temporal_xsection_historic_calibrated.png)
 
 The above shows a "cross-section" of model predictions for each month-day across simulation
 time. It is useful to gain an understanding on when models may underperform and give a

docs/src/examples/calibration_setup.md → docs/src/examples/calibration/calibration_setup.md

@@ -4,6 +4,9 @@ The calibration examples all rely on the functions shown here.
 
 List of metrics provided by Streamfall can be found in [Included metrics](@ref)
 
+The example here assumes the data has been installed or copied locally.
+Alternatively, download the `test/data` directory from the project repository and 
+change the `DATA_PATH` variable below accordingly.
 
 ## Importing shared/common packages
 
@@ -12,19 +15,16 @@ List of metrics provided by Streamfall can be found in [Included metrics](@ref)
 using Statistics, DataFrames, CSV
 using Distributed, BlackBoxOptim
 
-using ModelParameters
-using Graphs, MetaGraphs
-using YAML, Plots
+using YAML
+using StatsPlots, GraphPlot
 using Streamfall
 ```
 
-
 ## Load network specification
 
-Note that the `DATA_PATH` is pointing to the `test/data/campaspe/` directory.
-
 ```julia
 # Load and generate stream network
+DATA_PATH = joinpath(dirname(dirname(pathof(Streamfall))), "test/data/campaspe/")
 network = YAML.load_file(joinpath(DATA_PATH, "campaspe_network.yml"))
 sn = create_network("Example Network", network)
 ```
@@ -34,14 +34,15 @@ sn = create_network("Example Network", network)
 ```julia
 # Load climate data
 date_format = "YYYY-mm-dd"
-climate_data = CSV.File(joinpath(data_path, "climate/climate_historic.csv"),
+climate_data = CSV.read(joinpath(DATA_PATH, "climate/climate_historic.csv"),
                         comment="#",
-                        dateformat=date_format) |> DataFrame
+                        dateformat=date_format, DataFrame)
+
+dam_level_fn = joinpath(DATA_PATH, "gauges/406000_historic_levels_for_fit.csv")
+hist_dam_levels = CSV.read(dam_level_fn, dateformat=date_format, DataFrame)
 
-dam_level_fn = joinpath(data_path, "dam/historic_levels_for_fit.csv")
-dam_releases_fn = joinpath(data_path, "dam/historic_releases.csv")
-hist_dam_levels = CSV.File(dam_level_fn, dateformat=date_format) |> DataFrame
-hist_dam_releases = CSV.File(dam_releases_fn, dateformat=date_format) |> DataFrame
+dam_releases_fn = joinpath(DATA_PATH, "gauges/406000_historic_outflow.csv")
+hist_dam_releases = CSV.read(dam_releases_fn, dateformat=date_format, DataFrame)
 
 # Subset to same range
 climate_data, hist_dam_levels, hist_dam_releases = Streamfall.align_time_frame(climate_data,