diff --git a/.github/workflows/document-EpiAware.yaml b/.github/workflows/document-EpiAware.yaml new file mode 100644 index 000000000..4039ef4c9 --- /dev/null +++ b/.github/workflows/document-EpiAware.yaml @@ -0,0 +1,30 @@ +name: Documenter +on: + push: + branches: main + tags: [v*] + pull_request: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + Documenter: + permissions: + contents: write + statuses: write + name: Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + sparse-checkout: EpiAware + sparse-checkout-cone-mode: false + - name: Move EpiAware to root + run: mv EpiAware/* . + - uses: julia-actions/cache@v1 + - uses: julia-actions/julia-buildpkg@v1 + - uses: julia-actions/julia-docdeploy@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/test-EpiAware.yaml b/.github/workflows/test-EpiAware.yaml index fa84c6389..d370db35f 100644 --- a/.github/workflows/test-EpiAware.yaml +++ b/.github/workflows/test-EpiAware.yaml @@ -16,7 +16,7 @@ jobs: strategy: fail-fast: true matrix: - julia-version: ['1'] + julia-version: ['1.10', '1'] os: [ubuntu-latest, windows-latest, macOS-latest] steps: - uses: actions/checkout@v4 diff --git a/.gitignore b/.gitignore index c52aed962..ffa29724b 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,7 @@ # Julia **/Manifest.toml - +**/*_files # Data *.csv *.tsv @@ -62,7 +62,6 @@ dist/ downloads/ eggs/ .eggs/ -lib/ lib64/ parts/ sdist/ @@ -256,9 +255,6 @@ vignettes/*.pdf # R Environment Variables .Renviron -# pkgdown site -docs/ - # translation temp files po/*~ diff --git a/EpiAware/.gitignore b/EpiAware/.gitignore index 0bea468c2..1f2e36495 100644 --- a/EpiAware/.gitignore +++ b/EpiAware/.gitignore @@ -4,7 +4,8 @@ # such, it should not be committed for packages, but should be committed for # applications that require a static environment. **/Manifest.toml -docs +docs/build +!docs/lib/* # Data *.csv diff --git a/EpiAware/CHANGELOG.md b/EpiAware/CHANGELOG.md new file mode 100644 index 000000000..7e9705ae3 --- /dev/null +++ b/EpiAware/CHANGELOG.md @@ -0,0 +1,12 @@ +# Release notes + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Unreleased + +### Added + +### Changed + +### Fixed diff --git a/EpiAware/Project.toml b/EpiAware/Project.toml index 5508f766d..cb35f98bc 100644 --- a/EpiAware/Project.toml +++ b/EpiAware/Project.toml @@ -30,4 +30,4 @@ Random = "1.9" ReverseDiff = "1.15" SparseArrays = "1.10" Turing = "0.30" -julia = "1.9" +julia = "1.10" diff --git a/EpiAware/README.md b/EpiAware/README.md index 29b2152d6..2f3094098 100644 --- a/EpiAware/README.md +++ b/EpiAware/README.md @@ -1,9 +1,12 @@ -# EpiAware +# EpiAware.jl [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle) +![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg) [![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. + ## Model Diagram - Solid lines indicate implemented features/analysis. diff --git a/EpiAware/docs/Project.toml b/EpiAware/docs/Project.toml new file mode 100644 index 000000000..3d7eeda93 --- /dev/null +++ b/EpiAware/docs/Project.toml @@ -0,0 +1,4 @@ +[deps] +Changelog = "5217a498-cd5d-4ec6-b8c2-9b85a09b6e3e" +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +EpiAware = "b2eeebe4-5992-4301-9193-7ebc9f62c855" diff --git a/EpiAware/docs/changelog.jl b/EpiAware/docs/changelog.jl new file mode 100644 index 000000000..c6649f3dd --- /dev/null +++ b/EpiAware/docs/changelog.jl @@ -0,0 +1,9 @@ +# Generate a Documenter-friendly changelog from CHANGELOG.md +using Changelog + +Changelog.generate( + Changelog.Documenter(), + joinpath(@__DIR__, "..", "CHANGELOG.md"), + joinpath(@__DIR__, "src", "release-notes.md"); + repo = "JuliaDocs/Documenter.jl" +) diff --git a/EpiAware/docs/make.jl b/EpiAware/docs/make.jl new file mode 100644 index 000000000..edc0449fc --- /dev/null +++ b/EpiAware/docs/make.jl @@ -0,0 +1,22 @@ +using Documenter +using EpiAware + +include("changelog.jl") +include("pages.jl") + +makedocs(; sitename = "EpiAware.jl", + authors = "Samuel Brand, Zachary Susswein, Sam Abbott, and contributors", + clean = true, doctest = true, linkcheck = true, + warnonly = [:docs_block, :missing_docs], + modules = [EpiAware], + pages = pages, + format = Documenter.HTML( + prettyurls = get(ENV, "CI", nothing) == "true" + ) +) + +deploydocs( + repo = "github.com/CDCgov/Rt-without-renewal.git", + target = "build", + push_preview = true +) diff --git a/EpiAware/docs/pages.jl b/EpiAware/docs/pages.jl new file mode 100644 index 000000000..db333fa73 --- /dev/null +++ b/EpiAware/docs/pages.jl @@ -0,0 +1,18 @@ +pages = [ + "EpiAware.jl: Real-time epidemic monitoring" => "index.md", + "Manual" => Any[ + "Guide" => "man/guide.md", + "Examples" => [ + "Getting started" => "man/getting-started.md" + ] + ], + "Reference" => Any[ + "Public API" => "lib/public.md" + ], + "Developers" => [ + "Contributing" => "contributing.md", + "Release checklist" => "checklist.md", + "Internals" => "lib/internals.md" + ], + "release-notes.md" +] diff --git a/EpiAware/docs/src/checklist.md b/EpiAware/docs/src/checklist.md new file mode 100644 index 000000000..775e968c4 --- /dev/null +++ b/EpiAware/docs/src/checklist.md @@ -0,0 +1,35 @@ +# Checklists + +The purpose of this page is to collate a series of checklists for commonly +performed changes to the source code of EpiAware. It has been adapted from `Documenter.jl`. + +In each case, copy the checklist into the description of the pull request. + +## Making a release + +In preparation for a release, use the following checklist. These steps should be performed on a branch with an open pull request, either for a topic branch, or for a new branch `release-1.y.z` ("Release version 1.y.z") if multiple changes have accumulated on the `master` branch since the last release. + +```markdown +## Pre-release + + - [ ] Change the version number in `Project.toml` + * If the release is breaking, increment MAJOR + * If the release adds a new user-visible feature, increment MINOR + * Otherwise (bug-fixes, documentation improvements), increment PATCH + - [ ] Update `CHANGELOG.md`, following the existing style (in particular, make sure that the change log for this version has the correct version number and date). + - [ ] Run `make changelog`, to make sure that all the issue references in `CHANGELOG.md` are up to date. + - [ ] Check that the commit messages in this PR do not contain `[ci skip]` + - [ ] Run https://github.com/JuliaDocs/Documenter.jl/actions/workflows/regression-tests.yml + using a `workflow_dispatch` trigger to check for any changes that broke extensions. + +## The release + + - [ ] After merging the pull request, tag the release. There are two options for this: + + 1. [Comment `[at]JuliaRegistrator register` on the GitHub commit.](https://github.com/JuliaRegistries/Registrator.jl#via-the-github-app) + 2. Use [JuliaHub's package registration feature](https://help.juliahub.com/juliahub/stable/contribute/#registrator) to trigger the registration. + + Either of those should automatically publish a new version to the Julia registry. + - Once registered, the `TagBot.yml` workflow should create a tag, and rebuild the documentation for this tag. + - These steps can take quite a bit of time (1 hour or more), so don't be surprised if the new documentation takes a while to appear. +``` diff --git a/EpiAware/docs/src/contributing.md b/EpiAware/docs/src/contributing.md new file mode 100644 index 000000000..d54426632 --- /dev/null +++ b/EpiAware/docs/src/contributing.md @@ -0,0 +1,41 @@ +# Contributing + +This page details the some of the guidelines that should be followed when contributing to this package. It is adapted from `Documenter.jl`. + +## Branches + +`release-*` branches are used for tagged minor versions of this package. This follows the same approach used in the main Julia repository, albeit on a much more modest scale. + +Please open pull requests against the `master` branch rather than any of the `release-*` branches whenever possible. + +### Backports + +Bug fixes are backported to the `release-*` branches using `git cherry-pick -x` by a EpiAware member and will become available in point releases of that particular minor version of the package. + +Feel free to nominate commits that should be backported by opening an issue. Requests for new point releases to be tagged in `METADATA.jl` can also be made in the same way. + +### `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. + +## Style Guide + +Follow the style of the surrounding text when making changes. When adding new features please try to stick to the following points whenever applicable. This project follows the +[SciML style guide](https://github.com/SciML/SciMLStyle). + +## Tests + +### Unit tests + +As is conventional for Julia packages, unit tests are located at `test/*.jl` with the entrypoint +`test/runtests.jl`. + +### End to end testing + +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. diff --git a/EpiAware/docs/src/index.md b/EpiAware/docs/src/index.md new file mode 100644 index 000000000..a9b7be685 --- /dev/null +++ b/EpiAware/docs/src/index.md @@ -0,0 +1,36 @@ +# EpiAware.jl + +*Infectious disease situational awareness modelling toolkit for Julia.* + +A package for building and fitting situational awareness models for infectious diseases. The package is designed to be flexible and extensible, and to provide a consistent interface for fitting and simulating models. + +## Package Features + +- **Flexible**: The package is designed to be flexible and extensible, and to provide a consistent interface for fitting and simulating models. +- **Modular**: The package is designed to be modular, with a clear separation between the model and the data. +- **Extensible**: The package is designed to be extensible, with a clear separation between the model and the data. +- **Consistent**: The package is designed to provide a consistent interface for fitting and simulating models. +- **Efficient**: The package is designed to be efficient, with a clear separation between the model and the data. + +See the [Index](@ref main-index) for the complete list of documented functions and types. + +## Manual Outline + +```@contents +Pages = [ + "man/contributing.md", +] +Depth = 1 +``` + +## Library Outline + +```@contents +Pages = ["lib/public.md", "lib/internals.md"] +``` + +### [Index](@id main-index) + +```@index +Pages = ["lib/public.md"] +``` diff --git a/EpiAware/docs/src/lib/internals.md b/EpiAware/docs/src/lib/internals.md new file mode 100644 index 000000000..57ae28f36 --- /dev/null +++ b/EpiAware/docs/src/lib/internals.md @@ -0,0 +1,23 @@ +# internal Documentation + +Documentation for `EpiAware.jl`'s internal interface. + +## Contents + +```@contents +Pages = ["internal.md"] +Depth = 2:2 +``` + +## Index + +```@index +Pages = ["internals.md"] +``` + +## Internal API + +```@autodocs +Modules = [EpiAware] +Public = false +``` diff --git a/EpiAware/docs/src/lib/public.md b/EpiAware/docs/src/lib/public.md new file mode 100644 index 000000000..2055c84be --- /dev/null +++ b/EpiAware/docs/src/lib/public.md @@ -0,0 +1,20 @@ +# Public Documentation + +Documentation for `EpiAware.jl`'s public interface. + +See the Internals section of the manual for internal package docs covering all submodules. + +## Contents + +```@contents +Pages = ["public.md"] +Depth = 2:2 +``` + +## Index + +```@index +Pages = ["public.md"] +``` + +## Public API diff --git a/EpiAware/docs/src/man/getting-started.md b/EpiAware/docs/src/man/getting-started.md new file mode 100644 index 000000000..e69de29bb diff --git a/EpiAware/docs/src/man/guide.md b/EpiAware/docs/src/man/guide.md new file mode 100644 index 000000000..e69de29bb diff --git a/EpiAware/docs/src/release-notes.md b/EpiAware/docs/src/release-notes.md new file mode 100644 index 000000000..9a75d1049 --- /dev/null +++ b/EpiAware/docs/src/release-notes.md @@ -0,0 +1,16 @@ +```@meta +EditURL = "https://github.com/JuliaDocs/Documenter.jl/blob/master/CHANGELOG.md" +``` + +# Release notes + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Unreleased + +### Added + +### Changed + +### Fixed diff --git a/EpiAware/docs/versions.js b/EpiAware/docs/versions.js new file mode 100644 index 000000000..6cc415a92 --- /dev/null +++ b/EpiAware/docs/versions.js @@ -0,0 +1,3 @@ +// This is here just to make the version selector show up when you build Documenter's +// manual locally when developing / debugging. +var DOC_VERSIONS = ["build"]; diff --git a/EpiAware/src/EpiAware.jl b/EpiAware/src/EpiAware.jl index 2cc2286c5..796fdeaad 100644 --- a/EpiAware/src/EpiAware.jl +++ b/EpiAware/src/EpiAware.jl @@ -29,30 +29,26 @@ An epidemiological model in `EpiAware` consists of composable structs with core of infection and the time of observation as a convolution, followed by a negative binomial distributed sample. -## Imports - -$(IMPORTS) - -## Exports - -$(EXPORTS) - """ module EpiAware -using Distributions, Turing, LogExpFunctions, LinearAlgebra, SparseArrays, Random, - ReverseDiff, Optim, Parameters, QuadGK, DataFramesMeta, DocStringExtensions +using Distributions, Turing, LogExpFunctions, LinearAlgebra, SparseArrays, + Random, ReverseDiff, Optim, Parameters, QuadGK, DataFramesMeta, + DocStringExtensions -# Exported utilities -export create_discrete_pmf, spread_draws, scan +# Exported abstract types +export AbstractModel, AbstractEpiModel, AbstractLatentModel, + AbstractObservationModel # Exported types -export EpiData, Renewal, ExpGrowthRate, DirectInfections, AbstractModel, - AbstractEpiModel, AbstractLatentModel, AbstractObservationModel +export EpiData, Renewal, ExpGrowthRate, DirectInfections, RandomWalk # Exported Turing model constructors export make_epi_aware +# Exported utilities +export create_discrete_pmf, spread_draws, scan + include("docstrings.jl") include("abstract-types.jl") include("epi-models.jl") diff --git a/README.md b/README.md index 4e8ab05cb..d29c9c090 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,23 @@ -![Test](https://github.com/CDCgov/Rt-without-renewal/actions/workflows/test-EpiAware.yaml/badge.svg) -![CodeCov](https://github.com/CDCgov/Rt-without-renewal/actions/workflows/codecoverage-EpiAware.yaml/badge.svg) -![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg) - -# cfa-repo-template -A template for new CFA repos +# Effective reproduction number (Rt) estimation with or without a renewal process ⚠️ This is a work in progress -## How to use this template -To open a new repo using this template, click the green `Use this template` -button above and to the right. Then select `Create a new repository`. -Boilerplate language from [CDCgov GitHub Oroganization Open Source Project Template](https://github.com/cdcgov/template) -below the horizontal rule should be maintained in the final `README.md` file. - -[Guidance about when clearance is needed and how to get it] - -## This template contains -- [x] An Apache 2.0 license -- [ ] Issue templates for bugs, feature requests, and scientific improvements -- [ ] A pull request (PR) template -- [x] CI for linting and styling, following CFA's style guide for R, Python, and Java -- [x] A .gitignore template that covers R, Python, and Java - -## Reminder: how to open issues, branches, submit PRs, and review PRs -[TODO] -* Link to CFA's style guide -* How to open issues, including naming conventions, template usage -* How to create new branches, including naming conventions, template usage -* How to submit a PR, including when, template usage -* How to review a PR, including whose responsibility to merge - ------------------------------------------------------------------------------------- -# Your project name - ## Overview -Describe the purpose of your project. Add additional sections as necessary to help collaborators and potential collaborators understand and use your project. +To evaluate the role of the latent generative process in the estimation of the effective reproduction number (Rt), we are developing a flexible framework (see `EpiAware`) for Rt estimation that allows for the inclusion of different latent infection models (such as a renewal process) and provides a consistent interface for model fitting, posterior checking, and post-processing. + +In `pipeline`, we will use `EpiAware` to explore whether the inclusion of a renewal process in the latent generative process improves the estimation of Rt and other situational awareness signals. This exploration is then written as a manuscript for publication (see `manuscript` for work supporting this). ## Project Admin Name, Degrees, e-mail, CDC org (e.g., CDC/IOD/ORR/CFA) ## General Disclaimer + This repository was created for use by CDC programs to collaborate on public health related projects in support of the [CDC mission](https://www.cdc.gov/about/organization/mission.htm). GitHub is not hosted by the CDC, but is a third party website used by CDC and its partners to share information and collaborate on software. CDC use of GitHub does not imply an endorsement of any one particular service, product, or enterprise. ## Public Domain Standard Notice + This repository constitutes a work of the United States Government and is not subject to domestic copyright protection under 17 USC § 105. This repository is in the public domain within the United States, and copyright and related rights in @@ -54,6 +27,7 @@ submitting a pull request you are agreeing to comply with this waiver of copyright interest. ## License Standard Notice + This repository is licensed under ASL v2 or later. This source code in this repository is free: you can redistribute it and/or modify it under @@ -70,6 +44,7 @@ program. If not, see http://www.apache.org/licenses/LICENSE-2.0.html The source code forked from other open source projects will inherit its license. ## Privacy Standard Notice + This repository contains only non-sensitive, publicly available data and information. All material and community participation is covered by the [Disclaimer](https://github.com/CDCgov/template/blob/master/DISCLAIMER.md) @@ -77,6 +52,7 @@ and [Code of Conduct](https://github.com/CDCgov/template/blob/master/code-of-con For more information about CDC's privacy policy, please visit [http://www.cdc.gov/other/privacy.html](https://www.cdc.gov/other/privacy.html). ## Contributing Standard Notice + Anyone is encouraged to contribute to the repository by [forking](https://help.github.com/articles/fork-a-repo) and submitting a pull request. (If you are new to GitHub, you might start with a [basic tutorial](https://help.github.com/articles/set-up-git).) By contributing @@ -89,11 +65,13 @@ All comments, messages, pull requests, and other submissions received through CDC including this GitHub page may be subject to applicable federal law, including but not limited to the Federal Records Act, and may be archived. Learn more at [http://www.cdc.gov/other/privacy.html](http://www.cdc.gov/other/privacy.html). ## Records Management Standard Notice + This repository is not a source of government records but is a copy to increase collaboration and collaborative potential. All government records will be published through the [CDC web site](http://www.cdc.gov). ## Additional Standard Notices + Please refer to [CDC's Template Repository](https://github.com/CDCgov/template) for more information about [contributing to this repository](https://github.com/CDCgov/template/blob/master/CONTRIBUTING.md), [public domain notices and disclaimers](https://github.com/CDCgov/template/blob/master/DISCLAIMER.md),