# phskc-apde/rads architecture

> Architecture diagram of the GitHub repository phskc-apde/rads, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phskc-apde/rads
- Repository: https://github.com/phskc-apde/rads

## Overview

#### Purpose and Package Surface
RADS is an R package for standardized public-health analysis, customized for PHSKC APDE workflows. Its public interface is defined by `NAMESPACE`; package initialization and metadata reside in `R/rads-package.R` and `R/zzz.R`. Primary user-facing entry points include calculation, data/reference access, recoding, age standardization, and uncertainty functions.

#### Core Calculation Pipeline
`calc()` is the central estimation interface, with specialized survey handling in `R/calc.R` and `R/calc.dtsurvey.R`. It likely accepts analytic data and measure definitions, validates or normalizes inputs, selects an estimation path, and returns public-health metrics such as counts, rates, and uncertainty-aware estimates. Shared numerical and validation boundaries are in `R/validation_utils.R`, `R/check_nan.R`, and `R/digits.R`.

#### Data Access and Reference Boundary
The package separates analysis logic from source-data acquisition. Generic and domain-specific retrieval functions are organized in `R/get_data.R`, while population/reference-population access is in `R/get_population.R` and `R/build_getpop_query.R`. Bundled crosswalk reference data is shipped at `data/ref_get_xwalk.rda`, sourced from `data-raw/ref_get_xwalk.csv`. The README states current releases should operate without SQL Server or file-server permissions; formerly dependent access functionality has moved to private `apde.data`.

#### Recode and Data-Modeling Layer
RADS supports declarative transformations: recode specifications are parsed, converted into dictionaries/instructions, then applied to data through `R/parse_recode_instructions.R`, `R/create_recode.R`, and `R/enact_recodes.R`. `R/data_modeler.R` provides a higher-level data-modeling stage, likely coordinating variable definitions and transformations before analysis. This forms a distinct boundary between raw analytic inputs and metric calculation.

#### Domain-Specific Classification
Public-health domain logic is encapsulated rather than embedded in `calc()`. Hospitalization/CHARS classifications and validation are in `R/chars_functions.R`; mortality cause definitions, ICD cleanup, multicause handling, and validation are in `R/death_functions.R`. These modules prepare domain-specific numerator definitions and derived classifications for the shared calculation pipeline.

#### Statistical Adjustment and Inference
Age adjustment is an independent analysis stage in `R/age_standardize.R`, using reference populations from the retrieval layer. Uncertainty propagation is implemented in `R/propagate_uncertainty.R`, allowing downstream transformations to retain or compute uncertainty rather than treating estimates as scalar-only results. Additional shared computational functions are grouped in `R/utilities.R`.

#### Runtime, Dependencies, and Delivery
This is a conventional R package (`DESCRIPTION`, `NAMESPACE`) installable from GitHub with `remotes::install_github()` and loaded via `library(rads)`. Reference datasets are built in or supplied by the separately installed `rads.data` package. Documentation and intended workflows are exposed through vignettes such as `vignettes/calc.Rmd`, `vignettes/calculating_rates_with_rads.Rmd`, and `vignettes/leading_causes_of_death.qmd`.

