Expose code blocks in replication and explain REPL usage (#395)

* update replication example to show all code blocks and beef up description

* fix generated_quantities return usage

* reformat

* prune deps and add CSV

* Hide the doc generating bit and add description of usage

* moving specific Pluto instructions into faq and env details into contributing

* revert doc activate to fix CI

* Rewrite FAQ and contribution guide

* fix broken cross-ref

EpiAware/docs/Project.toml

@@ -1,14 +1,14 @@
 [deps]
 ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"
 AdvancedHMC = "0bf59076-c3b1-5ca4-86bd-e02cd72cde3d"
+CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
 Changelog = "5217a498-cd5d-4ec6-b8c2-9b85a09b6e3e"
 DataFramesMeta = "1313f7d8-7da2-5740-9ea0-a2ca25f37964"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DynamicPPL = "366bfd00-2699-11ea-058f-f148b4cae6d8"
 EpiAware = "b2eeebe4-5992-4301-9193-7ebc9f62c855"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
-Pathfinder = "b1d3bc72-d0e7-4279-b92f-7fa5d6d2d454"
 Pluto = "c3e4b0f8-55cb-11ea-2926-15256bba5781"
 PlutoStaticHTML = "359b1769-a58e-495b-9770-312e911026ad"
 ReverseDiff = "37e2e3b7-166d-5795-8a7a-e32c996b4267"

EpiAware/docs/src/developer/contributing.md

@@ -39,3 +39,45 @@ As is conventional for Julia packages, unit tests are located at `test/*.jl` wit
 Tests that build example package docs from source and inspect the results (end to end tests) are
 located in `/test/examples`. The main entry points are `test/examples/make.jl` for building and
 `test/examples/test.jl` for doing some basic checks on the generated outputs.
+
+## Pluto usage in showcase documentation
+
+Some of the showcase examples in `EpiAware/docs/src/showcase` use [`Pluto.jl`](https://plutojl.org/) notebooks for the underlying computation. The output of the notebooks is rendered into HTML for inclusion in the documentation in two steps:
+1. [`PlutoStaticHTML.jl`](https://github.com/rikhuijzer/PlutoStaticHTML.jl) converts the notebook with output into a machine-readable `.md` format.
+2. [`Documenter.jl`](https://github.com/JuliaDocs/Documenter.jl) renders the `.md` file into HTML for inclusion in the documentation during the build process.
+
+For other examples of using `Pluto` to generate documentation see the examples shown [here](https://plutostatichtml.huijzer.xyz/stable/#Documenter.jl).
+
+### Running Pluto notebooks from `EpiAware` locally
+
+To run the `Pluto.jl` scripts in the `EpiAware` documentation directly from the source code you can do these steps:
+
+1. Install [`Pluto.jl`](https://plutojl.org/) locally. We recommend using the version of `Pluto` that is pinned in the `Project.toml` file defining the documentation environment.
+2. Clone the `EpiAware` repository.
+3. Start `Pluto.jl` either from REPL (see the `Pluto.jl` documentation) or from the command line with the shell script `EpiAware/docs/pluto-scripts.sh`.
+4. From the `Pluto.jl` interface, navigate to the `Pluto.jl` script you want to run.
+
+### Contributing to Pluto notebooks in `EpiAware` documentation
+
+#### Modifying an existing Pluto notebook
+Committing changes to the `Pluto.jl` notebooks in the `EpiAware` documentation is the same as committing changes to any other part of the repository. However, please note that we expect the following features for the environment management of the notebooks:
+
+1. Use the environment determined by the `Project.toml` file in the `EpiAware/docs` directory. If you want extra packages, add them to this environment.
+2. Use the version of `EpiAware` that is used in these notebooks to be the version of `EpiAware` on the branch being pull requested into `main`. To do this use the `Pkg.develop` function.
+
+To do this you can use the following code snippet in the Pluto notebook:
+
+```julia
+# Determine the relative path to the `EpiAware/docs` directory
+docs_dir = dirname(dirname(dirname(dirname(@__DIR__))))
+# Determine the relative path to the `EpiAware` package directory
+pkg_dir = dirname(docs_dir)
+
+using Pkg: Pkg
+Pkg.activate(docs_dir)
+Pkg.develop(; path = pkg_dir)
+Pkg.instantiate()
+```
+
+#### Adding a new Pluto notebook
+Adding a new `Pluto.jl` notebook to the `EpiAware` documentation is the same as adding any other file to the repository. However, in addition to following the guidelines for modifying an [existing notebook](#modifying-an-existing-pluto-notebook), please note that the new notebook is added to the set of notebook builds using `build` in the `EpiAware/docs/make.jl` file. This will generate an `.md` of the same name as the notebook which can be rendered when `makedocs` is run. For this document to be added to the overall documentation the path to the `.md` file must be added to the `Pages` array defined in `EpiAware/docs/pages.jl`.

EpiAware/docs/src/getting-started/faq.md

@@ -6,11 +6,14 @@ This page contains a list of frequently asked questions about the `EpiAware` pac
 Pages = ["lib/getting-started/faq.md"]
 ```
 
-## Pluto scripts
+## Pluto notebooks
+
+In some of the showcase examples in `EpiAware/docs/src/showcase` we use [`Pluto.jl`](https://plutojl.org/) notebooks for the underlying computation. As well as reading the code blocks and output of the notebooks in this documentation, you can also run these notebooks by cloning `EpiAware` and running the notebooks with `Pluto.jl` (for further details see [developer notes](@ref developer)).
+
+It should be noted that `Pluto.jl` notebooks are reactive, meaning that they re-run downstream code after changes with downstreaming determined by a tree of dependent code blocks. This is different from the standard Julia REPL, and some other notebook formats (e.g. `.ipynb`). In `Pluto` each code block is a single lines of code or encapsulated by `let ... end` and `begin ... end`. The difference between `let ... end` blocks and `begin ... end` blocks are that the `let ... end` type of code block only adds the final output/return value of the block to scope, like an anonymous function, whereas `begin ... end` executes each line and adds defined variables to scope.
+
+For installation instructions and more information and documentation on `Pluto.jl` see the [Pluto.jl documentation](https://plutojl.org/).
 
-We use [`Pluto.jl`](https://plutojl.org/) scripts as part of our documentation and testing. The scripts are located in `docs/src/examples` and can be run using the `Pluto.jl` package.
-We recommend using the version of `Pluto` that is pinned in the `Project.toml` file defining the documentation environment.
-An entry point to running or developing this documentation is the `docs/pluto-scripts.sh` bash shell script. Run this from the root directory of this repository.
 
 ## Manipulating `EpiAware` model specifications
 

EpiAware/docs/src/showcase/replications/mishra-2020/index.jl

@@ -1,11 +1,10 @@
 ### A Pluto.jl notebook ###
-# v0.19.40
+# v0.19.43
 
 using Markdown
 using InteractiveUtils
 
 # ╔═╡ 34a06b3b-799b-48c5-bd08-1e57151f51ec
-# hideall
 let
     docs_dir = dirname(dirname(dirname(dirname(@__DIR__))))
     pkg_dir = dirname(docs_dir)
@@ -16,31 +15,34 @@ let
     Pkg.instantiate()
 end;
 
+# ╔═╡ d63b37f0-9642-4c38-ac01-9ffe48d50441
+using EpiAware
+
+# ╔═╡ 74642759-35a5-4957-9f2b-544712866410
+using Turing, DynamicPPL #Underlying Turing ecosystem packages to interact with models
+
+# ╔═╡ 0c5f413e-d043-448d-8665-f0f6f705d70f
+using Distributions, Statistics #Statistics packages
+
+# ╔═╡ b1e2a759-a52b-4ee5-8db4-cfe848878c92
+using CSV, DataFramesMeta #Data wrangling
+
+# ╔═╡ 9eb03a0b-c6ca-4e23-8109-fb68f87d7fdf
+begin #Plotting backend
+    using StatsPlots
+    using StatsPlots.PlotMeasures
+end
+
+# ╔═╡ 97b5374e-7653-4b3b-98eb-d8f73aa30580
+using ReverseDiff #Automatic differentiation backend
+
 # ╔═╡ 1642dbda-4915-4e29-beff-bca592f3ec8d
-begin
-    using EpiAware
-    using Turing
-    using Distributions
-    using StatsPlots, StatsPlots.PlotMeasures
-    using Random
-    using DynamicPPL
-    using Statistics
-    using DataFramesMeta
-    using LinearAlgebra
-    using Transducers
-    using ReverseDiff
-    using DelimitedFiles
+begin #Date utility and set Random seed
     using Dates
+    using Random
     Random.seed!(1)
 end
 
-# ╔═╡ a59d977c-0178-11ef-0063-83e30e0cf9f0
-begin
-    data = readdlm("south_korea_data.csv2", ','; header = true)
-    dates = data[1][:, 2] .|> Date
-    daily_cases = data[1][:, 3] .|> Integer
-end;
-
 # ╔═╡ 8a8d5682-2f89-443b-baf0-d4d3b134d311
 md"
 # Getting started with `EpiAware`
@@ -52,6 +54,12 @@ It is common to conceptualise the generative process of public health data, e.g
 `EpiAware` is built using the [`DynamicPPL`](https://github.com/TuringLang/DynamicPPL.jl) probabilistic programming domain-specific language, which is part of the [`Turing`](https://turinglang.org/dev/docs/using-turing/guide/) PPL. The structural concept behind `EpiAware` is that each module of an epidemiological model is a self-contained `Turing` [`Model`](https://turinglang.org/DynamicPPL.jl/stable/api/#DynamicPPL.Model-Tuple{}); that is each module is an object that can be conditioned on observable data and sampled from. A complete `EpiAware` model is the composition of these objects using the [`@submodel`](https://turinglang.org/DynamicPPL.jl/stable/api/#DynamicPPL.@submodel) macro.
 "
 
+# ╔═╡ 27d73202-a93e-4471-ab50-d59345304a0b
+md"
+## Dependencies for this notebook
+Now we want to import these dependencies into scope. If evaluating these code lines/blocks in REPL, then the REPL will offer to install any missing dependencies. Alternatively, you can add them to your active environment using `Pkg.add`.
+"
+
 # ╔═╡ 9161ab72-5c39-4a67-9762-e19f1c54c7fd
 md"
 ## Example: Early COVID-19 case data in South Korea
@@ -76,6 +84,18 @@ C_t \sim \text{NegBin}(\text{mean} = I_t,~ \text{overdispersion} = \phi).
 In the examples below we are going to largely recreate the _Mishra et al_ model, whilst emphasing that each component of the overall epidemiological model is, itself, a stand alone model that can be sampled from.
 "
 
+# ╔═╡ 1d3b9541-80ad-41b5-a5ed-a947f5c0731b
+md"
+## Load the data into scope
+First, we make sure that we have the data we want to analysis in scope by downloading it.
+"
+
+# ╔═╡ 4e5e0e24-8c55-4cb4-be3a-d28198f81a69
+url = "https://raw.githubusercontent.com/CDCgov/Rt-without-renewal/main/EpiAware/docs/src/showcase/replications/mishra-2020/south_korea_data.csv2"
+
+# ╔═╡ a59d977c-0178-11ef-0063-83e30e0cf9f0
+data = CSV.read(download(url), DataFrame)
+
 # ╔═╡ 104f4d16-7433-4a2d-89e7-288a9b223563
 md"
 ### Time-varying reproduction number as a `LatentModel` type
@@ -184,7 +204,7 @@ let
     twod_ar_mdl = generate_latent(twod_ar, 30)
     twod_ar_mdl_samples = mapreduce(hcat, 1:n_samples) do _
         θ = rand(twod_ar_mdl) #Sample unconditionally the underlying parameters of the model
-        gen = generated_quantities(twod_ar_mdl, θ)[1]
+        gen = generated_quantities(twod_ar_mdl, θ)
     end
 
     plot(twod_ar_mdl_samples,
@@ -327,7 +347,7 @@ plt_obs = let
     n_samples = 100
     obs_mdl_samples = mapreduce(hcat, 1:n_samples) do _
         θ = rand(obs_mdl) #Sample unconditionally the underlying parameters of the model
-        gen = generated_quantities(obs_mdl, θ)[1]
+        gen = generated_quantities(obs_mdl, θ)
     end
     scatter(obs_mdl_samples,
         lab = "",
@@ -401,8 +421,8 @@ We supply the data as a `NamedTuple` with the `y_t` field containing the observe
 "
 
 # ╔═╡ c7140b20-e030-4dc4-97bc-0efc0ff59631
-south_korea_data = (y_t = daily_cases[epi_prob.tspan[1]:epi_prob.tspan[2]],
-    dates = dates[epi_prob.tspan[1]:epi_prob.tspan[2]])
+south_korea_data = (y_t = data.cases_new[epi_prob.tspan[1]:epi_prob.tspan[2]],
+    dates = data.date[epi_prob.tspan[1]:epi_prob.tspan[2]])
 
 # ╔═╡ 9970adfd-ee88-4598-87a3-ffde5297031c
 md"
@@ -551,44 +571,53 @@ let
 end
 
 # ╔═╡ Cell order:
-# ╟─a59d977c-0178-11ef-0063-83e30e0cf9f0
-# ╟─34a06b3b-799b-48c5-bd08-1e57151f51ec
 # ╟─8a8d5682-2f89-443b-baf0-d4d3b134d311
+# ╟─34a06b3b-799b-48c5-bd08-1e57151f51ec
+# ╟─27d73202-a93e-4471-ab50-d59345304a0b
+# ╠═d63b37f0-9642-4c38-ac01-9ffe48d50441
+# ╠═74642759-35a5-4957-9f2b-544712866410
+# ╠═0c5f413e-d043-448d-8665-f0f6f705d70f
+# ╠═b1e2a759-a52b-4ee5-8db4-cfe848878c92
+# ╠═9eb03a0b-c6ca-4e23-8109-fb68f87d7fdf
+# ╠═97b5374e-7653-4b3b-98eb-d8f73aa30580
+# ╠═1642dbda-4915-4e29-beff-bca592f3ec8d
 # ╟─9161ab72-5c39-4a67-9762-e19f1c54c7fd
-# ╟─1642dbda-4915-4e29-beff-bca592f3ec8d
+# ╟─1d3b9541-80ad-41b5-a5ed-a947f5c0731b
+# ╠═4e5e0e24-8c55-4cb4-be3a-d28198f81a69
+# ╠═a59d977c-0178-11ef-0063-83e30e0cf9f0
 # ╟─104f4d16-7433-4a2d-89e7-288a9b223563
 # ╟─d201c82b-8efd-41e2-96d7-4f5e0c67088c
 # ╠═c88bbbd6-0101-4c04-97c9-c5887ef23999
 # ╟─40352cd6-3592-438b-b5d8-f56dcb1a4d27
 # ╟─31ee2757-0409-45df-b193-60c552797a3d
 # ╠═2bf22866-b785-4ee0-953d-ac990a197561
 # ╟─25e25125-8587-4451-8600-9b55a04dbcd9
-# ╟─fbe117b7-a0b8-4604-a5dd-e71a0a1a4fc3
+# ╠═fbe117b7-a0b8-4604-a5dd-e71a0a1a4fc3
 # ╟─9f84dec1-70f1-442e-8bef-a9494921549e
 # ╠═51a82a62-2c59-43c9-8562-69d15a7edfdd
-# ╟─d3938381-01b7-40c6-b369-a456ff6dba72
+# ╠═d3938381-01b7-40c6-b369-a456ff6dba72
 # ╟─12fd3bd5-657e-4b1a-aa88-6063419aaceb
 # ╠═61eac666-9fe4-4918-bd3f-68e89275d07a
-# ╟─5a96e7e9-0376-4365-8eb1-b2fad9be8fef
+# ╠═5a96e7e9-0376-4365-8eb1-b2fad9be8fef
 # ╟─6a9e871f-a2fa-4e41-af89-8b0b3c3b5b4b
 # ╠═c1fc1929-0624-45c0-9a89-86c8479b2675
 # ╠═99c9ba2c-20a5-4c7f-94d2-272d6c9d5904
-# ╟─71d08f7e-c409-4fbe-b154-b21d09010683
+# ╠═71d08f7e-c409-4fbe-b154-b21d09010683
 # ╟─4a2b5cf1-623c-4fe7-8365-49fb7972af5a
 # ╠═9e49d451-946b-430b-bcdb-1ef4bba55a4b
 # ╠═8487835e-d430-4300-bd7c-e33f5769ee32
 # ╟─2119319f-a2ef-4c96-82c4-3c7eaf40d2e0
 # ╟─51b5d5b6-3ad3-4967-ad1d-b1caee201fcb
 # ╠═9e564a6e-f521-41e8-8604-6a9d73af9ba7
 # ╠═72bdb47d-4967-4f20-9ae5-01f82e7b32c5
-# ╟─7a6d4b14-58d3-40c1-81f2-713c830f875f
+# ╠═7a6d4b14-58d3-40c1-81f2-713c830f875f
 # ╟─c8ef8a60-d087-4ae9-ae92-abeea5afc7ae
 # ╠═714908a1-dc85-476f-a99f-ec5c95a78b60
 # ╟─dacb8094-89a4-404a-8243-525c0dbfa482
 # ╠═d45f34e2-64f0-4828-ae0d-7b4cb3a3287d
 # ╠═2e0e8bf3-f34b-44bc-aa2d-046e1db6ee2d
 # ╠═55c639f6-b47b-47cf-a3d6-547e793c72bc
-# ╟─c3a62dda-e054-4c8c-b1b8-ba1b5c4447b3
+# ╠═c3a62dda-e054-4c8c-b1b8-ba1b5c4447b3
 # ╟─de5d96f0-4df6-4cc3-9f1d-156176b2b676
 # ╟─a06065e1-0e20-4cf8-8d5a-2d588da20bee
 # ╠═eaad5f46-e928-47c2-90ec-2cca3871c75d
@@ -600,6 +629,6 @@ end
 # ╟─9970adfd-ee88-4598-87a3-ffde5297031c
 # ╠═660a8511-4dd1-4788-9c14-fdd604bf83ad
 # ╟─5e6f505b-49fe-4ff4-ac2e-f6adcd445569
-# ╟─8b557bf1-f3dd-4f42-a250-ce965412eb32
+# ╠═8b557bf1-f3dd-4f42-a250-ce965412eb32
 # ╟─c05ed977-7a89-4ac8-97be-7078d69fce9f
-# ╟─ff21c9ec-1581-405f-8db1-0f522b5bc296
+# ╠═ff21c9ec-1581-405f-8db1-0f522b5bc296