Package {mapnhanespa}

Title:	Map Quantiles for Physical Activity from 'NHANES'
Version:	0.4.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.1.1
NeedsCompilation:	no
Packaged:	2026-11-09 21:34:35 UTC; johnmuschelli
Author:	John Muschelli [aut, cre], Lily Koffman [aut]
Maintainer:	John Muschelli <muschellij2@gmail.com>
Repository:	CRAN
Date/Publication:	2026-11-09 22:00: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",
  min_wear_minutes = 1368,
  min_valid_days = 3
)

Arguments

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 reference built with a 10-hour, 4-day wear criterion
map_nhanes_pa_quantiles(example_data, min_wear_minutes = 600,
                        min_valid_days = 4)

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 (e.g. 1368 minutes, see Details)

measure

measure that was calculated

value

value for the measure

Details

Valid days are defined as in Koffman, Crainiceanu, and Muschelli (2025). A day is valid if (1) at least 1,368 minutes (95% of a full day) were classified as wake wear, sleep wear, or unknown and had no data quality flags; (2) at least 420 minutes were classified as wake wear; and (3) at least 420 minutes had non-zero MIMS. Only participants with at least 3 valid days are included.

Source

NHANES 2011-2012 and 2013-2014 accelerometer data.

References

Koffman L, Crainiceanu C, Muschelli J (2025). Comparing Step Counting Algorithms for High-Resolution Wrist Accelerometry Data in NHANES 2011-2014. Medicine & Science in Sports & Exercise, 57(4), 746-755. doi:10.1249/MSS.0000000000003616. PMID: 39589008.

NHANES PA data under alternative wear-time inclusion criteria

Description

Participant-level NHANES 2011-2014 physical activity summaries computed under 15 accelerometer wear-time inclusion criteria: every combination of a minimum of 600, 960, 1296, 1368, or 1440 wear minutes per valid day and a minimum of 1, 3, or 4 valid days. Use nhanes_pa_wear_criteria() to list the criteria and select one with the min_wear_minutes and min_valid_days arguments of the mapping functions.

Usage

nhanes_measure_data_wear_criteria

Format

A data frame with 193114 rows and 18 variables:

SEQN

ID variable

criterion

wear-time criterion, "wear{min}_days{d}", e.g. "wear1368_days3". See nhanes_pa_wear_criteria().

data_release_cycle

wave/data release cycle

cat_age

age category

gender

sex/gender designation

wtmec4yr_adj_norm

normalized survey weight, adjusted separately within each criterion

masked_variance_pseudo_psu

PSU - sampling unit

masked_variance_pseudo_stratum

sampling stratum

num_valid_days

number of valid days under the criterion

AC, log10AC, PAXMTSM, log10PAXMTSM, oaksteps, scrfsteps, scsslsteps, vsrevsteps, vssteps

values for each summary, as in the measure and value columns of nhanes_measure_data

Details

The data are stored wide, with one row per participant and criterion and one column per summary, to keep the package small.

A day is valid if (1) at least min_wear_minutes minutes were classified as wake wear, sleep wear, or unknown and had no data quality flags; (2) at least 420 minutes were classified as wake wear; and (3) at least 420 minutes had non-zero MIMS. A participant is included under a criterion if they have at least min_valid_days valid days. Survey weights were re-adjusted for each criterion, so rows from different criteria should never be combined.

The "wear1368_days3" criterion matches nhanes_measure_data up to floating-point rounding (relative differences of about 1e-16 in some log10AC and log10PAXMTSM values), except for two participants (SEQN 69762 and 80584) who each differ by one valid day. This is because the PhysioNet PAXFLGSM quality-flag file omits some flags present in the original NHANES data. The package default (min_wear_minutes = 1368, min_valid_days = 3) therefore continues to use nhanes_measure_data, so earlier results are unchanged.

Source

NHANES 2011-2012 and 2013-2014 accelerometer data, via PhysioNet.

References

Koffman L, Crainiceanu C, Muschelli J (2025). Comparing Step Counting Algorithms for High-Resolution Wrist Accelerometry Data in NHANES 2011-2014. Medicine & Science in Sports & Exercise, 57(4), 746-755. doi:10.1249/MSS.0000000000003616.

Koffman L, Muschelli J (2025). Minute Level Step Counts and Physical Activity Data from the National Health and Nutrition Examination Survey (NHANES) 2011-2014 (version 1.0.1). PhysioNet. doi:10.13026/9n0r-tv02.

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

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, or in nhanes_measure_data_wear_criteria for a non-default wear-time criterion.

Usage

nhanes_pa_measure_cdf(
  measure,
  age = NULL,
  sex = NULL,
  wave = NULL,
  age_category = NULL,
  min_wear_minutes = 1368,
  min_valid_days = 3
)

Arguments

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,
  min_wear_minutes = 1368,
  min_valid_days = 3
)

Arguments

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

# Same value against a complete-wear (24 h), 1-day reference
nhanes_pa_quantile(
  value = 15000,
  age = 25,
  sex = "Female",
  measure = "mims",
  min_wear_minutes = 1440,
  min_valid_days = 1
)

Available accelerometer wear-time inclusion criteria

Description

Lists the wear-time inclusion criteria that can be selected with the min_wear_minutes and min_valid_days arguments of map_nhanes_pa_quantiles(), nhanes_pa_quantile(), nhanes_pa_measure_cdf(), and precompute_nhanes_pa_cdfs(). Choose the criterion that matches the inclusion rules used for your own data.

Usage

nhanes_pa_wear_criteria()

Details

A day is valid if it has at least min_wear_minutes minutes of non-flagged wear (wake wear, sleep wear, or unknown), at least 420 minutes of wake wear, and at least 420 minutes with non-zero MIMS. A participant is included if they have at least min_valid_days valid days. Survey weights were re-adjusted separately for each criterion.

The default criterion (1,368 minutes, 3 days) uses nhanes_measure_data, the primary analysis of Koffman, Crainiceanu, and Muschelli (2025). Every other criterion uses the matching subset of nhanes_measure_data_wear_criteria.

Value

A data frame with one row per criterion and columns:

criterion

criterion label, "wear{min}_days{d}"

min_wear_minutes

minimum minutes of wear for a valid day

min_wear_hours

min_wear_minutes in hours

pct_of_day

min_wear_minutes as a percentage of 1,440 minutes

min_valid_days

minimum number of valid days

default

TRUE for the package default criterion

note

short note on where the wear threshold is used

References

Troiano RP, Berrigan D, Dodd KW, Masse LC, Tilert T, McDowell M (2008). Physical activity in the United States measured by accelerometer. Medicine & Science in Sports & Exercise, 40(1), 181-188. doi:10.1249/mss.0b013e31815a51b3.

Saint-Maurice PF, Troiano RP, Bassett DR, et al. (2020). Association of daily step count and step intensity with mortality among US adults. JAMA, 323(12), 1151-1160. doi:10.1001/jama.2020.1382.

Koffman L, Crainiceanu C, Muschelli J (2025). Comparing Step Counting Algorithms for High-Resolution Wrist Accelerometry Data in NHANES 2011-2014. Medicine & Science in Sports & Exercise, 57(4), 746-755. doi:10.1249/MSS.0000000000003616.

Examples

nhanes_pa_wear_criteria()

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. CDFs are cached separately for each wear-time criterion.

Usage

precompute_nhanes_pa_cdfs(min_wear_minutes = 1368, min_valid_days = 3)

Arguments

Value

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