# Mapping Study Physical Activity to NHANES Quantiles

    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 (Koffman et al. 2025). The minute-level NHANES step count and physical activity data are also available through PhysioNet (Koffman and Muschelli 2025).

## Basic Mapping

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

    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")
    #>    id age    sex   measure   value nhanes_quantile
    #> 1 P01  25 Female      mims   15000       0.5349443
    #> 2 P02  62   Male ssl_steps    7500       0.3527381
    #> 3 P03  84 Female        AC 1000000       0.1322205

The `measure` column accepts common aliases:

    measures <- data.frame(
      id = c("P01", "P01", "P01"),
      age = 25,
      sex = "Female",
      measure = c("mims", "PAXMTSM", "total_PAXMTSM"),
      value = 15000
    )

    map_nhanes_pa_quantiles(measures, id = "id")
    #>    id age    sex       measure value nhanes_quantile
    #> 1 P01  25 Female          mims 15000       0.5349443
    #> 2 P01  25 Female       PAXMTSM 15000       0.5349443
    #> 3 P01  25 Female total_PAXMTSM 15000       0.5349443

## Combined and Wave-Specific References

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

    map_nhanes_pa_quantiles(study_data, id = "id")
    #>    id age    sex   measure   value nhanes_quantile
    #> 1 P01  25 Female      mims   15000       0.5349443
    #> 2 P02  62   Male ssl_steps    7500       0.3527381
    #> 3 P03  84 Female        AC 1000000       0.1322205

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"`.

    map_nhanes_pa_quantiles(study_data, id = "id", wave = "2013-2014")
    #>    id age    sex   measure   value nhanes_quantile
    #> 1 P01  25 Female      mims   15000       0.4943653
    #> 2 P02  62   Male ssl_steps    7500       0.3820584
    #> 3 P03  84 Female        AC 1000000       0.1181001

## 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.

    map_nhanes_pa_quantiles(study_data, id = "id", sex = NULL)
    #>    id age    sex   measure   value nhanes_quantile
    #> 1 P01  25 Female      mims   15000       0.5688587
    #> 2 P02  62   Male ssl_steps    7500       0.4164160
    #> 3 P03  84 Female        AC 1000000       0.1408881

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.

    map_nhanes_pa_quantiles(study_data, id = "id", age = NULL)
    #>    id age    sex   measure   value nhanes_quantile
    #> 1 P01  25 Female      mims   15000      0.53548286
    #> 2 P02  62   Male ssl_steps    7500      0.28321363
    #> 3 P03  84 Female        AC 1000000      0.01040967

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

    map_nhanes_pa_quantiles(study_data, id = "id", sex = NULL, wave = 7)
    #>    id age    sex   measure   value nhanes_quantile
    #> 1 P01  25 Female      mims   15000       0.6017452
    #> 2 P02  62   Male ssl_steps    7500       0.3716006
    #> 3 P03  84 Female        AC 1000000       0.1669768

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.

## Single Values

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

    nhanes_pa_quantile(
      value = 15000,
      age = 25,
      sex = "Female",
      measure = "mims"
    )
    #> [1] 0.5349443

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

    nhanes_pa_quantile(
      value = 15000,
      age = 25,
      sex = NULL,
      measure = "mims",
      wave = "2011-2012"
    )
    #> [1] 0.6017452

## Age Categories

Ages are mapped into NHANES CDF age categories:

    suppressWarnings(nhanes_pa_age_category(c(8, 25, 84, 90)))
    #> [1] "[0,10)"  "[20,30)" "[80,85)" "[80,85)"

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

Koffman, Lily, Ciprian Crainiceanu, and John Muschelli. 2025. “Comparing Step Counting Algorithms for High-Resolution Wrist Accelerometry Data in NHANES 2011-2014.” Medicine & Science in Sports & Exercise 57 (4): 746–55. https://doi.org/10.1249/MSS.0000000000003616.
Koffman, Lily, and John Muschelli. 2025. “Minute Level Step Counts and Physical Activity Data from the National Health and Nutrition Examination Survey (NHANES) 2011-2014.” PhysioNet, ahead of print, May. https://doi.org/10.13026/9n0r-tv02.