Package {mapnhanespa}

Title: Map Quantiles for Physical Activity from 'NHANES'
Version: 0.1.0
Description: Maps physical activity from the National Health and Nutrition Examination Survey ('NHANES') study into population-based quantiles.
License: MIT + file LICENSE
Encoding: UTF-8
Depends: R (≥ 3.5)
LazyData: true
LazyDataCompression: xz
URL: https://github.com/jhuwit/mapnhanespa
BugReports: https://github.com/jhuwit/mapnhanespa/issues
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition: 3
VignetteBuilder: knitr
Imports: dplyr, magrittr, purrr, survey
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-05-29 16:31:16 UTC; johnmuschelli
Author: John Muschelli ORCID iD [aut, cre]
Maintainer: John Muschelli <muschellij2@gmail.com>
Repository: CRAN
Date/Publication: 2026-06-02 11:10:08 UTC

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Map physical activity values to NHANES population quantiles

Description

map_nhanes_pa_quantiles() adds a population-level quantile column to a participant-level data frame. Quantiles are evaluated from NHANES accelerometer cumulative distribution functions stratified by age category, sex/gender, measure, and optionally survey wave.

Usage

map_nhanes_pa_quantiles(
  data,
  id = NULL,
  age = "age",
  sex = "sex",
  measure = "measure",
  value = "value",
  wave = NULL,
  age_category = NULL,
  quantile_col = "nhanes_quantile"
)

Arguments

data

A data frame with one row per participant-measure observation.

id

Optional participant identifier column name. The column is checked when supplied, but otherwise left unchanged.

age, sex, measure, value

Column names in data containing age in years, sex/gender, physical activity measure, and observed value. Set age = NULL to use the age-overall CDFs. Set sex = NULL to use the sex/gender-overall CDFs. Setting both to NULL uses the overall CDF across both dimensions.

wave

Optional NHANES wave column name or scalar value. Supported values are 7, 8, "2011-2012", and "2013-2014". If NULL, the combined wave CDFs are used.

age_category

Optional column name containing NHANES age categories such as "[20,30)" or "Overall". When supplied, it is used instead of age.

quantile_col

Name of the output quantile column.

Value

data with an added quantile column.

Examples

example_data <- data.frame(
  id = 1:2,
  age = c(25, 62),
  sex = c("Female", "Male"),
  measure = c("mims", "ssl_steps"),
  value = c(15000, 7500)
)

map_nhanes_pa_quantiles(example_data)

map_nhanes_pa_quantiles(example_data, sex = NULL)

map_nhanes_pa_quantiles(example_data, age = NULL, wave = "2011-2012")
map_nhanes_pa_quantiles(example_data, age = NULL, sex = NULL)

NHANES PA data

Description

NHANES PA data

Usage

nhanes_measure_data

Format

A data frame with 87619 rows and 9 variables:

SEQN

ID variable

data_release_cycle

wave/data release cycle

cat_age

age category

gender

sex/gender designation

wtmec4yr_adj_norm

normalized weight for surveys

masked_variance_pseudo_psu

PSU - sampling unit

masked_variance_pseudo_stratum

sampling stratum

num_valid_days

number of valid days of wear >= 1396 minutes

measure

measure that was calculated

value

value for the measure

Source

NHANES 2011-2012 and 2013-2014 accelerometer data.

Convert ages to NHANES physical activity CDF age categories

Description

Ages are grouped into 10-year bins from ⁠[0,10)⁠ through ⁠[70,80)⁠. Ages greater than or equal to 80 are assigned to the oldest available CDF category, "[80,85)". Ages greater than 85 also map to "[80,85)", with a warning by default.

Usage

nhanes_pa_age_category(age, warn = TRUE)

Arguments

age

Numeric age in years.

warn

Logical. If TRUE, warn when non-missing ages greater than 85 are mapped into the "[80,85)" category.

Value

A character vector of NHANES age category labels.

Examples

nhanes_pa_age_category(c(8, 25, 84, 90))

Evaluate a single NHANES physical activity quantile

Description

Evaluate a single NHANES physical activity quantile

Usage

nhanes_pa_quantile(
  value,
  age = NULL,
  sex = NULL,
  measure,
  wave = NULL,
  age_category = NULL
)

Arguments

value

Observed physical activity value.

age

Age in years. Set to NULL to use the age-overall CDFs. Ignored when age_category is supplied.

sex

Sex/gender. Common values such as "M", "male", "F", and "female" are normalized. Set to NULL to use the sex/gender-overall CDFs.

measure

Physical activity measure. Supported aliases include "mims", "PAXMTSM", "ssl_steps", "scsslsteps", "steps", Verisense step aliases such as "steps_stepcount_ssl", "steps_stepcount_rf", "steps_vs_original", "steps_vs_revised", "steps_sdt", and "AC".

wave

Optional NHANES wave. Supported values are 7, 8, "2011-2012", and "2013-2014".

age_category

Optional NHANES age category such as "[20,30)" or "Overall".

Value

A numeric quantile in ⁠[0, 1]⁠, or NA_real_ when no matching CDF is available.

Examples

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

nhanes_pa_quantile(
  value = 15000,
  age = 25,
  sex = NULL,
  measure = "mims",
  wave = "2013-2014"
)

Precompute and cache NHANES PA CDFs

Description

Builds every supported CDF combination and stores the result in the internal cache. This covers combined and by-wave CDFs, age-specific and age-overall strata, sex/gender-specific and sex/gender-overall strata, and the overall-overall combination for each supported measure.

Usage

precompute_nhanes_pa_cdfs()

Value

Invisibly returns a list with the cached combined and by-wave tables.