Main entry points: [`R/calc.R`](https://github.com/phskc-apde/rads/blob/main/R/calc.R) (calc()), [`R/data_modeler.R`](https://github.com/phskc-apde/rads/blob/main/R/data_modeler.R) (Data modeler), [`R/age_standardize.R`](https://github.com/phskc-apde/rads/blob/main/R/age_standardize.R) (Age standardization), [`R/get_data.R`](https://github.com/phskc-apde/rads/blob/main/R/get_data.R) (Data retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_package["Package Surface"]
  node_namespace["Exports<br/>R package API"]
  node_package_init["Package initialization<br/>R package runtime<br/>[rads-package.R]"]
  node_zzz["Load hooks<br/>R package runtime<br/>[zzz.R]"]
end

subgraph group_data["Data &amp; References"]
  node_data_access["Data retrieval<br/>access API<br/>[get_data.R]"]
  node_population_access["Population retrieval<br/>reference API<br/>[get_population.R]"]
  node_population_query["Population query builder<br/>query construction"]
  node_crosswalk[("Bundled crosswalk<br/>reference dataset<br/>[ref_get_xwalk.rda]")]
end

subgraph group_prepare["Modeling &amp; Domain Prep"]
  node_recode_parser["Recode parser<br/>specification parser"]
  node_recode_builder["Recode dictionary builder<br/>transformation builder<br/>[create_recode.R]"]
  node_recode_executor["Recode executor<br/>data transformation<br/>[enact_recodes.R]"]
  node_data_modeler["Data modeler<br/>analytic preparation<br/>[data_modeler.R]"]
  node_chars["CHARS classification<br/>hospitalization domain logic<br/>[chars_functions.R]"]
  node_mortality["Mortality classification<br/>cause-of-death domain logic<br/>[death_functions.R]"]
end

subgraph group_analysis["Estimation &amp; Inference"]
  node_calc{{"calc&#40;&#41;<br/>central estimation API<br/>[calc.R]"}}
  node_survey_calc["Survey estimation<br/>survey estimator<br/>[calc.dtsurvey.R]"]
  node_age_standardize["Age standardization<br/>statistical adjustment<br/>[age_standardize.R]"]
  node_uncertainty["Uncertainty propagation<br/>inference"]
  node_validation["Validation &amp; numeric utilities<br/>shared computation<br/>[validation_utils.R]"]
end

node_namespace -->|"exports"| node_calc
node_package_init -->|"initializes"| node_zzz
node_data_access -->|"supplies inputs"| node_data_modeler
node_population_query -->|"builds retrieval"| node_population_access
node_crosswalk -->|"reference lookup"| node_data_access
node_recode_parser -->|"parsed instructions"| node_recode_builder
node_recode_builder -->|"recode dictionary"| node_recode_executor
node_recode_executor -->|"transformed variables"| node_data_modeler
node_data_modeler -->|"analytic data"| node_calc
node_chars -->|"numerator classifications"| node_calc
node_mortality -->|"cause definitions"| node_calc
node_validation -->|"validates inputs"| node_calc
node_calc -->|"selects survey path"| node_survey_calc
node_calc -->|"estimates for adjustment"| node_age_standardize
node_population_access -->|"reference population"| node_age_standardize
node_calc -->|"estimate inputs"| node_uncertainty
node_age_standardize -->|"adjusted estimates"| node_uncertainty

click node_namespace "https://github.com/phskc-apde/rads/blob/main/NAMESPACE"
click node_package_init "https://github.com/phskc-apde/rads/blob/main/R/rads-package.R"
click node_zzz "https://github.com/phskc-apde/rads/blob/main/R/zzz.R"
click node_data_access "https://github.com/phskc-apde/rads/blob/main/R/get_data.R"
click node_population_access "https://github.com/phskc-apde/rads/blob/main/R/get_population.R"
click node_population_query "https://github.com/phskc-apde/rads/blob/main/R/build_getpop_query.R"
click node_crosswalk "https://github.com/phskc-apde/rads/blob/main/data/ref_get_xwalk.rda"
click node_recode_parser "https://github.com/phskc-apde/rads/blob/main/R/parse_recode_instructions.R"
click node_recode_builder "https://github.com/phskc-apde/rads/blob/main/R/create_recode.R"
click node_recode_executor "https://github.com/phskc-apde/rads/blob/main/R/enact_recodes.R"
click node_data_modeler "https://github.com/phskc-apde/rads/blob/main/R/data_modeler.R"
click node_chars "https://github.com/phskc-apde/rads/blob/main/R/chars_functions.R"
click node_mortality "https://github.com/phskc-apde/rads/blob/main/R/death_functions.R"
click node_calc "https://github.com/phskc-apde/rads/blob/main/R/calc.R"
click node_survey_calc "https://github.com/phskc-apde/rads/blob/main/R/calc.dtsurvey.R"
click node_age_standardize "https://github.com/phskc-apde/rads/blob/main/R/age_standardize.R"
click node_uncertainty "https://github.com/phskc-apde/rads/blob/main/R/propagate_uncertainty.R"
click node_validation "https://github.com/phskc-apde/rads/blob/main/R/validation_utils.R"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_namespace,node_package_init,node_zzz toneBlue
class node_data_access,node_population_access,node_population_query,node_crosswalk toneAmber
class node_recode_parser,node_recode_builder,node_recode_executor,node_data_modeler,node_chars,node_mortality toneMint
class node_calc,node_survey_calc,node_age_standardize,node_uncertainty,node_validation toneRose
```

## Components

### Package Surface

- [Exports](https://github.com/phskc-apde/rads/blob/main/NAMESPACE): R package API · Defines the public package interface. · `NAMESPACE`
- [Package initialization](https://github.com/phskc-apde/rads/blob/main/R/rads-package.R): R package runtime · `R/rads-package.R`
- [Load hooks](https://github.com/phskc-apde/rads/blob/main/R/zzz.R): R package runtime · `R/zzz.R`

### Data & References

- [Data retrieval](https://github.com/phskc-apde/rads/blob/main/R/get_data.R): access API · Generic and domain-specific source-data access. · `R/get_data.R`
- [Population retrieval](https://github.com/phskc-apde/rads/blob/main/R/get_population.R): reference API · `R/get_population.R`
- [Population query builder](https://github.com/phskc-apde/rads/blob/main/R/build_getpop_query.R): query construction · `R/build_getpop_query.R`
- [Bundled crosswalk](https://github.com/phskc-apde/rads/blob/main/data/ref_get_xwalk.rda): reference dataset · `data/ref_get_xwalk.rda`

### Modeling & Domain Prep

- [Recode parser](https://github.com/phskc-apde/rads/blob/main/R/parse_recode_instructions.R): specification parser · `R/parse_recode_instructions.R`
- [Recode dictionary builder](https://github.com/phskc-apde/rads/blob/main/R/create_recode.R): transformation builder · `R/create_recode.R`
- [Recode executor](https://github.com/phskc-apde/rads/blob/main/R/enact_recodes.R): data transformation · `R/enact_recodes.R`
- [Data modeler](https://github.com/phskc-apde/rads/blob/main/R/data_modeler.R): analytic preparation · Coordinates variable definitions and transformations. · `R/data_modeler.R`
- [CHARS classification](https://github.com/phskc-apde/rads/blob/main/R/chars_functions.R): hospitalization domain logic · `R/chars_functions.R`
- [Mortality classification](https://github.com/phskc-apde/rads/blob/main/R/death_functions.R): cause-of-death domain logic · Cleans and classifies ICD and multicause definitions. · `R/death_functions.R`

### Estimation & Inference

- [calc()](https://github.com/phskc-apde/rads/blob/main/R/calc.R): central estimation API · Produces public-health counts, rates, and estimates. · `R/calc.R`
- [Survey estimation](https://github.com/phskc-apde/rads/blob/main/R/calc.dtsurvey.R): survey estimator · `R/calc.dtsurvey.R`
- [Age standardization](https://github.com/phskc-apde/rads/blob/main/R/age_standardize.R): statistical adjustment · `R/age_standardize.R`
- [Uncertainty propagation](https://github.com/phskc-apde/rads/blob/main/R/propagate_uncertainty.R): inference · `R/propagate_uncertainty.R`
- [Validation & numeric utilities](https://github.com/phskc-apde/rads/blob/main/R/validation_utils.R): shared computation · `R/validation_utils.R`

## Connections

- Exports → calc(): exports
- Package initialization → Load hooks: initializes
- Data retrieval → Data modeler: supplies inputs
- Population query builder → Population retrieval: builds retrieval
- Bundled crosswalk → Data retrieval: reference lookup
- Recode parser → Recode dictionary builder: parsed instructions
- Recode dictionary builder → Recode executor: recode dictionary
- Recode executor → Data modeler: transformed variables
- Data modeler → calc(): analytic data
- CHARS classification → calc(): numerator classifications
- Mortality classification → calc(): cause definitions
- Validation & numeric utilities → calc(): validates inputs
- calc() → Survey estimation: selects survey path
- calc() → Age standardization: estimates for adjustment
- Population retrieval → Age standardization: reference population
- calc() → Uncertainty propagation: estimate inputs
- Age standardization → Uncertainty propagation: adjusted estimates