Merge branch 'main' into prefix-method

CDCgov · Jul 5, 2024 · 7a768d7 · 7a768d7
2 parents b666062 + 26822f4
commit 7a768d7
Show file tree

Hide file tree

Showing 60 changed files with 789 additions and 217 deletions.
diff --git a/EpiAware/README.md b/EpiAware/README.md
@@ -5,90 +5,8 @@
 [![Test EpiAware](https://github.com/CDCgov/Rt-without-renewal/actions/workflows/test-EpiAware.yaml/badge.svg)](https://github.com/CDCgov/Rt-without-renewal/actions/workflows/test-EpiAware.yaml)
 [![codecov](https://codecov.io/gh/CDCgov/Rt-without-renewal/graph/badge.svg?token=IX4GIA8F0H)](https://codecov.io/gh/CDCgov/Rt-without-renewal)
 
-A `Julia` package for flexible and composable modeling and inference of the effective reproduction number (Rt) and other situational awareness signals in the presence of different latent generative processes and observation models.
+*An infectious disease situational awareness modelling toolkit for Julia.*
 
-## Installation instruction
+**Websites**: [Organization Website](https://cdcgov.github.io/Rt-without-renewal/dev/) | [Documentation](https://cdcgov.github.io/Rt-without-renewal/dev/)
 
-Eventually, `EpiAware` is likely to be added to the Julia registry. Until then, you can install it from the `/EpiAware` sub-directory of this repository by running the following command in the Julia REPL:
-
-```julia
-using Pkg; Pkg.add(url="https://github.com/CDCgov/Rt-without-renewal", subdir="EpiAware")
-```
-
-## Model Diagram
-
-- Solid lines indicate implemented features/analysis.
-- Dashed lines indicate planned features/analysis.
-
-## Current `EpiAware` model diagram
-```mermaid
-flowchart LR
-
-A["Underlying GI
-Bijector"]
-
-EpiModel["AbstractTuringEpiModel
-----------------------
-Choice of target
-for latent process:
-
-DirectInfections
-    ExpGrowthRate
-    Renewal"]
-
-InitModel["Priors for
-initial scale of incidence"]
-
-DataW[Data wrangling and QC]
-
-
-ObsData["Observational Data
----------------------
-Obs. cases y_t"]
-
-LatentProcPriors["Latent process priors"]
-
-LatentProc["AbstractTuringLatentModel
----------------------
-RandomWalk"]
-
-ObsModelPriors["Observation model priors
-choice of delayed obs. model"]
-
-ObsModel["AbstractObservationModel
----------------------
-DelayObservations"]
-
-E["Turing model constructor
----------------------
-generate_epiaware"]
-
-G[Posterior draws]
-H[Posterior checking]
-I[Post-processing]
-
-
-
-A --> EpiData
-EpiData --> EpiModel
-InitModel --> EpiModel
-EpiModel -->E
-ObsData-->E
-DataW-.->ObsData
-LatentProcPriors-->LatentProc
-LatentProc-->E
-ObsModelPriors-->ObsModel
-ObsModel-->E
-
-
-E-->|sample...NUTS...| G
-G-.->H
-H-.->I
-```
-
-## Pluto scripts
-
-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.
-
-## Opinionated guide to using Julia for project development
-Some user and potential contributors may not be familiar with using Julia for, or part of, project development. In documentation we give our opinions on how to use Julia for project development focussing on Julia version control with the command line tool `juliaup`, typical patterns for using stacked environments and useful settings for development using the Julia extension of VS-Code as an interactive development environment (IDE) for Julia project. Please find the documentation [here](https://cdcgov.github.io/Rt-without-renewal/dev/man/getting-started-julia/).
+EpiAware Organization Stats: ![EpiAware Stars](https://img.shields.io/github/stars/EpiAware?style=social)
diff --git a/EpiAware/docs/make.jl b/EpiAware/docs/make.jl
@@ -1,19 +1,31 @@
 using Documenter
 using EpiAware
+using EpiAware.EpiAwareBase
+using EpiAware.EpiAwareUtils
+using EpiAware.EpiInference
+using EpiAware.EpiInfModels
+using EpiAware.EpiLatentModels
+using EpiAware.EpiObsModels
 using Pluto: Configuration.CompilerOptions
 using PlutoStaticHTML
 
 include("changelog.jl")
 include("pages.jl")
 include("build.jl")
 
-build("examples")
+build("getting-started")
+build("getting-started/tutorials")
+build("showcase/replications/mishra-2020")
+
+DocMeta.setdocmeta!(EpiAware, :DocTestSetup, :(using EpiAware); recursive = true)
 
 makedocs(; sitename = "EpiAware.jl",
     authors = "Samuel Brand, Zachary Susswein, Sam Abbott, and contributors",
-    clean = true, doctest = true, linkcheck = true,
+    clean = true, doctest = false, linkcheck = true,
     warnonly = [:docs_block, :missing_docs, :linkcheck, :autodocs_block],
-    modules = [EpiAware],
+    modules = [
+        EpiAware, EpiAware.EpiAwareBase, EpiAware.EpiAwareUtils, EpiAware.EpiInference,
+        EpiAware.EpiInfModels, EpiAware.EpiLatentModels, EpiAware.EpiObsModels],
     pages = pages,
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true",

diff --git a/EpiAware/docs/pages.jl b/EpiAware/docs/pages.jl
@@ -1,18 +1,88 @@
-pages = [
-    "EpiAware.jl: Real-time epidemic monitoring" => "index.md",
-    "Manual" => Any[
-        "Getting Started with using Julia in Projects" => "man/getting-started-julia.md",
-        "Examples" => [
-            "Getting started" => "examples/getting_started.md"
-        ]
+getting_started_pages = Any[
+    "Overview" => "getting-started/index.md",
+    "Installation" => "getting-started/installation.md",
+    "Quickstart" => "getting-started/quickstart.md",
+    "Frequently asked questions" => "getting-started/faq.md",
+    "Explainers" => [
+        "Overview" => "getting-started/explainers/index.md",
+        "Working with Julia" => "getting-started/explainers/julia.md",
+        "Introduction to EpiAware" => "getting-started/explainers/intro.md",
+        "Modelling infections" => "getting-started/explainers/modelling-infections.md",
+        "Inference" => "getting-started/explainers/inference.md",
+        "Latent models" => "getting-started/explainers/latent-models.md",
+        "Observation models" => "getting-started/explainers/observation-models.md"
+    ],
+    "Tutorials" => [
+        "Overview" => "getting-started/tutorials/index.md",
+        "Simple renewal with delays" => "getting-started/tutorials/simple-renewal-with-delays.md",
+        "Nowcasting" => "getting-started/tutorials/nowcasting.md",
+        "Multiple observation models" => "getting-started/tutorials/multiple-observation-models.md",
+        "Multiple infection processes" => "getting-started/tutorials/multiple-infection-processes.md",
+        "Partial pooling" => "getting-started/tutorials/partial-pooling.md"
+    ]
+]
+
+showcase_pages = Any[
+    "Overview" => "showcase/index.md",
+    "Replication" => [
+        "On the derivation of the renewal equation from an age-dependent branching process: an epidemic modelling perspective" => "showcase/replications/mishra-2020/index.md"
+    ]
+]
+
+what_is_pages = [
+    "Overview" => "overview.md"
+]
+
+module_pages = Any[
+    "EpiAware" => [
+        "Overview" => "lib/index.md",
+        "Public API" => "lib/public.md",
+        "Internal API" => "lib/internals.md"
+    ],
+    "EpiAwareBase" => [
+        "Overview" => "lib/EpiAwareBase/index.md",
+        "Public API" => "lib/EpiAwareBase/public.md",
+        "Internal API" => "lib/EpiAwareBase/internals.md"
     ],
-    "Reference" => Any[
-        "Public API" => "lib/public.md"
+    "EpiAwareUtils" => [
+        "Overview" => "lib/EpiAwareUtils/index.md",
+        "Public API" => "lib/EpiAwareUtils/public.md",
+        "Internal API" => "lib/EpiAwareUtils/internals.md"
     ],
-    "Developers" => [
-        "Contributing" => "man/contributing.md",
-        "Release checklist" => "checklist.md",
-        "Internals" => "lib/internals.md"
+    "EpiInference" => [
+        "Overview" => "lib/EpiInference/index.md",
+        "Public API" => "lib/EpiInference/public.md",
+        "Internal API" => "lib/EpiInference/internals.md"
     ],
+    "EpiInfModels" => [
+        "Overview" => "lib/EpiInfModels/index.md",
+        "Public API" => "lib/EpiInfModels/public.md",
+        "Internal API" => "lib/EpiInfModels/internals.md"
+    ],
+    "EpiLatentModels" => [
+        "Overview" => "lib/EpiLatentModels/index.md",
+        "Public API" => "lib/EpiLatentModels/public.md",
+        "Internal API" => "lib/EpiLatentModels/internals.md"
+    ],
+    "EpiObsModels" => [
+        "Overview" => "lib/EpiObsModels/index.md",
+        "Public API" => "lib/EpiObsModels/public.md",
+        "Internal API" => "lib/EpiObsModels/internals.md"
+    ]
+]
+
+developer_pages = [
+    "Overview" => "developer/index.md",
+    "Contributing" => "developer/contributing.md",
+    "Release checklist" => "developer/checklist.md"
+]
+
+pages = [
+    "EpiAware.jl: Real-time infectious disease monitoring" => "index.md",
+    "Getting started" => getting_started_pages,
+    "Showcase" => showcase_pages,
+    "What is EpiAware?" => what_is_pages,
+    "Modules" => module_pages,
+    "Developers" => developer_pages,
     "release-notes.md"
 ]
diff --git a/EpiAware/docs/src/checklist.md → EpiAware/docs/src/developer/checklist.md b/EpiAware/docs/src/checklist.md → EpiAware/docs/src/developer/checklist.md
diff --git a/EpiAware/docs/src/man/contributing.md → EpiAware/docs/src/developer/contributing.md b/EpiAware/docs/src/man/contributing.md → EpiAware/docs/src/developer/contributing.md
@@ -16,11 +16,11 @@ Feel free to nominate commits that should be backported by opening an issue. Req
 
 ### `release-*` branches
 
-  * Each new minor version `x.y.0` gets a branch called `release-x.y` (a [protected branch](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)).
-  * New versions are usually tagged only from the `release-x.y` branches.
-  * For patch releases, changes get backported to the `release-x.y` branch via a single PR with the standard name "Backports for x.y.z" and label ["Type: Backport"](https://github.com/JuliaDocs/Documenter.jl/pulls?q=label%3A%22Type%3A+Backport%22). The PR message links to all the PRs that are providing commits to the backport. The PR gets merged as a merge commit (i.e. not squashed).
-  * The old `release-*` branches may be removed once they have outlived their usefulness.
-  * Patch version [milestones](https://github.com/CDCgov/Rt-without-renewal/milestones) are used to keep track of which PRs get backported etc.
+* Each new minor version `x.y.0` gets a branch called `release-x.y` (a [protected branch](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)).
+* New versions are usually tagged only from the `release-x.y` branches.
+* For patch releases, changes get backported to the `release-x.y` branch via a single PR with the standard name "Backports for x.y.z" and label ["Type: Backport"](https://github.com/JuliaDocs/Documenter.jl/pulls?q=label%3A%22Type%3A+Backport%22). The PR message links to all the PRs that are providing commits to the backport. The PR gets merged as a merge commit (i.e. not squashed).
+* The old `release-*` branches may be removed once they have outlived their usefulness.
+* Patch version [milestones](https://github.com/CDCgov/Rt-without-renewal/milestones) are used to keep track of which PRs get backported etc.
 
 ## Style Guide
 

diff --git a/EpiAware/docs/src/developer/index.md b/EpiAware/docs/src/developer/index.md
@@ -0,0 +1,3 @@
+# [Developer documentation](@id developer)
+
+Welcome to the `EpiAware` developer documentation! This section is designed to help you get started with developing the package.
diff --git a/EpiAware/docs/src/getting-started/explainers/index.md b/EpiAware/docs/src/getting-started/explainers/index.md
@@ -0,0 +1,3 @@
+# Explainers
+
+This section contains a series of explainers that provide a detailed overview of the EpiAware platform and its features. These explainers are designed to help you understand the platform and its capabilities, and to provide you with the information you need to get started using EpiAware. See the sidebar for the list of explainers.
diff --git a/EpiAware/docs/src/getting-started/explainers/inference.md b/EpiAware/docs/src/getting-started/explainers/inference.md
@@ -0,0 +1 @@
+# Inference
diff --git a/EpiAware/docs/src/getting-started/explainers/interfaces.md b/EpiAware/docs/src/getting-started/explainers/interfaces.md
@@ -0,0 +1,25 @@
+# Interfaces
+
+We support two primary workflows for using the package:
+
+- `EpiProblem`: A high-level interface for defining and fitting models to data. This is the recommended way to use the package.
+- `Turing` interface: A lower-level interface for defining and fitting models to data. This is the more flexible way to use the package and may also be more familiar to users of `Turing.jl`.
+
+See the getting started section for tutorials on each of these workflows.
+
+## EpiProblem
+
+Each module of the overall epidemiological model we are interested in is a `Turing` `Model` in its own right. In this section, we compose the individual models into the full epidemiological model using the `EpiProblem` struct.
+
+The constructor for an `EpiProblem` requires:
+
+- An `epi_model`.
+- A `latent_model`.
+- An `observation_model`.
+- A `tspan`.
+
+The `tspan` set the range of the time index for the models.
+
+## Turing interface
+
+The `Turing` interface is a lower-level interface for defining and fitting models to data. This is the more flexible way to use the package and may also be more familiar to users of `Turing.jl`.
diff --git a/EpiAware/docs/src/getting-started/explainers/intro.md b/EpiAware/docs/src/getting-started/explainers/intro.md
@@ -0,0 +1,68 @@
+# Introduction
+
+The diagram below shows the relationship between the modules in the package for a typical workflow.
+
+```mermaid
+flowchart LR
+
+A["Underlying GI
+Bijector"]
+
+EpiModel["AbstractTuringEpiModel
+----------------------
+Choice of target
+for latent process:
+
+DirectInfections
+    ExpGrowthRate
+    Renewal"]
+
+InitModel["Priors for
+initial scale of incidence"]
+
+DataW[Data wrangling and QC]
+
+
+ObsData["Observational Data
+---------------------
+Obs. cases y_t"]
+
+LatentProcPriors["Latent process priors"]
+
+LatentProc["AbstractTuringLatentModel
+---------------------
+RandomWalk"]
+
+ObsModelPriors["Observation model priors
+choice of delayed obs. model"]
+
+ObsModel["AbstractObservationModel
+---------------------
+DelayObservations"]
+
+E["Turing model constructor
+---------------------
+generate_epiaware"]
+
+G[Posterior draws]
+H[Posterior checking]
+I[Post-processing]
+
+
+
+A --> EpiData
+EpiData --> EpiModel
+InitModel --> EpiModel
+EpiModel -->E
+ObsData-->E
+DataW-.->ObsData
+LatentProcPriors-->LatentProc
+LatentProc-->E
+ObsModelPriors-->ObsModel
+ObsModel-->E
+
+
+E-->|sample...NUTS...| G
+G-->H
+H-->I
+```
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# [Developer documentation](@id developer)

		Welcome to the `EpiAware` developer documentation! This section is designed to help you get started with developing the package.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Explainers

		This section contains a series of explainers that provide a detailed overview of the EpiAware platform and its features. These explainers are designed to help you understand the platform and its capabilities, and to provide you with the information you need to get started using EpiAware. See the sidebar for the list of explainers.