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).
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 age_category_pa_map nhanes_quantile
#> 1 P01 25 Female mims 15000 [20,30) 0.5349443
#> 2 P02 62 Male ssl_steps 7500 [60,70) 0.3527381
#> 3 P03 84 Female AC 1000000 [80,85) 0.1322205The 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:
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")
#> id age sex measure value age_category_pa_map
#> 1 P01 25 Female total_activity_counts 2773035 [20,30)
#> 2 P01 25 Female total_log10AC 3039 [20,30)
#> 3 P01 25 Female total_PAXMTSM 14653 [20,30)
#> 4 P01 25 Female total_log10PAXMTSM 1043 [20,30)
#> 5 P01 25 Female total_scsslsteps 8694 [20,30)
#> 6 P01 25 Female total_scrfsteps 11421 [20,30)
#> 7 P01 25 Female total_oaksteps 12055 [20,30)
#> 8 P01 25 Female total_vssteps 9505 [20,30)
#> 9 P01 25 Female total_vsrevsteps 9631 [20,30)
#> nhanes_quantile
#> 1 0.4852706
#> 2 0.5714842
#> 3 0.4873396
#> 4 0.5564848
#> 5 0.5872852
#> 6 0.4938108
#> 7 0.4892558
#> 8 0.5019565
#> 9 0.5158600The 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.
nhanes_pa_measure_map()
#> measure summary
#> 1 AC AC
#> 2 activity_counts AC
#> 3 activitycounts AC
#> 4 counts AC
#> 5 total_AC AC
#> 6 total_activity_counts AC
#> 7 log10AC log10AC
#> 8 log10_activity_counts log10AC
#> 9 log10_counts log10AC
#> 10 total_log10AC log10AC
#> 11 PAXMTSM PAXMTSM
#> 12 mims PAXMTSM
#> 13 mims_unit PAXMTSM
#> 14 total_PAXMTSM PAXMTSM
#> 15 log10PAXMTSM log10PAXMTSM
#> 16 log10_mims log10PAXMTSM
#> 17 total_log10PAXMTSM log10PAXMTSM
#> 18 log10_mims_unit log10PAXMTSM
#> 19 scsslsteps scsslsteps
#> 20 ssl_steps scsslsteps
#> 21 sslstepcount scsslsteps
#> 22 sslstepcounts scsslsteps
#> 23 total_ssl_steps scsslsteps
#> 24 total_scsslsteps scsslsteps
#> 25 steps_stepcount_ssl scsslsteps
#> 26 steps_stepcounts_ssl scsslsteps
#> 27 scrfsteps scrfsteps
#> 28 rf_steps scrfsteps
#> 29 rfstepcount scrfsteps
#> 30 rfstepcounts scrfsteps
#> 31 total_rf_steps scrfsteps
#> 32 total_scrfsteps scrfsteps
#> 33 steps_stepcount_rf scrfsteps
#> 34 steps_stepcounts_rf scrfsteps
#> 35 oaksteps oaksteps
#> 36 foreststeps oaksteps
#> 37 steps_oak oaksteps
#> 38 steps_forest oaksteps
#> 39 nsteps_oak oaksteps
#> 40 nsteps_forest oaksteps
#> 41 total_oaksteps oaksteps
#> 42 steps_stepcount_forest oaksteps
#> 43 steps_stepcounts_forest oaksteps
#> 44 vssteps vssteps
#> 45 vssteps_original vssteps
#> 46 steps_vs_original vssteps
#> 47 total_vssteps vssteps
#> 48 vsrevsteps vsrevsteps
#> 49 vssteps_revised vsrevsteps
#> 50 steps_vs_revised vsrevsteps
#> 51 total_vsrevsteps vsrevstepsThe measure column accepts common aliases, including
total_ac and total_activity_counts for the
AC CDF:
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")
#> id age sex measure value age_category_pa_map
#> 1 P01 25 Female mims 15000 [20,30)
#> 2 P01 25 Female PAXMTSM 15000 [20,30)
#> 3 P01 25 Female total_ac 2773035 [20,30)
#> 4 P01 25 Female total_activity_counts 2773035 [20,30)
#> nhanes_quantile
#> 1 0.5349443
#> 2 0.5349443
#> 3 0.4852706
#> 4 0.4852706
nhanes_pa_measure_cdf("total_activity_counts", age = 25, sex = "Female")(2773035)
#> [1] 0.4852706By 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 age_category_pa_map nhanes_quantile
#> 1 P01 25 Female mims 15000 [20,30) 0.5349443
#> 2 P02 62 Male ssl_steps 7500 [60,70) 0.3527381
#> 3 P03 84 Female AC 1000000 [80,85) 0.1322205To 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".
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 age_category_pa_map nhanes_quantile
#> 1 P01 25 Female mims 15000 [20,30) 0.5688587
#> 2 P02 62 Male ssl_steps 7500 [60,70) 0.4164160
#> 3 P03 84 Female AC 1000000 [80,85) 0.1408881If 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 age_category_pa_map nhanes_quantile
#> 1 P01 25 Female mims 15000 Overall 0.53548286
#> 2 P02 62 Male ssl_steps 7500 Overall 0.28321363
#> 3 P03 84 Female AC 1000000 Overall 0.01040967Both 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 age_category_pa_map nhanes_quantile
#> 1 P01 25 Female mims 15000 [20,30) 0.6017452
#> 2 P02 62 Male ssl_steps 7500 [60,70) 0.3716006
#> 3 P03 84 Female AC 1000000 [80,85) 0.1669768The 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.
For a single participant-measure value, use
nhanes_pa_quantile().
The same combined, wave-specific, and overall-stratum options are available:
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.