# phac-nml-phrsd/ern architecture

> Architecture diagram of the GitHub repository phac-nml-phrsd/ern, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phac-nml-phrsd/ern
- Repository: https://github.com/phac-nml-phrsd/ern

## Overview

##### Project type and purpose
- This is an R package (“ern”) whose purpose is to estimate the time‐varying effective reproduction number (Rₜ) of pathogens using either clinical testing data or wastewater surveillance data. It provides data‐processing pipelines, statistical inference (including a JAGS‐based MCMC implementation), plotting utilities, vignettes for users, and integration with CRAN.

##### File structure
- Top‐level files: DESCRIPTION, NAMESPACE, LICENSE, README.md (package metadata)
- R/: core R code modules, each file encapsulates specific functionality (data ingestion, deconvolution, smoothing, estimation, plotting, diagnostics)
- data-raw/: scripts that generate raw data for inclusion in data/
- data/: packaged datasets (cl.data, ww.data) used for examples and testing
- inst/: citation and other miscellaneous install‐time files
- man-roxygen/ & man/: roxygen source and generated Rd documentation
- tests/: testthat suite with helper scripts and reference test data
- vignettes/: user guides and reproducible examples
- .github/workflows/: CI config for test/coverage on GitHub Actions

##### README for additional insights
- Describes two inference methods (“renewal” via JAGS and “linear” interpolation)
- Notes external dependency on JAGS (rjags) for Bayesian inference
- Mentions vignettes as interactive tutorials
- Outlines developer workflow for CRAN submission

a. Main components
- External Inputs:
– Clinical incidence data (user‐provided)
– Wastewater surveillance data (user‐provided)
- Data Ingestion & Preprocessing: scripts in R/data-raw and R/data.R
- Distribution Library: R/distributions.R, parameter modules (incubation, serial interval, shedding)
- Deconvolution & Interpolation Engines:
– Renewal‐method using JAGS (R/deconvolution_RL.R, R/mcmcdiag.R)
– Linear‐interpolation method (R/linear_int_daily.R)
- Rₜ Estimation Functions: R/estimate_R_cl*, R/estimate_R_ww*
- Results Summarization & Plots: R/summary_postsamples.R, R/plot.R
- Documentation & Examples: man-roxygen, man/, vignettes/
- Packaging & Tests:
– Package metadata (DESCRIPTION, NAMESPACE)
– Unit tests (tests/)
– CI/CD pipeline (GitHub Actions in .github/)
- External Services: JAGS executable (invoked via rjags), CRAN build farm

b. Relationships and data flows
– User data → Data Ingestion → Distribution Library → Deconvolution/Interpolation → Rₜ Estimation → Summarization & Plots → User output
– Vignettes reference core functions and packaged data
– CI pipeline runs tests and builds package for CRAN

c. Architectural patterns & design principles
– Modular: each R script provides a focused responsibility
– Data‐Centric: raw data → cleaned data → model input → model output
– Pipeline: chaining functions in a well‐defined order
– Test‐Driven: extensive test suite for each function
– Documentation‐First: roxygen to Rd to README to vignettes

