Update all examples

Use `pathof()` to point to example test data
Add example of custom calibration approaches

Author: ConnectedSystems

README.md

@@ -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" => [
@@ -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/assets/custom_calibration_ensemble.png

@@ -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")

docs/src/assets/custom_calibration_gr4j.png

@@ -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,