Mapping Study Physical Activity to NHANES Quantiles
In mapnhanespa: Map Quantiles for Physical Activity from 'NHANES'

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

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.

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

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

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

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)

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)

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

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.

Single Values

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

nhanes_pa_quantile(
  value = 15000,
  age = 25,
  sex = "Female",
  measure = "mims"
)

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

Age Categories

Ages are mapped into NHANES CDF age categories:

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.