d. Key technologies & libraries
– R (language)
– rjags / JAGS (Bayesian inference engine)
– testthat (unit testing)
– roxygen2 (documentation)
– GitHub Actions (CI/CD)

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Data Layer"
    UserProvidedInc[(User Provided Data)]:::data
    CLData[(Built-in Clinical Data)]:::data
    WWData[(Built-in Wastewater Data)]:::data
    CLDataRaw["data-raw/cl-data.R"]:::preproc
    DataR["R/data.R"]:::preproc
  end

  UserProvidedInc --> DataR
  CLDataRaw -->|"raw incidence"| DataR
  CLData --> DataR
  WWData --> DataR

  DistributionLibrary["R/distributions.R"]:::core
  DataR -->|"cleaned incidence"| DistributionLibrary

  subgraph "Inference Layer"
    subgraph "Renewal Method (JAGS)"
      RL["R/deconvolution_RL.R"]:::core
      MCMCdiag["R/mcmcdiag.R"]:::core
      WWInc["R/deconv_ww_inc.R"]:::core
      JAGS[JAGS Engine]:::ext
    end
    subgraph "Linear Method"
      Linear["R/linear_int_daily.R"]:::core
    end
  end

  DistributionLibrary -->|"distribution parameters"| RL
  DistributionLibrary -->|"distribution parameters"| WWInc
  DistributionLibrary -->|"distribution parameters"| Linear
  JAGS -->|"MCMC run"| RL
  JAGS -->|"MCMC run"| WWInc
  RL -->|"deconvolved series"| MCMCdiag
  WWInc --> MCMCdiag

  subgraph "Estimation"
    EstimateCl["R/estimate_R_cl.R"]:::core
    EstimateClRep["R/estimate_R_cl_rep.R"]:::core
    EstimateClSingle["R/estimate_R_cl_single.R"]:::core
    EstimateWw["R/estimate_R_ww.R"]:::core
  end

  MCMCdiag -->|"posterior samples"| EstimateClSingle
  Linear -->|"interpolated series"| EstimateCl
  Linear --> EstimateClRep
  WWInc --> EstimateWw

  subgraph "Presentation Layer"
    Summary["R/summary_postsamples.R"]:::core
    Plot["R/plot.R"]:::core
    Vignette["vignettes/est-rt.Rmd"]:::docs
    UserOutput[/"User Output"/]:::data
  end

  EstimateCl --> Summary
  EstimateClRep --> Summary
  EstimateClSingle --> Summary
  EstimateWw --> Summary
  Summary --> Plot
  Plot --> UserOutput
  Vignette -->|"example functions"| Plot

  subgraph "Ancillary Components"
    Description["DESCRIPTION"]:::meta
    Namespace["NAMESPACE"]:::meta
    ManRox["man-roxygen/"]:::docs
    Man["man/"]:::docs
    Tests["tests/testthat/"]:::tests
    TestData["tests/testdata/"]:::tests
    CI[".github/workflows/test-coverage.yaml"]:::ci
    CRAN[(CRAN Build Farm)]:::ext
  end

  Description --> CI
  Namespace --> CI
  Tests --> CI
  TestData --> Tests
  CI -->|"build & test"| CRAN

  %% Click Events
  click CLDataRaw "https://github.com/phac-nml-phrsd/ern/blob/main/data-raw/cl-data.R"
  click DataR "https://github.com/phac-nml-phrsd/ern/blob/main/R/data.R"
  click DistributionLibrary "https://github.com/phac-nml-phrsd/ern/blob/main/R/distributions.R"
  click RL "https://github.com/phac-nml-phrsd/ern/blob/main/R/deconvolution_RL.R"
  click MCMCdiag "https://github.com/phac-nml-phrsd/ern/blob/main/R/mcmcdiag.R"
  click WWInc "https://github.com/phac-nml-phrsd/ern/blob/main/R/deconv_ww_inc.R"
  click Linear "https://github.com/phac-nml-phrsd/ern/blob/main/R/linear_int_daily.R"
  click EstimateCl "https://github.com/phac-nml-phrsd/ern/blob/main/R/estimate_R_cl.R"
  click EstimateClRep "https://github.com/phac-nml-phrsd/ern/blob/main/R/estimate_R_cl_rep.R"
  click EstimateClSingle "https://github.com/phac-nml-phrsd/ern/blob/main/R/estimate_R_cl_single.R"
  click EstimateWw "https://github.com/phac-nml-phrsd/ern/blob/main/R/estimate_R_ww.R"
  click Summary "https://github.com/phac-nml-phrsd/ern/blob/main/R/summary_postsamples.R"
  click Plot "https://github.com/phac-nml-phrsd/ern/blob/main/R/plot.R"
  click CLData "https://github.com/phac-nml-phrsd/ern/blob/main/data/cl.data.rda"
  click WWData "https://github.com/phac-nml-phrsd/ern/blob/main/data/ww.data.rda"
  click Vignette "https://github.com/phac-nml-phrsd/ern/blob/main/vignettes/est-rt.Rmd"
  click ManRox "https://github.com/phac-nml-phrsd/ern/tree/main/man-roxygen/"
  click Man "https://github.com/phac-nml-phrsd/ern/tree/main/man/"
  click Tests "https://github.com/phac-nml-phrsd/ern/tree/main/tests/testthat/"
  click TestData "https://github.com/phac-nml-phrsd/ern/tree/main/tests/testdata/"
  click CI "https://github.com/phac-nml-phrsd/ern/blob/main/.github/workflows/test-coverage.yaml"
  click Description "https://github.com/phac-nml-phrsd/ern/tree/main/DESCRIPTION"
  click Namespace "https://github.com/phac-nml-phrsd/ern/tree/main/NAMESPACE"

  classDef data fill:#1f77b4,stroke:#000,color:#fff
  classDef preproc fill:#a2d2e6,stroke:#000,color:#000
  classDef core fill:#2ca02c,stroke:#000,color:#fff
  classDef ext fill:#ff7f0e,stroke:#000,color:#000
  classDef docs fill:#7f7f7f,stroke:#000,color:#fff
  classDef tests fill:#8c564b,stroke:#000,color:#fff
  classDef ci fill:#bcbd22,stroke:#000,color:#000
  classDef meta fill:#17becf,stroke:#000,color:#000
```
