Package {essential8}

Title:	Reproducible Cardiovascular Health Metric Scoring
Version:	0.2.0
Description:	Provides a reproducible R implementation of the American Heart Association Life's Essential 8 cardiovascular health scoring framework for adult records from people aged 20 years or older. Calculates the eight component scores and their unweighted composite score from available component data 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.1.0
NeedsCompilation:	no
Packaged:	2026-10-10 14:31:17 UTC; Carso
Author:	Carson Richardson [aut, cre, cph], Amrik Khalsa [ctb], Sara Conroy [ctb]
Maintainer:	Carson Richardson <carson.richardson@outlook.com>
Repository:	CRAN
Date/Publication:	2026-10-10 14:50:02 UTC

essential8: Reproducible cardiovascular health metric scoring

Description

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

Scientific status

The adult scoring rules in version 0.2.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:

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

See Also

Useful links:

• https://thatoneguy006.github.io/essential8/

• https://github.com/thatoneguy006/essential8

• Report bugs at https://github.com/thatoneguy006/essential8/issues

Score Life's Essential 8 cardiovascular health

Description

Computes the eight adult Life's Essential 8 (LE8) component scores and the composite score using the American Heart Association's 2022 Presidential Advisory. Component scores are calculated wherever sufficient inputs are available, without imputing missing values. This implementation applies only to adults aged 20 years or older.

Usage

score_le8(data, diet_method = "mepa", mepa_columns = NULL, min_components = 7L)

Arguments

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_n_components, le8_composite_score, le8_complete, and le8_category. The component count reports how many scores contributed to the composite score; le8_complete is TRUE only when all eight components are available. Categories are "low" for scores below 50, "moderate" for scores from 50 to less than 80, and "high" for scores of at least 80. The category is missing when the composite score is missing.

Input columns

• age: Age in years; must be present, complete, and at least 20.

• For diet_method = "mepa", the 16 Table C screener-item columns named below and sex (or female when sex is absent). The item names are matched exactly after case normalization. Supply daily servings in olive_oil, green_leafy_vegetables, other_vegetables, and whole_grains; supply weekly servings or frequency in berries, other_fruit, meat, fish, chicken, cheese, butter_cream, beans, sweets_and_pastries, nuts, and alcohol; supply the number of times per week that fast-food meals are consumed in fast_food. Sex may be encoded as "m"/"f", "male"/"female", or 0/1, where 0 is male and 1 is female. Character encodings are matched case-insensitively, and character "0"/"1" values are also accepted.

• diet_value: Used when diet_method = "percentile". Supply a DASH or HEI-2015 percentile from 1 to 100, calculated against the relevant reference distribution. The function does not rank supplied rows against one another. If this column is absent or missing, the diet score is missing. If it is present for MEPA data, all its values must be missing.

• moderate_activity_minutes and vigorous_activity_minutes: Weekly minutes. Each vigorous minute counts as two moderate-equivalent minutes.

• smoking_status: One of "never", "former", or "current".

• years_since_quit: Years since quitting combustible tobacco. This is used only when smoking_status is "former".

• current_inhaled_nds: Whether an inhaled nicotine-delivery system is currently used.

• secondhand_smoke_home: Whether the adult lives with an active indoor smoker.

• sleep_hours: Average hours of sleep per night.

• bmi: Body mass index in kg/m^2. Values below 18.5 are not scored because the AHA advisory defers to clinician judgment for underweight adults.

• bmi_profile: Either "general" or "asian_pacific". The function never infers a profile from race or ethnicity.

• non_hdl_cholesterol: Non-HDL cholesterol in mg/dL.

• lipid_lowering_treatment: Whether the lipid value is drug treated.

• diabetes: Whether diabetes has been diagnosed.

• glucose_measure: Either "fasting_glucose" or "hba1c".

• glucose_value: Fasting glucose in mg/dL or HbA1c in percent, as named by glucose_measure. Diagnosed diabetes requires HbA1c. A record with no diabetes diagnosis but a value in the diagnostic diabetes range is rejected because the AHA scoring table does not assign that combination.

• systolic_bp and diastolic_bp: Blood pressure in mm Hg.

• antihypertensive_treatment: Whether the blood pressure is treated.

Component input columns may contain missing values or be omitted. A component score is NA_real_ when its available inputs are insufficient. Missing values are never imputed. A warning is emitted when an entire LE8 component cannot be calculated for any observation.

Optional clinical-judgment columns

• apply_lean_muscular_bmi_override: A caller-adjudicated flag asserting that a lean, higher-muscle-mass adult in the general BMI profile has a BMI from 25 to less than 30 and should receive 100 BMI points. If absent, the standard BMI band is used.

• apply_sleep_apnea_penalty: If TRUE, subtract 20 points for untreated or undertreated sleep apnea. If absent, no discretionary penalty is applied.

• apply_prediabetes_metformin_penalty: A caller-adjudicated flag asserting that the adult has a history of prediabetes, is taking metformin to prevent diabetes, is currently normoglycemic, and the clinician chose to apply the AHA's discretionary 20-point decrement. If absent, no discretionary penalty is applied.

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. 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"
  )
]