From 30a26b64176e64dd834f538a9032d735fd46cfaf Mon Sep 17 00:00:00 2001 From: Sam Date: Mon, 1 Jul 2024 12:46:56 +0100 Subject: [PATCH] final reorg --- EpiAware/README.md | 17 ++-------- EpiAware/docs/pages.jl | 31 +++++++++++++------ .../src/man/getting-started/installation.md | 7 +++++ .../src/man/getting-started/quickstart.md | 3 ++ .../man/getting-started/tips-and-tricks.md | 9 ++++++ .../epidemic-modelling.md} | 0 .../getting-started/tutorials/inference.md | 0 .../getting-started/tutorials/interfaces.md | 27 ++++++++++++++++ .../intro.md} | 17 ++-------- .../julia.md | 0 .../tutorials/latent-models.md | 0 .../tutorials/observation-models.md | 0 .../getting-started/tutorials/quickstart.md | 0 EpiAware/docs/src/man/overview.md | 4 ++- .../{ => replication}/mishra-2020/get_data.R | 0 .../{ => replication}/mishra-2020/index.jl | 0 .../mishra-2020/south_korea_data.csv2 | 0 17 files changed, 76 insertions(+), 39 deletions(-) create mode 100644 EpiAware/docs/src/man/getting-started/installation.md create mode 100644 EpiAware/docs/src/man/getting-started/quickstart.md create mode 100644 EpiAware/docs/src/man/getting-started/tips-and-tricks.md rename EpiAware/docs/src/man/getting-started/{index.md => tutorials/epidemic-modelling.md} (100%) create mode 100644 EpiAware/docs/src/man/getting-started/tutorials/inference.md create mode 100644 EpiAware/docs/src/man/getting-started/tutorials/interfaces.md rename EpiAware/docs/src/man/getting-started/{new-user-tutorials/EpiProblem-interface.md => tutorials/intro.md} (69%) rename EpiAware/docs/src/man/getting-started/{new-user-tutorials => tutorials}/julia.md (100%) create mode 100644 EpiAware/docs/src/man/getting-started/tutorials/latent-models.md create mode 100644 EpiAware/docs/src/man/getting-started/tutorials/observation-models.md create mode 100644 EpiAware/docs/src/man/getting-started/tutorials/quickstart.md rename EpiAware/docs/src/man/showcase/{ => replication}/mishra-2020/get_data.R (100%) rename EpiAware/docs/src/man/showcase/{ => replication}/mishra-2020/index.jl (100%) rename EpiAware/docs/src/man/showcase/{ => replication}/mishra-2020/south_korea_data.csv2 (100%) diff --git a/EpiAware/README.md b/EpiAware/README.md index 0b45306d6..ba41aa0f2 100644 --- a/EpiAware/README.md +++ b/EpiAware/README.md @@ -5,19 +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. +*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") -`` -## 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/pages.jl b/EpiAware/docs/pages.jl index 53cdfbdb0..8858d6d52 100644 --- a/EpiAware/docs/pages.jl +++ b/EpiAware/docs/pages.jl @@ -1,11 +1,24 @@ 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" => Any[ + "Installation" => "getting-started/installation.md", + "Quickstart" => "getting-started/quickstart.md", + "Tips and Tricks" => "getting-started/tips-and-tricks.md", + "Tutorials" => [ + "Working with Julia" => "getting-started/tutorials/julia.md", + "Introduction to EpiAware" => "getting-started/tutorials/intro.md", + "Epidemic modelling" => "getting-started/tutorials/epidemic-modelling.md", + "Inference" => "getting-started/tutorials/inference.md", + "Latent models" => "getting-started/tutorials/latent-models.md", + "Observation models" => "getting-started/tutorials/observation-models.md" ] ], + "Showcase" => [ + "Replication" => [ + "On the derivation of the renewal equation from an age-dependent branching process: an epidemic modelling perspective" => "showcase/replication/mishra-2020/index.md" + ] + ], + "What is EpiAware?" => ["overview.md"], "Modules" => [ "EpiAware" => "lib/EpiAwareBase/index.md", "EpiAwareUtils" => "lib/EpiAwareUtils/index.md", @@ -13,14 +26,14 @@ pages = [ "EpiInfModels" => "lib/EpiInfModels/index.md", "EpiLatentModels" => "lib/EpiLatentModels/index.md", "EpiObsModels" => "lib/EpiObsModels/index.md" + "EpiAware" => [ + "Public API" => "lib/public.md", + "Internal API" => "lib/internals.md" + ] ], - "Reference" => Any[ - "Public API" => "lib/public.md", - "Internal API" => "lib/internals.md"], "Developers" => [ "Contributing" => "man/contributing.md", - "Release checklist" => "checklist.md", - "Internals" => "lib/internals.md" + "Release checklist" => "checklist.md" ], "release-notes.md" ] diff --git a/EpiAware/docs/src/man/getting-started/installation.md b/EpiAware/docs/src/man/getting-started/installation.md new file mode 100644 index 000000000..5fe4f6dfa --- /dev/null +++ b/EpiAware/docs/src/man/getting-started/installation.md @@ -0,0 +1,7 @@ +# Installation + +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") +``` diff --git a/EpiAware/docs/src/man/getting-started/quickstart.md b/EpiAware/docs/src/man/getting-started/quickstart.md new file mode 100644 index 000000000..7de815ab3 --- /dev/null +++ b/EpiAware/docs/src/man/getting-started/quickstart.md @@ -0,0 +1,3 @@ +# Quickstart + +Get up and running with EpiAware in just a few minutes using this quickstart guide. diff --git a/EpiAware/docs/src/man/getting-started/tips-and-tricks.md b/EpiAware/docs/src/man/getting-started/tips-and-tricks.md new file mode 100644 index 000000000..2e6820d8f --- /dev/null +++ b/EpiAware/docs/src/man/getting-started/tips-and-tricks.md @@ -0,0 +1,9 @@ +# Tips and tricks + +```@index +Pages = ["lib/getting-started/tips-and-tricks.md"] +``` + +## 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. diff --git a/EpiAware/docs/src/man/getting-started/index.md b/EpiAware/docs/src/man/getting-started/tutorials/epidemic-modelling.md similarity index 100% rename from EpiAware/docs/src/man/getting-started/index.md rename to EpiAware/docs/src/man/getting-started/tutorials/epidemic-modelling.md diff --git a/EpiAware/docs/src/man/getting-started/tutorials/inference.md b/EpiAware/docs/src/man/getting-started/tutorials/inference.md new file mode 100644 index 000000000..e69de29bb diff --git a/EpiAware/docs/src/man/getting-started/tutorials/interfaces.md b/EpiAware/docs/src/man/getting-started/tutorials/interfaces.md new file mode 100644 index 000000000..52319daba --- /dev/null +++ b/EpiAware/docs/src/man/getting-started/tutorials/interfaces.md @@ -0,0 +1,27 @@ + +# 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/man/getting-started/new-user-tutorials/EpiProblem-interface.md b/EpiAware/docs/src/man/getting-started/tutorials/intro.md similarity index 69% rename from EpiAware/docs/src/man/getting-started/new-user-tutorials/EpiProblem-interface.md rename to EpiAware/docs/src/man/getting-started/tutorials/intro.md index 4e60f72c8..c7620f272 100644 --- a/EpiAware/docs/src/man/getting-started/new-user-tutorials/EpiProblem-interface.md +++ b/EpiAware/docs/src/man/getting-started/tutorials/intro.md @@ -1,16 +1,3 @@ -# Getting Started: EpiProblem Interface - -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. - The diagram below shows the relationship between the modules in the package for a typical workflow. ```mermaid @@ -74,6 +61,6 @@ ObsModel-->E E-->|sample...NUTS...| G -G-.->H -H-.->I +G-->H +H-->I ``` diff --git a/EpiAware/docs/src/man/getting-started/new-user-tutorials/julia.md b/EpiAware/docs/src/man/getting-started/tutorials/julia.md similarity index 100% rename from EpiAware/docs/src/man/getting-started/new-user-tutorials/julia.md rename to EpiAware/docs/src/man/getting-started/tutorials/julia.md diff --git a/EpiAware/docs/src/man/getting-started/tutorials/latent-models.md b/EpiAware/docs/src/man/getting-started/tutorials/latent-models.md new file mode 100644 index 000000000..e69de29bb diff --git a/EpiAware/docs/src/man/getting-started/tutorials/observation-models.md b/EpiAware/docs/src/man/getting-started/tutorials/observation-models.md new file mode 100644 index 000000000..e69de29bb diff --git a/EpiAware/docs/src/man/getting-started/tutorials/quickstart.md b/EpiAware/docs/src/man/getting-started/tutorials/quickstart.md new file mode 100644 index 000000000..e69de29bb diff --git a/EpiAware/docs/src/man/overview.md b/EpiAware/docs/src/man/overview.md index 39cedbd69..4c8515ede 100644 --- a/EpiAware/docs/src/man/overview.md +++ b/EpiAware/docs/src/man/overview.md @@ -1,6 +1,8 @@ [Overview of the EpiAware Software Ecosystem](@id overview) -`EpiAware` is not a standard toolkit for infectious disease modelling. Rather it seeks to be highly modular and composable for advanced users whilst still providing opinionated workflows for those who are new to the field. Developed by the authors behind other widely used infectious disease modelling packages such as `EpiNow2`, `epinowcast`, and `epidist`, alongside experts in infectious disease modelling in Julia,`EpiAware` is designed to go beyond the capabilities of these packages by providing a more flexible and extensible framework for modelling and inference of infectious disease dynamics. +_`EpiAware` is not a standard toolkit for infectious disease modelling._ + +It seeks to be highly modular and composable for advanced users whilst still providing opinionated workflows for those who are new to the field. Developed by the authors behind other widely used infectious disease modelling packages such as `EpiNow2`, `epinowcast`, and `epidist`, alongside experts in infectious disease modelling in Julia,`EpiAware` is designed to go beyond the capabilities of these packages by providing a more flexible and extensible framework for modelling and inference of infectious disease dynamics. ## Package Features diff --git a/EpiAware/docs/src/man/showcase/mishra-2020/get_data.R b/EpiAware/docs/src/man/showcase/replication/mishra-2020/get_data.R similarity index 100% rename from EpiAware/docs/src/man/showcase/mishra-2020/get_data.R rename to EpiAware/docs/src/man/showcase/replication/mishra-2020/get_data.R diff --git a/EpiAware/docs/src/man/showcase/mishra-2020/index.jl b/EpiAware/docs/src/man/showcase/replication/mishra-2020/index.jl similarity index 100% rename from EpiAware/docs/src/man/showcase/mishra-2020/index.jl rename to EpiAware/docs/src/man/showcase/replication/mishra-2020/index.jl diff --git a/EpiAware/docs/src/man/showcase/mishra-2020/south_korea_data.csv2 b/EpiAware/docs/src/man/showcase/replication/mishra-2020/south_korea_data.csv2 similarity index 100% rename from EpiAware/docs/src/man/showcase/mishra-2020/south_korea_data.csv2 rename to EpiAware/docs/src/man/showcase/replication/mishra-2020/south_korea_data.csv2