GlobalDietaryR

GlobalDietaryR provides R workflows for harmonising Global Dietary Database (GDD) and Global Burden of Disease (GBD) data, calculating dietary indices and population attributable fractions (PAFs), building statistical summaries, and visualising global nutrition patterns.

Project status

This repository is the maintained development source recovered from the GlobalDietaryR 2.0.0 installed package image with the rights holder's authorisation. The exact recovered snapshot is preserved separately from the maintained source so that recovery fidelity and later scientific corrections remain auditable.

• 297 functions are inventoried.
• 82 public functions retain compatible exported names and each has title, description, usage, argument, value, and example documentation.
• 27 functions form the recommended core API.
• 50 functions remain as extended compatibility APIs.
• 5 functions are retained as legacy APIs.
• PAF, dietary-index, and GBD/GDD merge workflows have regression tests.
• Authorisation checks from the installed image are not present in the maintained package.

See the API lifecycle policy, the human-readable function catalog, and the machine-readable catalog.

Installation

Install the current GitHub version with:

install.packages("remotes")
remotes::install_github("Carl6231/GlobalDietaryR")

Alternatively, install a local development checkout with:

install.packages(
  ".",
  repos = NULL,
  type = "source"
)

Several dietary-index wrappers use the optional dietaryindex package. Install its current development version separately when those wrappers are needed:

remotes::install_github("jamesjiadazhan/dietaryindex")

Core workflows

Filter a GDD-style data frame:

library(GlobalDietaryR)

example_data <- data.frame(
  location = c("A", "B", "A"),
  year = c(2010, 2010, 2015),
  nutrition = c("Fruits", "Fruits", "Whole grains"),
  median = c(120, 95, 70)
)

gdd_filter(
  example_data,
  location == "A"
)

The core APIs cover:

• GDD decoding, filtering, regional extraction, and data-quality checks;
• GBD/GDD harmonisation and provenance-aware joins;
• ACS2020, AHEI, DASHI, DII, HEI2020, MEDI, and PHDI calculations;
• relative-risk workbook parsing and PAF calculation;
• summary tables and selected publication-oriented visualisations.

Use help(package = "GlobalDietaryR") or the reference index to locate a specific function.

Scientific safeguards

• GDD_expand_with_gbd() requires complete join keys by default. Weaker partial-key matching must be requested explicitly and is labelled in the returned data.
• gbd_convert_relative_RISK_dataframe() retains parsed records but marks whether positive finite point and interval estimates pass the package's basic PAF-compatibility gate.
• gdd_calculate_paf() normalises relative risks to the theoretical minimum risk exposure level (TMREL), supports population weighting, and preserves fitted spline models.
• PHDI endpoint scenarios are reported as ordered scenario minima and maxima; they are not statistical confidence intervals.

These safeguards do not turn ecological country-level associations into individual-level causal estimates. Users remain responsible for the causal estimand, risk-outcome justification, exposure comparability, lag structure, and uncertainty model.

Validation

Run the complete local suite with:

Rscript -e 'testthat::test_local(".", reporter = "summary")'
R CMD build --no-build-vignettes .
R CMD check --no-manual --no-build-vignettes GlobalDietaryR_*.tar.gz

The current suite contains 26 behavioural test cases and 214 passing expectations. The final local source-package check reports Status: OK (0 errors, 0 warnings, 0 notes). Detailed evidence is stored in key-module-validation.txt and recovery-verification.txt. Per-function documentation completeness is recorded in public-documentation-completeness.csv.

Data boundary

No third-party GDD, GBD, IHME, or SDI input workbook is distributed in the package. Validation inputs remain under the ignored .private-data/ directory; their filenames, sizes, and checksums are recorded for local audit. Users must obtain and use those datasets under their respective terms.

Contributing

See CONTRIBUTING.md. Scientific changes must include a documented estimand or scoring rule, a deterministic fixture, and a regression test.

License

GlobalDietaryR is released under the MIT License. Copyright (c) 2026 Carl6231.