README

essential8 provides reproducible R implementations of the American Heart Association Life’s Essential 8 cardiovascular health scoring framework.

The current release implements adult scoring for people aged 20 years or older. Pediatric scoring is planned but not yet implemented.

Installation

install.packages("essential8")

# install.packages("remotes")
remotes::install_github("thatoneguy006/essential8")

Background

The American Heart Association Life’s Essential 8 (LE8) framework combines eight lifestyle and health components into a composite cardiovascular health score from 0 to 100. essential8 applies the published adult scoring bands in one validated workflow and returns all eight component scores plus the composite.

Version 0.2.0 supports incomplete adult records without imputing raw inputs or component scores. By default, the composite is calculated when at least seven components are available; min_components can set a threshold from 1 through 8. Optional AHA clinical-judgment adjustments are applied only when the user supplies explicit adjudication flags; see ?score_le8 for details.

Basic use

Read the AHA advisory and ?score_le8 before using the package, particularly the input units, population-percentile diet requirements, and optional clinical-judgment adjustments.

Pass a data frame containing adult inputs for the eight AHA metrics. Missing component values are allowed, and component-specific columns may be omitted when a domain is unavailable:

The following example contains one record and uses score_le8(patient, diet_method = "mepa"):

library(essential8)

patient <- data.frame(
  id = "patient_1",
  age = 55,
  sex = "female",

  # MEPA items --------------------------
  # 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,
  # -------------------------------------

  # Physical activity -------------------
  moderate_activity_minutes = 90,
  vigorous_activity_minutes = 0,
  # -------------------------------------

  # Smoking -----------------------------
  smoking_status = "former",
  years_since_quit = 6,
  current_inhaled_nds = FALSE,
  secondhand_smoke_home = FALSE,
  # --------------------------------------

  # Sleep --------------------------------
  sleep_hours = 7.5,
  # --------------------------------------

  # BMI ----------------------------------
  bmi = 27.5,
  bmi_profile = "general",
  # --------------------------------------

  # Blood lipids -------------------------
  non_hdl_cholesterol = 145,
  lipid_lowering_treatment = FALSE,
  # --------------------------------------

  # Diabetes & Glucose -------------------
  diabetes = FALSE,
  glucose_measure = "fasting_glucose",
  glucose_value = 95,
  # --------------------------------------

  # Blood Pressure -----------------------
  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"
  )
]

The diet_method argument can be specified either as "mepa" or "percentile", corresponding to the 16 MEPA items seen above or the DASH percentile alternative scores. The min_components argument defaults to 7. For diet_method = "mepa", the function calculates mepa_total directly from the 16 screener responses. Their column names must be the screener labels shown above. Matching is case-insensitive.

The default MEPA sex field is sex; if it is absent, a female column is recognized automatically. Map any other field with, for example, mepa_columns = c(sex = "reported_sex", alcohol = "alc"). For sex, values are trimmed and matched case-insensitively as m/f or male/female. Numeric or character 0/1 values are also accepted, where 0 is male and 1 is female.

For data that use both diet methods, split the rows into separate data frames and call score_le8() separately. Percentile calls use diet_value, containing a DASH or HEI-2015 percentile from 1 to 100. The result appends all eight component scores, le8_n_components, le8_complete, the composite score, and its cardiovascular health category. Future versions will allow the calculation of these DASH/HEI percentiles, similar to how the MEPA is currently implemented. See ?score_le8 for more information.

Incomplete component data

score_le8() preserves ordinary row-level missingness. The composite is the mean of the available component scores when the selected threshold is met:

incomplete <- rbind(patient, patient)
incomplete$id <- c("complete", "sleep_missing")
incomplete$sleep_hours[2] <- NA_real_

incomplete_scores <- score_le8(incomplete, min_components = 7)
incomplete_scores[
  c(
    "id",
    "le8_composite_score",
    "le8_n_components",
    "le8_complete"
  )
]

le8_n_components reports how many component scores contributed, while le8_complete is TRUE only when all eight were available. If a component cannot be calculated for any observation, the function emits one consolidated warning identifying every structurally unavailable component.

Learn more

Disclaimer

essential8 is independent research software and is not affiliated with, sponsored by, approved by, or endorsed by the American Heart Association. It is not intended for clinical decision-making or diagnosis of health problems.

essential8