Package {essential8}

Title: Reproducible Cardiovascular Health Metric Scoring
Version: 0.1.0
Description: Provides a reproducible R implementation of the American Heart Association Life's Essential 8 cardiovascular health scoring framework for complete adult records from people aged 20 years or older. Calculates the eight component scores and their unweighted composite score using the 2022 adult definition described by Lloyd-Jones et al. (2022) <doi:10.1161/CIR.0000000000001078>.
License: MIT + file LICENSE
Encoding: UTF-8
Language: en-US
Imports: cli (≥ 3.6.0)
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
Config/Needs/website: pkgdown
URL: https://thatoneguy006.github.io/essential8/, https://github.com/thatoneguy006/essential8
BugReports: https://github.com/thatoneguy006/essential8/issues
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-08-23 01:51:46 UTC; Carso
Author: Carson Richardson ORCID iD [aut, cre, cph]
Maintainer: Carson Richardson <carson.richardson@outlook.com>
Repository: CRAN
Date/Publication: 2026-09-03 11:20:09 UTC

essential8: Reproducible cardiovascular health metric scoring

Description

essential8 is a transparent, versioned, and auditable implementation of published adult cardiovascular health metric definitions. Complete-data adult scoring based on the American Heart Association's 2022 Life's Essential 8 definition is available through score_le8().

Scientific status

The adult scoring rules in version 0.1.0 are implemented from the cited AHA publications and covered by boundary and input-validation tests. Users remain responsible for verifying measurement protocols, population-specific diet percentiles, and caller-adjudicated clinical-judgment flags. The package is research software and is not intended for clinical decision support.

Author(s)

Maintainer: Carson Richardson carson.richardson@outlook.com (ORCID) [copyright holder]

Authors:

See Also

Useful links:

Score Life's Essential 8 cardiovascular health

Description

Computes the eight adult Life's Essential 8 (LE8) component scores and their unweighted mean using the American Heart Association's 2022 Presidential Advisory. This initial implementation requires complete data for every required input and applies only to adults aged 20 years or older.

Usage

score_le8(data, diet_method = "mepa", mepa_columns = NULL)

Arguments

data

A data frame with one row per adult and the required columns described below.

diet_method

A single diet-scoring method applied to every row in data: "mepa" (the default) or "percentile". Values are matched case-insensitively. Score data that use different methods in separate calls.

mepa_columns

NULL, or a named character vector mapping canonical MEPA fields to columns in data. The names are canonical fields and the values are actual column names. Unmapped fields use their canonical names.

Value

A data frame containing the original columns plus mepa_total (missing for population-percentile rows), physical_activity_moderate_equivalent_minutes, the eight component score columns prefixed with le8_, le8_composite_score, and le8_category. The composite score is the exact, unrounded mean. Categories are "low" for scores below 50, "moderate" for scores from 50 to less than 80, and "high" for scores of at least 80.

Required columns

Optional clinical-judgment columns

Source-constrained behavior

The function derives the 0-to-16 MEPA total from the 16 raw screener responses. For population scoring, callers must supply a DASH or HEI-2015 percentile calculated against the relevant reference population; the rows in data are not their own reference distribution.

The AHA table applies 20-point treatment decrements to blood-lipid and blood-pressure scores. These components are floored at zero, consistent with the AHA's 0-to-100 metric definition and the non-negative possible scores shown in its applied NHANES implementation. Optional sleep-apnea and prediabetes/metformin decrements are applied only through explicit flags. Inputs are not rounded. The documented MEPA daily/weekly equivalences are applied where the source question and criterion use different timeframes. Combinations without a source-defined score, including simultaneous current combustible smoking and current inhaled-NDS use, produce a structured error.

References

Lloyd-Jones DM, Allen NB, Anderson CAM, et al. (2022). Life's Essential 8: Updating and Enhancing the American Heart Association's Construct of Cardiovascular Health. Circulation, 146(5), e18-e43. doi:10.1161/CIR.0000000000001078

Lloyd-Jones DM, Ning H, Labarthe D, et al. (2022). Status of Cardiovascular Health in US Adults and Children Using the American Heart Association's New Life's Essential 8 Metrics. Circulation, 146(11), 822-835. doi:10.1161/CIRCULATIONAHA.122.060911

Examples

patient <- data.frame(
  id = "patient_1",
  age = 55,
  sex = "female",
  # Daily servings
  olive_oil = 2,
  green_leafy_vegetables = 1,
  other_vegetables = 2,
  whole_grains = 2,
  # Weekly servings
  berries = 3,
  other_fruit = 5,
  meat = 2,
  fish = 3,
  chicken = 2,
  cheese = 1,
  butter_cream = 1,
  beans = 3,
  sweets_and_pastries = 1,
  nuts = 4,
  alcohol = 4,
  # Fast-food meals per week
  fast_food = 0,
  moderate_activity_minutes = 90,
  vigorous_activity_minutes = 0,
  smoking_status = "former",
  years_since_quit = 6,
  current_inhaled_nds = FALSE,
  secondhand_smoke_home = FALSE,
  sleep_hours = 7.5,
  bmi = 27.5,
  bmi_profile = "general",
  non_hdl_cholesterol = 145,
  lipid_lowering_treatment = FALSE,
  diabetes = FALSE,
  glucose_measure = "fasting_glucose",
  glucose_value = 95,
  systolic_bp = 128,
  diastolic_bp = 78,
  antihypertensive_treatment = FALSE
)

scores <- score_le8(patient, diet_method = "mepa")
scores[
  c(
    "id",
    "mepa_total",
    "le8_diet_score",
    "le8_composite_score",
    "le8_category"
  )
]