---
title: "Mapping Study Physical Activity to NHANES Quantiles"
output: rmarkdown::html_vignette
bibliography: references.bib
vignette: >
  %\VignetteIndexEntry{Mapping Study Physical Activity to NHANES Quantiles}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library(mapnhanespa)
```

## Purpose

`mapnhanespa` maps physical activity summaries from a study sample onto
population-level quantiles estimated from the National Health and Nutrition
Examination Survey (NHANES) 2011-2012 and 2013-2014 accelerometer waves. These
NHANES cycles are useful reference populations because participants wore
ActiGraph GT3X+ accelerometers on the non-dominant wrist for seven consecutive
days, producing nationally representative accelerometry data.

The package is designed for the common setting where a study has participant
identifiers, age, sex or gender, a physical activity measure, and a value for
that measure. Instead of comparing raw values across measures with different
scales, the package evaluates each value against the corresponding NHANES
cumulative distribution function (CDF). The result is a quantile in `[0, 1]`
that can be interpreted relative to the NHANES reference distribution.

The CDFs in this package are based on NHANES 2011-2014 activity count, MIMS, and
step-count summaries. The step-count measures relate to work applying multiple
step-counting algorithms to high-resolution wrist accelerometry data from
NHANES 2011-2014 [@koffman2025stepcount]. The minute-level NHANES step count
and physical activity data are also available through PhysioNet
[@koffman2025physionet].

## Basic Mapping

Use `map_nhanes_pa_quantiles()` when the input data have one row per
participant-measure observation.

```{r}
study_data <- data.frame(
  id = c("P01", "P02", "P03"),
  age = c(25, 62, 84),
  sex = c("Female", "Male", "Female"),
  measure = c("mims", "ssl_steps", "AC"),
  value = c(15000, 7500, 1000000)
)

map_nhanes_pa_quantiles(study_data, id = "id")
```

The returned `age_category_pa_map` column shows the NHANES age category used
to select each participant's CDF. The following example covers all nine
supported summaries:

```{r}
all_measures <- data.frame(
  id = rep("P01", 9),
  age = 25,
  sex = "Female",
  measure = c("total_activity_counts", "total_log10AC", "total_PAXMTSM",
              "total_log10PAXMTSM", "total_scsslsteps", "total_scrfsteps",
              "total_oaksteps", "total_vssteps", "total_vsrevsteps"),
  value = c(2773035, 3039, 14653, 1043, 8694, 11421, 12055, 9505, 9631)
)

map_nhanes_pa_quantiles(all_measures, id = "id")
```

The complete list of accepted names and the summary used for each CDF is
available from `nhanes_pa_measure_map()`. Other names return `NA` with a warning listing the
unmapped measures. Each `value` should be calculated using the summary named
in the map and supplied on that summary's scale.

```{r}
nhanes_pa_measure_map()
```

The `measure` column accepts common aliases, including `total_ac` and
`total_activity_counts` for the `AC` CDF:

```{r}
measures <- data.frame(
  id = rep("P01", 4),
  age = 25,
  sex = "Female",
  measure = c("mims", "PAXMTSM", "total_ac", "total_activity_counts"),
  value = c(15000, 15000, 2773035, 2773035)
)

map_nhanes_pa_quantiles(measures, id = "id")

nhanes_pa_measure_cdf("total_activity_counts", age = 25, sex = "Female")(2773035)
```

## Combined and Wave-Specific References

By default, quantiles are evaluated against CDFs estimated from the combined
2011-2012 and 2013-2014 NHANES waves.

```{r}
map_nhanes_pa_quantiles(study_data, id = "id")
```

To map against a specific NHANES wave, provide `wave`. Supported values include
the NHANES data release cycles `7` and `8`, and the year labels `"2011-2012"`
and `"2013-2014"`.

```{r}
map_nhanes_pa_quantiles(study_data, id = "id", wave = "2013-2014")
```

## Overall Age or Sex Strata

If a study should be mapped without sex or gender stratification, set
`sex = NULL`. The participant's age category is still used, but the CDF is
selected from the `gender == "Overall"` stratum.

```{r}
map_nhanes_pa_quantiles(study_data, id = "id", sex = NULL)
```

If a study should be mapped without age stratification, set `age = NULL`. The
participant's sex or gender is still used, but the CDF is selected from the
`cat_age == "Overall"` stratum.

```{r}
map_nhanes_pa_quantiles(study_data, id = "id", age = NULL)
```

Both options can be combined with a wave-specific reference:

```{r}
map_nhanes_pa_quantiles(study_data, id = "id", sex = NULL, wave = 7)
```

The package data do not contain a stratum that is overall for both age and sex
or gender. Calls that omit both age and sex therefore produce an error.

## Wear-time Inclusion Criteria

The default NHANES reference follows the primary analysis of
@koffman2025stepcount. A day is valid if it has at least 1,368 minutes (95% of
a full day) of non-flagged wear, at least 420 minutes of wake wear, and at
least 420 minutes of non-zero MIMS. Participants need at least 3 valid days.

Studies often use other rules, and a quantile is most meaningful when the
study and the reference use the same rules. The `min_wear_minutes` and
`min_valid_days` arguments select a reference built with a different
criterion. Survey weights were re-adjusted separately for each criterion.
The available criteria are listed by `nhanes_pa_wear_criteria()`:

```{r}
criteria <- nhanes_pa_wear_criteria()
criteria[, c("criterion", "min_wear_hours", "pct_of_day", "min_valid_days",
             "default")]
unique(criteria[, c("min_wear_minutes", "note")])
```

For example, a study that used the 10-hour, 4-day hip-worn NHANES 2003-2006
rule can compare the same value under both references:

```{r}
compare <- rbind(
  cbind(criterion = "1368 min, 3 days (default)",
        map_nhanes_pa_quantiles(study_data, id = "id")),
  cbind(criterion = "600 min, 4 days",
        map_nhanes_pa_quantiles(study_data, id = "id",
                                min_wear_minutes = 600, min_valid_days = 4))
)
compare[order(compare$id), c("id", "measure", "value", "criterion",
                             "nhanes_quantile")]
```

The default criterion uses `nhanes_measure_data`, so results match earlier
versions of the package. Every other criterion uses the matching subset of
`nhanes_measure_data_wear_criteria`.

## Single Values

For a single participant-measure value, use `nhanes_pa_quantile()`.

```{r}
nhanes_pa_quantile(
  value = 15000,
  age = 25,
  sex = "Female",
  measure = "mims"
)
```

The same combined, wave-specific, and overall-stratum options are available:

```{r}
nhanes_pa_quantile(
  value = 15000,
  age = 25,
  sex = NULL,
  measure = "mims",
  wave = "2011-2012"
)
```

## Age Categories

Ages are mapped into NHANES CDF age categories:

```{r}
suppressWarnings(nhanes_pa_age_category(c(8, 25, 84, 90)))
```

Ages greater than 85 are mapped to the oldest available category, `"[80,85)"`,
and produce a warning when age is supplied directly. If a study already has age
categories, pass the column name through `age_category`.

## References