Skip to contents

essential8

Overview

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

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

Installation 

install.packages("essential8")

Install the development version from GitHub with:

# 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 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.1.0 requires complete data for every component and supports adults aged 20 years or older. It does not implement pediatric or incomplete-record scoring (yet). 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 complete adult inputs for all eight AHA metrics:

  • diet (can be MEPA or percentile based, see below for more info)
  • physical activity (moderate and vigorous activity)
  • smoking
  • sleep
  • BMI
  • blood lipids
  • blood glucose and diabetes status
  • blood pressure (requires both systolic and diastolic measures)

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

score_le8(data, diet_method = "mepa", mepa_columns = NULL) applies the user-chosen diet method to every row in the call. 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. 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 require diet_value, containing a DASH or HEI-2015 percentile from 1 to 100. The result appends all eight component scores, 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.

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.

References

  • Lloyd-Jones, D. M., Allen, N. B., Anderson, C. A. M., et al. (2022). Life’s Essential 8: Updating and Enhancing the American Heart Association’s Construct of Cardiovascular Health: A Presidential Advisory From the American Heart Association. Circulation, 146(5), e18-e43. https://doi.org/10.1161/CIR.0000000000001078
  • Lloyd-Jones, D. M., 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. https://doi.org/10.1161/CIRCULATIONAHA.122.060911