---
title: "Get started with essential8"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started with essential8}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Overview

`essential8` computes component and composite Life's Essential 8 (LE8)
cardiovascular health scores. The current implementation scores adults aged
20 years or older using the American Heart Association's 2022 definition.
Pediatric scoring is not yet available.

This vignette shows the basic complete-data workflow. See
`?score_le8` for the full input contract and scoring details.

## Create an adult data frame

Supply one row per person. The example below uses base R and includes two
adults with raw responses to the 16-item Mediterranean Eating Pattern for
Americans (MEPA) screener. It also demonstrates both possible BMI profiles and both possible glucose measures.

```{r create-data}
library(essential8)

adult_data <- data.frame(
  id = c("patient_1", "patient_2"),
  age = c(42, 61),
  sex = c("female", "male"),
  # Daily servings
  olive_oil = c(2, 1),
  green_leafy_vegetables = c(1, 0.5),
  other_vegetables = c(2, 1),
  whole_grains = c(2, 1),
  # Weekly servings
  berries = c(3, 1),
  other_fruit = c(5, 2),
  meat = c(2, 5),
  fish = c(3, 1),
  chicken = c(2, 4),
  cheese = c(1, 4),
  butter_cream = c(1, 5),
  beans = c(3, 1),
  sweets_and_pastries = c(1, 5),
  nuts = c(4, 1),
  fast_food = c(0, 2),
  alcohol = c(4, 0),
  moderate_activity_minutes = c(100, 60),
  vigorous_activity_minutes = c(25, 0),
  smoking_status = c("never", "former"),
  years_since_quit = c(0, 6),
  current_inhaled_nds = c(FALSE, FALSE),
  secondhand_smoke_home = c(FALSE, FALSE),
  sleep_hours = c(7.5, 6.5),
  bmi = c(24.2, 24.0),
  bmi_profile = c("general", "asian_pacific"),
  non_hdl_cholesterol = c(125, 145),
  lipid_lowering_treatment = c(FALSE, TRUE),
  diabetes = c(FALSE, FALSE),
  glucose_measure = c("fasting_glucose", "hba1c"),
  glucose_value = c(95, 6.0),
  systolic_bp = c(118, 132),
  diastolic_bp = c(76, 84),
  antihypertensive_treatment = c(FALSE, TRUE)
)
```

## Compute LE8 scores

Pass the data frame to `score_le8()`. The returned data frame retains the
input columns and appends the derived activity measure, eight component
scores, composite score, and category.

```{r score-data}
scored <- score_le8(adult_data, diet_method = "mepa")

scored[c(
  "id",
  "mepa_total",
  "le8_diet_score",
  "physical_activity_moderate_equivalent_minutes",
  "le8_composite_score",
  "le8_category"
)]
```

Each vigorous activity minute counts as two moderate activity minutes and is
recorded as `physical_activity_moderate_equivalent_minutes`. The
`le8_composite_score` is the mean of the eight component scores. Categories
are `"low"` below 50, `"moderate"` from 50 to less than 80, and `"high"` at
80 or higher.

The component scores are available for analysis and quality checks:

```{r component-scores}
component_columns <- setdiff(
  grep("^le8_.*_score$", names(scored), value = TRUE),
  "le8_composite_score"
)

scored[c("id", component_columns)]
```

## Understand the MEPA inputs

The MEPA response columns use the 16 screener-item labels in snake case. The
column names should reflect as seen below, but you can map custom columns using
`mepa_columns = c()`.

- `olive_oil`, `green_leafy_vegetables`, `other_vegetables`, and
  `whole_grains` are servings per day.
- `berries`, `other_fruit`, `meat`, `fish`, `chicken`, `cheese`,
  `butter_cream`, `beans`, `sweets_and_pastries`, `nuts`, and `alcohol` are
  servings per week.
- `fast_food` is the number of times per week that meals are consumed from
  fast-food restaurants.

The screener defines `meat` as red meat, hamburger, bacon, or sausage;
`fish` includes fish, shellfish, or seafood; and `cheese` means full-fat or
regular cheese or cream cheese.

`score_le8()` evaluates each criterion and returns their sum as `mepa_total`
so that the derived diet input can be audited. The default MEPA sex field is
`sex`. If `sex` is absent, a field named `female` is
recognized automatically; map any other name with, for example,
`mepa_columns = c(sex = "reported_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.

## Choose other input methods explicitly

The `diet_method` argument defaults to `"mepa"`. If a source data set
contains both MEPA and percentile inputs, split the rows into separate data
frames and call `score_le8()` separately for each method.

- For `diet_method = "mepa"`, `diet_value` must be absent or contain only
  missing values.
- For `diet_method = "percentile"`, `diet_value` is required; MEPA columns are
  ignored. Supply a DASH or HEI-2015 percentile from 1 to 100, calculated
  against the relevant reference population before calling `score_le8()`.
- Set `bmi_profile` to either `"general"` or `"asian_pacific"`. The function
  does not infer a BMI profile from race or ethnicity.
- Set `glucose_measure` to `"fasting_glucose"` for a value in mg/dL or
  `"hba1c"` for a percentage. Diagnosed diabetes requires HbA1c for scoring.

The percentile workflow is executable without removing the unused MEPA columns:

```{r percentile}
percentile_data <- adult_data[1, , drop = FALSE]
percentile_data$diet_value <- 95
percentile_scores <- score_le8(
  percentile_data,
  diet_method = "percentile"
)
percentile_scores[
  c("diet_value", "le8_diet_score", "le8_composite_score")
]
```

Three optional, caller-adjudicated flags control clinical-judgment adjustments:
`apply_lean_muscular_bmi_override`, `apply_sleep_apnea_penalty`, and
`apply_prediabetes_metformin_penalty`. When these columns are absent, their
adjustments are not applied.

## Complete and source-defined inputs

The current implementation requires complete, finite values for every
required input. It does not impute missing data, convert units, or round raw
measurements before scoring.

`score_le8()` also rejects combinations for which the AHA source does not
define a score. Examples include an underweight BMI that
requires clinical judgment, a diagnostic-range glucose value paired with no
diabetes diagnosis, and simultaneous current combustible smoking and inhaled
nicotine-delivery-system use. Reconcile these records before scoring.
