Download NHANES files for an analyte using the CDC variable catalog

A smarter alternative to nhanes_download() for analytes whose file name changed across cycles (e.g. total cholesterol: LAB13 -> L13_B -> L13_C -> TCHOL_D onward). Uses nhanes_variable_map() to look up the correct CDC file name for each cycle, then downloads using the exact catalog name.

Usage

nhanes_download_analyte(
  term,
  cycles,
  component = "Laboratory",
  keep_vars = NULL,
  refresh = FALSE,
  add_cycle_col = TRUE
)

Arguments

term

Character. Search term passed to nhanes_variable_map().

cycles

Character. One or more cycle labels (e.g. "1999-2000"). See nhanes_cycles().

component

Character or NULL. NHANES component to search. Default "Laboratory".

keep_vars

Character vector or NULL. Passed to nhanes_variable_map() to disambiguate serum from urine forms of the same analyte.

refresh

Logical. Re-download even if cached? Default FALSE.

add_cycle_col

Logical. Add a cycle column to each data frame? Default TRUE.

Value

If a single cycle is requested, a data frame. If multiple cycles are requested, a named list of data frames keyed by cycle label.

See also

nhanes_variable_map() to inspect the per-cycle file/variable lookup before downloading; nhanes_harmonize() to rename and stack the returned list; nhanes_download() for downloading by exact file code.

Examples

# \donttest{
cycles <- nhanes_cycles()[1:10, "cycle"]

# Total cholesterol -- file name changed in 1999-2004; this handles it
tchol_list <- nhanes_download_analyte("total cholesterol", cycles)
#> Found 6 unique variables matching "total cholesterol".
#> Warning: Both "2017-2018" and "2017-2020" are present. The 2017-2018 participants are
#> included in the 2017-2020 pandemic-adjusted file -- use one or the other in
#> pooled analyses to avoid double-counting.

# Serum creatinine (keep_vars excludes urine creatinine)
scr_list <- nhanes_download_analyte("creatinine", cycles,
                                    keep_vars = c("LBXSCR","LBDSCR","LB2SCR"))
#> Found 20 unique variables matching "creatinine".
#> Warning: Both "2017-2018" and "2017-2020" are present. The 2017-2018 participants are
#> included in the 2017-2020 pandemic-adjusted file -- use one or the other in
#> pooled analyses to avoid double-counting.
# }