Package {mapnhanespa}

Title: Map Quantiles for Physical Activity from 'NHANES'
Version: 0.3.0
Description: Maps physical activity from the National Health and Nutrition Examination Survey ('NHANES') study into population-based quantiles, using the NHANES 2011-2014 step count and physical activity summaries described in Koffman, Crainiceanu, and Muschelli (2025) <doi:10.1249/MSS.0000000000003616>, with minute-level data from Koffman and Muschelli (2025) <doi:10.13026/9n0r-tv02>.
License: MIT + file LICENSE
Encoding: UTF-8
Depends: R (≥ 4.1.0)
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, purrr, survey
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-10-22 20:56:45 UTC; johnmuschelli
Author: John Muschelli ORCID iD [aut, cre], Lily Koffman ORCID iD [aut]
Maintainer: John Muschelli <muschellij2@gmail.com>
Repository: CRAN
Date/Publication: 2026-10-22 22:50:02 UTC

Map physical activity values to NHANES population quantiles

Description

map_nhanes_pa_quantiles() adds a population-level quantile column and the NHANES age category used for each row 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. Accepted measure names and their CDF summaries are listed by nhanes_pa_measure_map(). Unmapped names return missing quantiles and are listed in a warning.

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 and age_category_pa_map, the NHANES age category used to select the CDF. The category is "Overall" when age = NULL and is taken directly from age_category when supplied.

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

Select the NHANES CDF for a measure

Description

Uses the explicit aliases in nhanes_pa_measure_map() to select the CDF calculated from the corresponding summary in nhanes_measure_data.

Usage

nhanes_pa_measure_cdf(
  measure,
  age = NULL,
  sex = NULL,
  wave = NULL,
  age_category = NULL
)

Arguments

measure

A single supported measure name.

age

Age in years, or NULL for the overall age CDF.

sex

Sex/gender, or NULL for the overall sex/gender CDF.

wave

Optional NHANES wave (7, 8, "2011-2012", or "2013-2014").

age_category

Optional NHANES age category, used instead of age.

Value

A CDF function, or NA_real_ if no CDF is available.

Supported physical activity measure names

Description

Returns every accepted measure name and the NHANES summary used to build its CDF. Matching ignores case, spaces, underscores, and punctuation. Measures absent from this table have no supported CDF.

Usage

nhanes_pa_measure_map()

Value

A data frame with measure (accepted name) and summary (the measure in nhanes_measure_data used for its CDF).

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. See nhanes_pa_measure_map() for every supported name and its CDF summary.

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.