Package 'nhanesR'

Description

Counts deaths and accumulates person-years of exposure in the cells of one or more categorical covariates, and returns the crude mortality rate in each cell together with every marginal table (one-way, two-way, and so on) in the same long data frame.

Usage

mortality_tabulation(
  data,
  time,
  event,
  by,
  time_units = c("years", "months", "days"),
  scale = 1000,
  weights = NULL,
  expected = NULL,
  margins = TRUE,
  breaks = NULL,
  age_col = NULL,
  age_breaks = NULL,
  conf_level = 0.95
)

Arguments

Details

This is a rate tabulation, not a life table. The exposure basis is the follow-up time of everyone: decedents contribute time from entry to death and censored people contribute time from entry to censoring, so a rate is deaths divided by all person-years at risk, not only the exposure of those who died.

Margins are exact aggregates of the finest cells, with the rate recomputed from the margin's own deaths and person-years (rates are never averaged). A covariate that has been collapsed is labelled "All"; the grand total has every covariate set to "All". Confidence intervals are exact Poisson intervals on the death count, treating person-years as fixed.

Value

A data frame of class mortality_tabulation with one column per covariate in by, then n (people, or weighted people), deaths, pyears, rate, rate_lo, rate_hi, and with expected also expected, oe, oe_lo, oe_hi; the column n_cov counts how many covariates define each row (0 for the grand total). Rows are ordered by n_cov, then by the factor levels of by. With age_breaks, n counts the people who start follow-up in each cell.

See Also

tabulation_grid() to pivot two covariates into a grid; survival::pyears(), which does the same counting for fixed cells.

Examples

set.seed(1)
d <- data.frame(sex = sample(c("F", "M"), 500, TRUE),
                bmi = sample(c("<25", "25+"), 500, TRUE),
                t = rexp(500, 0.05))
d$dead <- as.integer(d$t < 12); d$t <- pmin(d$t, 12)
tab <- mortality_tabulation(d, time = "t", event = "dead", by = c("sex", "bmi"))
tab
tabulation_grid(tab, rows = "bmi", cols = "sex")

Description

Attaches CDC plain-language descriptions as column labels via NH_label, then calls describe. This is a convenience wrapper; for repeated use prefer NH_label() once so that labels persist across all subsequent Hmisc operations.

Usage

NH_describe(x, descriptions = NULL, all_weights = FALSE, ...)

Arguments

Details

Replicate weights (variables matching REP[0-9]+$, e.g. WTMREP01–WTMREP52 and WTIREP01–WTIREP52) are suppressed by default because they appear in NHANES DEMO files but are not needed for Taylor-series linearization variance estimation, which is the standard approach for NHANES analysis. Set all_weights = TRUE to include them.

Value

An object of class "describe" with CDC descriptions embedded as variable labels.

See Also

NH_label to attach labels to a data frame for persistent use; describe for the underlying engine.

Examples

tc <- nhanes_download_analyte("total cholesterol", "2015-2016")
invisible(NH_describe(tc))

# Include replicate weights in the output
demo_list <- nhanes_download("DEMO", nhanes_cycles()[1:10, "cycle"])
demo <- nhanes_stack(demo_list)
invisible(NH_describe(demo, all_weights = TRUE))

# Supply descriptions from a prior nhanes_search_variables() call
vars <- nhanes_search_variables("cholesterol")
invisible(NH_describe(tc, descriptions = vars))

Description

Looks up the plain-language CDC description for each column in a NHANES data frame and stores it as an "label" attribute on the column. Hmisc reads these attributes automatically in describe, Hmisc::summary(), Hmisc::html(), and other label-aware functions, so labelling once makes descriptions available everywhere.

Usage

NH_label(x, descriptions = NULL)

Arguments

Value

x with "label" attributes set on each column that could be matched to a CDC description. Columns with no catalog match are returned unchanged.

See Also

NH_describe for a one-step labelled describe; nhanes_search_variables to browse the variable catalog; label for the Hmisc label convention.

Examples

tc <- nhanes_download_analyte("total cholesterol", "2015-2016")
tc <- NH_label(tc)

# CDC descriptions now appear in all Hmisc label-aware output
invisible(Hmisc::describe(tc))

Description

nhanesR stores downloaded and parsed NHANES files in a local cache to avoid redundant downloads. By default the cache is placed in the standard user data directory for your operating system (see below). Use this function to view or change the location for the current session, or set it permanently in your .Rprofile.

Usage

nhanes_cache_dir(path = NULL, create = TRUE)

Arguments

Details

Package options

Three options control nhanesR behavior. Set any of them in your .Rprofile to make the change permanent across sessions; changes made during a session (via nhanes_cache_dir() or options() directly) last only until the session ends.

Default cache location

By default the cache lives inside R's session-temporary directory (tempdir()), so nhanesR never writes to your home directory without your consent. Downloaded files are re-fetched in each new R session. To keep a persistent cache, set nhanesR.cache_dir in your ⁠~/.Rprofile⁠.

Setting options permanently

Add lines like these to your ⁠~/.Rprofile⁠:

options(
  nhanesR.cache_dir = "/data/nhanes_cache",  # shared lab server path
  nhanesR.verbose   = FALSE,                  # suppress progress messages
  nhanesR.timeout   = 300L                    # 5-minute timeout for slow connections
)

Options set in .Rprofile take precedence over package defaults: nhanesR only sets an option at load time if it is not already defined.

Value

The current (or newly set) cache directory path, invisibly.

See Also

nhanes_download() and nhanes_download_analyte(), whose caching behavior is controlled by the options described above.

Examples

# View current cache location (defaults to a subdirectory of tempdir())
nhanes_cache_dir()

# Change to a custom session-local location (CRAN-safe)

nhanes_cache_dir(file.path(tempdir(), "my_nhanes_cache"))


# Suppress download messages for this session
options(nhanesR.verbose = FALSE)

# View all current nhanesR option values
Filter(function(x) startsWith(x, "nhanesR."), names(options()))

Description

Returns a data frame of all NHANES cycles known to nhanesR, including metadata about survey weights, pandemic adjustment status, and mortality linkage availability.

Usage

nhanes_cycles(include_iii = FALSE)

Arguments

Value

A tibble with one row per cycle and columns:

cycle

Character. Cycle label (e.g. "2015-2016").

begin_year, end_year

Integer. Survey years.

suffix

Character. Letter suffix appended to file codes.

wt_mec_2yr

Character. 2-year MEC exam weight variable name.

wt_int_2yr

Character. 2-year interview weight variable name.

wt_mec_4yr

Character. 4-year combined weight, where available.

wt_prepan

Character. Pre-pandemic weight for 2017-2020 cycle.

pandemic_adj

Logical. Was this cycle pandemic-adjusted?

has_lmf_public

Logical. Is a public-use LMF available?

censor_date

Character. Mortality follow-up censor date.

See Also

nhanes_manifest() to see what files are available within a cycle; nhanes_download() to download files; nhanes_lmf_cycles() for cycles that have public-use mortality linkage.

Examples

nhanes_cycles()
nhanes_cycles(include_iii = TRUE)

# Extract cycle labels as a character vector for use in download functions
cycles <- nhanes_cycles()[["cycle"]]
cycles[1:10]  # first ten continuous cycles (1999-2018)

Description

Downloads one or more NHANES component files in SAS transport (XPT) format from the CDC website, parses them into R data frames, attaches variable labels, and caches the results locally as RDS files.

Usage

nhanes_download(file_code, cycles, refresh = FALSE, add_cycle_col = TRUE)

Arguments

Details

Finding valid file codes

File codes are the base names CDC assigns to each data file, without the cycle-letter suffix or .xpt extension. For example, the Demographics file is always "DEMO", and the blood pressure examination file is "BPX".

Use nhanes_manifest() to browse all files available for a given cycle and component. The file_name column of the manifest shows the full CDC name including the cycle suffix (e.g. "TCHOL_I"); strip the trailing underscore-letter to get the base code for nhanes_download():

m <- nhanes_manifest("2015-2016", "Laboratory")
m[, c("file_name", "description")]

# Base codes ready for nhanes_download():
sub("_[A-Z]$", "", m$file_name)

Note that some analyte file names changed across cycles (e.g. total cholesterol: LAB13 -> L13_B -> TCHOL_D onward). For those cases, use nhanes_download_analyte() instead, which looks up the correct CDC filename for each cycle automatically via the variable catalog.

Invalid file codes

File codes are not validated before the download attempt. If an unknown code is supplied, CDC returns HTTP 200 with an HTML error page rather than a 404. nhanesR detects this via the Content-Type header and aborts with a message directing you to nhanes_manifest() to confirm the correct name.

Variable label encoding

NHANES XPT files were produced by SAS, which writes variable labels in the system locale of the generating server — typically Latin-1 (ISO 8859-1). Some biochemistry files (notably BIOPRO and its predecessors L40_C onward) use the Latin-1 byte 0xB5 for the micro prefix in SI unit strings such as umol/L. That byte is not valid UTF-8, so any downstream code that runs regular expressions over label attributes will receive an "unable to translate ... to a wide string" warning and the label will be skipped.

nhanesR guards against this internally by passing labels through iconv(..., to = "UTF-8", sub = "") before pattern matching in nhanes_harmonize(). If you read label attributes directly in your own code, apply the same conversion:

labels <- iconv(
  vapply(df, function(col) attr(col, "label") %||% "", character(1L)),
  to = "UTF-8", sub = ""
)

Value

If a single file_code and single cycle are requested, a data frame. If multiple file_codes or cycles are requested, a named list of data frames with names of the form "{file_code}_{cycle}".

See Also

nhanes_manifest() to browse available file codes; nhanes_download_analyte() for analytes whose file name changed across cycles; nhanes_cycles() for valid cycle labels.

Examples

# Browse available Laboratory files for a cycle, then download by base code
m <- nhanes_manifest("2015-2016", "Laboratory")
m[, c("file_name", "description")]   # see what's available
bpx <- nhanes_download("BPX", "2015-2016")

# Single file, single cycle
demo <- nhanes_download("DEMO", "2015-2016")

# Multiple cycles (returns list)
demos <- nhanes_download("DEMO", c("2013-2014", "2015-2016", "2017-2018"))

# Multiple files, single cycle
files <- nhanes_download(c("DEMO", "BPX", "TRIGLY"), "2015-2016")

Description

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

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

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)

# Serum creatinine (keep_vars excludes urine creatinine)
scr_list <- nhanes_download_analyte("creatinine", cycles,
                                    keep_vars = c("LBXSCR","LBDSCR","LB2SCR"))

Description

Diagnostic helper that reports median follow-up time, event rate, and maximum possible follow-up per cycle. Useful for assessing the asymmetric censoring problem when pooling cycles.

Usage

nhanes_followup_summary(data, cycle_col = "cycle")

Arguments

Value

A data frame with one row per cycle.

See Also

nhanes_survival_prep() which produces the required input.

Examples

demo <- nhanes_download("DEMO", "2015-2016")
linked <- nhanes_mortality_link(demo)
surv_data <- nhanes_survival_prep(linked, origin = "exam")
nhanes_followup_summary(surv_data)

Description

NHANES analytes are sometimes stored under different variable names in different cycles (e.g. HDL cholesterol: LBDHDL in 1999-2002, LBXHDD in 2003-2004, LBDHDD from 2005 onward). nhanes_harmonize() offers two ways to resolve this:

Usage

nhanes_harmonize(
  data_list,
  mapping = NULL,
  unit = NULL,
  name = NULL,
  label_pattern = NULL,
  units = c("conventional", "SI", "both"),
  trim = TRUE,
  stack = TRUE
)

Arguments

Details

• Unit-based (unit + name): scans column label attributes for the specified unit string (e.g. "mg/dL") and renames the matching column. No need to know the CDC variable codes in advance. Use label_pattern to disambiguate when a file contains multiple columns in the same unit (e.g. early cycles that bundled total cholesterol and HDL together).

• Explicit mapping (mapping): a named character vector of old -> new variable names. More verbose but unambiguous.

Value

If stack = TRUE (default), a single stacked data frame. When unit is used with trim = TRUE (the default), only SEQN, cycle, and the harmonized column are returned – ready for merging. If stack = FALSE, a named list of data frames.

See Also

nhanes_download_analyte() which produces the per-cycle list consumed by this function; nhanes_stack() for row-binding without renaming; nhanes_variable_map() to inspect variable names per cycle before choosing a mapping.

Examples

cycles <- nhanes_cycles()[1:10, "cycle"]

# Conventional units (default): returns SEQN + cycle + HDL_mgdl
hdl_list <- nhanes_download_analyte("HDL", cycles)
hdl <- nhanes_harmonize(hdl_list, unit = "mg/dL", name = "HDL_mgdl",
                         label_pattern = "HDL")

# SI units: retain mmol/L columns, drop conventional duplicates
hdl_si <- nhanes_harmonize(hdl_list, unit = "mmol/L", name = "HDL_mmol",
                            label_pattern = "HDL", units = "SI")

# Merge two analytes cleanly
tchol_list <- nhanes_download_analyte("total cholesterol", cycles)
TC  <- nhanes_harmonize(tchol_list, unit = "mg/dL", name = "TC_mgdl",
                         label_pattern = "total cholesterol")
lipids <- merge(hdl, TC, by = c("SEQN", "cycle"))

# Explicit mapping
hdl <- nhanes_harmonize(
  hdl_list,
  mapping = c(LBDHDL = "HDL_mgdl", LBXHDD = "HDL_mgdl",
              LBDHDD = "HDL_mgdl")
)

Description

List NHANES cycles with a public-use LMF

Usage

nhanes_lmf_cycles()

Value

Character vector of cycle labels.

See Also

nhanes_mortality_link(), nhanes_mortality_download()

Description

Queries the CDC NHANES data page for a given cycle and component, returning a data frame of available files with their download URLs and documentation links.

Usage

nhanes_manifest(cycle, component, refresh = FALSE)

Arguments

Details

Results are cached locally for the session to avoid repeated HTTP requests. Use refresh = TRUE to force re-query.

Value

A tibble with columns:

cycle

Cycle label.

component

Component name.

file_name

File code (e.g. "DEMO_I").

description

Plain-text description from CDC.

xpt_url

Direct URL to the XPT data file.

doc_url

URL to the HTML documentation/codebook page.

date_published

Date published, if available.

See Also

nhanes_cycles() for valid cycle labels; nhanes_download() to download a file by its base code; nhanes_search_variables() to search the variable catalog by keyword.

Examples

nhanes_manifest("2015-2016", "Laboratory")
nhanes_manifest("2015-2016", "Demographics")

Description

Joins two or more NHANES data frames on the SEQN respondent sequence number. Validates that survey design variables (PSU, strata, weights) are present and warns when merging across components that use different weight variables.

Usage

nhanes_merge(..., by = "SEQN", type = c("inner", "left"), weight_var = NULL)

Arguments

Details

Weight guidance

The appropriate weight depends on which components are merged:

• Demographics only -> WTINT2YR (interview weight)

• Any exam/lab component -> WTMEC2YR (MEC exam weight)

• Dietary 24-hr recall -> WTDRD1 or WTDR2D

• Multi-cycle pooled -> divide the 2-year weight by the number of cycles, or use the 4-year combined weight where available

This function warns but does not enforce weight selection. Use nhanes_cycles() to look up available weight variable names per cycle.

Value

A merged data frame. Duplicate columns (present in more than one input) are deduplicated, keeping the version from the first data frame where the column appears, with a warning.

See Also

nhanes_stack() to row-bind per-cycle lists before merging; nhanes_download() to obtain the component data frames; nhanes_mortality_link() to append mortality follow-up after merging.

Examples

demo  <- nhanes_download("DEMO",  "2015-2016")
bpx   <- nhanes_download("BPX",   "2015-2016")
trigly <- nhanes_download("TRIGLY","2015-2016")

analytic <- nhanes_merge(demo, bpx, trigly)

# Multi-cycle: use nhanes_stack() before merging
demo_list <- nhanes_download("DEMO", c("2013-2014", "2015-2016"))
bpx_list  <- nhanes_download("BPX",  c("2013-2014", "2015-2016"))
demo_pool <- nhanes_stack(demo_list)
bpx_pool  <- nhanes_stack(bpx_list)
analytic  <- nhanes_merge(demo_pool, bpx_pool, by = c("SEQN", "cycle"))

Description

Downloads the fixed-width .dat mortality files from the CDC FTP server for one or more NHANES cycles. Files are cached locally; re-downloading is skipped unless refresh = TRUE.

Usage

nhanes_mortality_download(
  cycles = NULL,
  refresh = FALSE,
  quiet = !getOption("nhanesR.verbose", TRUE)
)

Arguments

Details

The public-use LMF provides mortality follow-up through December 31, 2019 for NHANES 1999-2018 and NHANES III. Files were released in April 2022 and will not be updated (the 2022-linked restricted-use files require RDC access).

Value

Invisibly, a named character vector of local file paths (one per cycle). The primary side-effect is writing files to the cache directory under ⁠mortality/dat/⁠.

See Also

nhanes_mortality_parse(), nhanes_mortality_link(), nhanes_survival_prep()

Examples

# Download all available cycles
nhanes_mortality_download()

# Download specific cycles
nhanes_mortality_download(c("2013-2014", "2015-2016", "2017-2018"))

Description

Performs a left join of the parsed LMF onto a data frame containing NHANES participants, matched on the participant sequence number. Automatically handles multiple cycles by row-binding the appropriate LMF files before joining.

Usage

nhanes_mortality_link(
  nhanes_data,
  cycles = NULL,
  keep_vars = NULL,
  download = TRUE,
  seqn_col = "SEQN",
  cycle_col = "cycle"
)

Arguments

Details

Data from any source – nhanes_download(), nhanesA, or nhanesdata – can be linked by supplying the appropriate column name arguments. For example, nhanesdata stores the sequence number as seqn (integer) and the cycle as year (integer start year, e.g. 1999); pass ⁠seqn_col = "seqn", cycle_col = "year"⁠ and both are handled automatically.

Value

nhanes_data with LMF columns appended. Rows with no mortality record (SEQNs absent from the LMF) will have NA for all LMF columns; this should not occur for continuous NHANES 1999-2018.

See Also

nhanes_survival_prep() to convert the linked data into a survival dataset; nhanes_lmf_cycles() for cycles with a public-use LMF; nhanes_stack() to row-bind multi-cycle data before linking.

Examples

demo <- nhanes_download("DEMO", "2015-2016")
demo_mort <- nhanes_mortality_link(demo)

Description

Reads the fixed-width .dat files (downloading them first if needed) and returns a named list of data frames, one per cycle.

Usage

nhanes_mortality_parse(cycles = NULL, refresh = FALSE, download = TRUE)

Arguments

Details

Variable labels are attached as the "label" attribute on each column, following the haven/labelled convention.

Value

A named list of data frames. Each data frame contains:

SEQN

Respondent sequence number (join key to NHANES data).

ELIGSTAT

Eligibility: 1=eligible; 2=under 18; 3=insufficient data.

MORTSTAT

Vital status: 0=assumed alive; 1=assumed deceased.

UCOD_LEADING

Underlying cause of death (11-category ICD-10 recode).

DIABETES

Diabetes mentioned on death certificate (1=yes).

HYPERTEN

Hypertension mentioned on death certificate (1=yes).

PERMTH_INT

Months of follow-up from interview date.

PERMTH_EXM

Months of follow-up from examination date.

Note

For select records, PERMTH_INT, PERMTH_EXM, and UCOD_LEADING contain synthetic (perturbed) values introduced by CDC to reduce re-identification risk. MORTSTAT and ELIGSTAT are not perturbed.

See Also

nhanes_mortality_download() to download the raw .dat files; nhanes_mortality_link() to join parsed mortality data onto an analytic dataset.

Examples

lmf <- nhanes_mortality_parse(c("2015-2016", "2017-2018"))
lmf[["2015-2016"]]

Description

Searches the CDC NHANES variable catalog for variables whose name or description matches a keyword or phrase. Results are drawn from the CDC variable list pages and cached locally to avoid repeated HTTP requests.

Usage

nhanes_search_variables(
  term,
  component = NULL,
  refresh = FALSE,
  summarize = TRUE
)

Arguments

Details

This is the recommended way to find the correct file code and variable name for an analyte across NHANES cycles. For example, total cholesterol was stored in LAB13 (1999-2000), L13_B (2001-2002), L13_C (2003-2004), and TCHOL (2005 onwards), always in variable LBXTC.

Value

When summarize = TRUE (default), a data frame with columns:

variable_name

CDC variable code (e.g. LBXTC).

variable_desc

Plain-language description.

file_names

Comma-separated file codes across cycles.

cycles

Comma-separated cycle labels.

n_cycles

Number of cycles in which this variable appears.

When summarize = FALSE, one row per variable per cycle with an additional file_name and component column.

See Also

nhanes_variable_map() for a per-cycle file/variable lookup table ready for use with nhanes_download_analyte(); nhanes_manifest() to browse files rather than variables.

Examples

# Find total cholesterol across all cycles (summarized)
nhanes_search_variables("total cholesterol")

# Raw one-row-per-cycle output
nhanes_search_variables("total cholesterol", summarize = FALSE)

# Restrict to laboratory component
nhanes_search_variables("alanine", component = "Laboratory")

# Search for HDL cholesterol
nhanes_search_variables("HDL")

Description

Row-binds the same component across multiple cycles, enforcing that the cycle column is present and handling variable name changes across cycles.

Usage

nhanes_stack(..., fill = TRUE)

Arguments

Value

A single data frame with all cycles stacked. A cycle column is always included.

See Also

nhanes_harmonize() which calls this internally and also renames variables across cycles; nhanes_merge() to join components by SEQN; nhanes_mortality_link() which expects a stacked data frame as input.

Examples

demos <- nhanes_download("DEMO", c("2013-2014", "2015-2016", "2017-2018"))
stacked <- nhanes_stack(demos)

Description

Takes a linked NHANES-mortality data frame (from nhanes_mortality_link()) and returns a dataset ready for use with survival::Surv(), with:

Usage

nhanes_survival_prep(
  data,
  origin = c("exam", "interview"),
  time_unit = c("months", "years"),
  cause = NULL,
  weight_var = NULL,
  seqn_col = "SEQN",
  cycle_col = "cycle"
)

Arguments

Details

• Ineligible participants (ELIGSTAT != 1) removed with a warning

• A time column (in months or years) from the specified follow-up origin

• An event column (0/1) from MORTSTAT

• Optional cause-specific event indicator based on UCOD_LEADING

• Survey weight column renamed and validated

Value

A data frame with additional columns:

time

Follow-up time in specified units.

event

All-cause mortality indicator (0/1).

event_cause

Cause-specific indicator, if cause supplied.

survey_weight

Survey weight, renamed from weight_var.

.eligstat_dropped

Attribute recording how many rows were removed.

Eligibility filtering

Participants with ELIGSTAT != 1 are automatically removed with a warning. This includes those under 18 at time of survey (ELIGSTAT == 2) and those with insufficient identifying data for linkage (ELIGSTAT == 3). The number dropped is reported and attached as an attribute.

Asymmetric follow-up across cycles

All public-use LMF files censor at December 31, 2019. Participants enrolled in later cycles (e.g. 2017-2018) have substantially shorter maximum follow-up than those enrolled in 1999-2000. This function warns when multiple cycles are detected, as this asymmetry must be accounted for in any pooled analysis.

Survey weights

NHANES provides three families of survey weight, each correcting for a different sampling stage. Choosing the wrong weight produces biased point estimates and incorrect standard errors.

The fasting subsample weight (WTSAF2YR) is a statistical probability weight – not a body-weight measurement – that accounts for the additional random subsampling of participants asked to fast before their blood draw. Fasting participants are a minority of all MEC attendees; using WTMEC2YR for fasting analytes ignores this extra subsampling step and will give incorrect population estimates.

For pooled multi-cycle analyses, CDC guidance scales weights by the number of pooled cycles (n). This function applies that automatically when a 2-year weight is supplied:

• If both 1999-2000 and 2001-2002 are present and the corresponding 4-year weight column exists (e.g., WTMEC4YR for WTMEC2YR), those two early cycles are scaled as ⁠4-year weight * (2/n)⁠.

• All later cycles are scaled as ⁠2-year weight * (1/n)⁠.

• If the early-pair 4-year weight column is unavailable, all cycles fall back to ⁠2-year weight * (1/n)⁠.

The original unscaled 2-year weight is preserved in survey_weight_2yr_raw.

Perturbed variables

PERMTH_INT, PERMTH_EXM, and UCOD_LEADING contain synthetic values for select records (CDC data perturbation to reduce re-identification risk). MORTSTAT is not perturbed. Cause-specific analyses using UCOD_LEADING should be interpreted with this in mind.

See Also

nhanes_mortality_link() which produces the input for this function; nhanes_followup_summary() to check follow-up time by cycle; nhanes_ucod_labels() for cause-of-death codes accepted by cause.

Examples

demo_list <- nhanes_download("DEMO", c("2013-2014", "2015-2016"))
demo <- nhanes_stack(demo_list)
demo_mort <- nhanes_mortality_link(demo)

# All-cause mortality, exam origin, MEC 2-year weight
surv_data <- nhanes_survival_prep(
  demo_mort,
  origin     = "exam",
  time_unit  = "years",
  weight_var = "WTMEC2YR"
)

# Cause-specific: cardiovascular (code "001")
surv_data_cvd <- nhanes_survival_prep(
  demo_mort,
  origin = "exam",
  cause  = "001",
  weight_var = "WTMEC2YR"
)

# Use with survival package
library(survival)
library(survey)
design <- svydesign(
  id      = ~SDMVPSU,
  strata  = ~SDMVSTRA,
  weights = ~survey_weight,
  nest    = TRUE,
  data    = surv_data
)

Description

Returns the ICD-10 recode table used in the public-use LMF UCOD_LEADING variable, including code, plain-language label, and ICD-10 chapter ranges.

Usage

nhanes_ucod_labels()

Value

A data frame with columns code, label, icd10_range.

See Also

nhanes_survival_prep() where the cause argument accepts these codes.

Examples

nhanes_ucod_labels()

Description

Wraps nhanes_search_variables() to return a single-row-per-cycle lookup table showing which variable name and file to use for a given analyte across NHANES cycles. Useful for analytes whose variable names changed between cycles (e.g. HDL cholesterol: LBDHDL -> LBXHDD -> LBDHDD).

Usage

nhanes_variable_map(
  term,
  component = "Laboratory",
  keep_vars = NULL,
  include_reliability = FALSE,
  refresh = FALSE
)

Arguments

Details

When multiple variables match within a cycle (e.g. mg/dL and mmol/L versions), the function prefers the non-SI variable. Comment-code variables (suffix LC/LCN or "comment" in description) are always dropped.

Value

A data frame with columns cycle, variable_name, and file_name, one row per cycle in which the analyte was measured. Returns zero rows if nothing matches.

See Also

nhanes_search_variables() for the underlying keyword search; nhanes_download_analyte() which uses this map to resolve filenames automatically.

Examples

# HDL cholesterol across all cycles
nhanes_variable_map("HDL")

# Serum creatinine only (exclude urine variables)
nhanes_variable_map("creatinine",
                    keep_vars = c("LBXSCR", "LBDSCR", "LB2SCR"))

# Urinary albumin only
nhanes_variable_map("albumin", keep_vars = c("URXUMA", "UR2UMA", "UR1MA"))

Description

Fetches the data file, its SAS program (which holds the column positions and variable labels) and the codebook PDF, and keeps them in the nhanesR cache (see nhanes_cache_dir()) so they are downloaded once. The exam file is about 195 MB, so the download timeout is raised to at least 15 minutes for these files.

Usage

nhanes3_download(file, what = c("sas", "dat", "codebook"), refresh = FALSE)

Arguments

Details

The .sas file is small. It is enough for nhanes3_layout(), so you can look through the variables before deciding to download the large .dat.

Value

Invisibly, a named character vector of the local paths.

See Also

nhanes3_layout(), nhanes3_read()

Examples

## Not run: 
# the small SAS program only: enough to browse the variables
nhanes3_download("adult", what = "sas")

## End(Not run)

Description

NHANES III (1988-1994) predates the per-cycle XPT files of continuous NHANES. Its public-use data are a few large fixed-width .dat files, each with a SAS program (.sas) that gives the column positions and variable labels, and a codebook PDF. This lists the files nhanes3_download(), nhanes3_layout() and nhanes3_read() know by name.

Usage

nhanes3_files()

Value

A data frame with file (the name to pass to the other functions), folder on the CDC server, a description, and the dat_url, sas_url and codebook_url of each file.

See Also

nhanes3_layout() to see what is in a file, nhanes3_read() to read chosen columns. The nhanes-iii vignette walks through the whole workflow.

Examples

nhanes3_files()

Description

Parses the SAS program that ships with each NHANES III file. This is the stage where you can stop and choose which columns to read: the exam file has more than 2,000 and the adult questionnaire more than 1,200, and reading a handful by position is fast while reading them all is not. Only the small .sas file is needed, not the large .dat.

Usage

nhanes3_layout(
  file,
  pattern = NULL,
  ignore.case = TRUE,
  sas_file = NULL,
  refresh = FALSE
)

Arguments

Details

Labels are the short descriptions from the SAS program (for example "How tall are you without shoes - inches"). Value labels and the missing-value codes of each variable are in the codebook PDF, and a variable's own special codes (for example 666 for "varies") are not the same as the all-8s/all-9s codes that nhanes3_read() can recode; check the codebook before recoding (see the nhanes-iii vignette).

Value

A data frame of class nhanes3_layout with one row per variable: var, label (NA if the SAS program gives none), start, end, width (the number of characters in the field) and type ("numeric" or "character"). The record length is checked against the layout and stored in attr(, "lrecl").

See Also

nhanes3_read(), nhanes3_files()

Examples

## Not run: 
nhanes3_layout("adult", pattern = "tall|weigh")   # heights and weights people reported
nhanes3_layout("exam", pattern = "^BMP")          # the body-measure variables

## End(Not run)

Description

Reads only the columns you ask for from the large fixed-width .dat file, using the positions in its SAS program (nhanes3_layout()). Choose the columns by name with vars, or, in an interactive session, leave vars out to pick them from a list (use pattern to shorten the list first). SEQN, the respondent ID used to link files and mortality, is always included when the file has it.

Usage

nhanes3_read(
  file,
  vars = NULL,
  pattern = NULL,
  recode = NULL,
  id = "SEQN",
  dat_file = NULL,
  sas_file = NULL,
  n_max = Inf
)

Arguments

Details

NHANES III stores "blank but applicable" as all 8s and "don't know" as all 9s, sized to the field (8/9 for a one-character item, 88888/99999 for a five-character measurement). Left in place they look like real values. recode turns these into NA for the variables you name. It is not applied to everything: IDs, weights and age have no such codes, and many items have special codes of their own (666 for "varies", 777 for "less than 1 per day"), so check the codebook (nhanes3_download() with what = "codebook") first.

Value

A tibble with the requested columns (numeric, except any $ character columns). It carries attr(, "width"), the width of each field, and attr(, "var_labels"), the SAS labels.

See Also

nhanes3_layout(), nhanes3_files(), nhanes_mortality_parse() for the NHANES III linked mortality file.

Examples

## Not run: 
exam <- nhanes3_read("exam", c("HSSEX", "HSAGEIR", "BMPHT", "BMPWT", "WTPFEX6"),
                     recode = c("BMPHT", "BMPWT"))

## End(Not run)

Description

List NHIS survey years with Household/Person data available

Usage

nhis_data_years(module = c("either", "household", "person"))

Arguments

Value

Character vector of NHIS survey years.

The 1989 Household gap

1989's Household .zip is confirmed absent from the CDC server (HTTP 404), despite that year's own documentation (readme.txt) listing a Household file in its file table (48,054 records, the same 335-byte record length as every other core file that year). The matching HOUSEHLD.SAS syntax file is still present – only the data file itself is missing. Every case/extension variant (.EXE/.exe/.ZIP/.zip, upper/lower filename) was checked before concluding this is a genuine absence on NCHS's end rather than a URL-pattern issue here. 1989's Person file is unaffected.

See Also

nhis_download()

Description

Downloads the fixed-width .zip, unzips it, downloads the matching SAS input-syntax file NCHS publishes alongside it, and parses both together using SAScii::read.SAScii() – reusing NCHS's own column-position specification rather than a hand-built one. Results are cached locally as RDS files, same convention as nhanes_download() and nhis_mortality_parse().

Usage

nhis_download(module, years = NULL, refresh = FALSE)

Arguments

Value

If a single year is requested, a data frame. If multiple years are requested, a named list of data frames keyed by year. Every returned data frame carries a .nhis_data_year integer column (the requested survey year, not to be confused with a native YEAR/ SRVY_YR column the file itself may already contain).

Column names differ by era

1997 onward uses NCHS's own descriptive variable names directly (SRVY_YR, HHX, WTFA_HH, ...), taken straight from that era's SAS syntax file. 1986-1996 uses NCHS's original placeholder scheme instead (e.g. HH_22, PX_24) – that's literally what those years' SAS syntax files contain. Column NAMES are never changed (a placeholder stays a placeholder), but for 1986-1991 each placeholder column gets a "label" attribute (haven/labelled convention, same as every other labelled column in this package) with its real meaning, built from that year's own NHISCORE.PDF codebook (data-raw/build_nhis_pre1997_crosswalk.R). Check with attr(df$HH_22, "label"), or NH_describe() to see all of them at once. 1992-1996 do not get labels – checked directly, not just left undone: the source PDF's own page layout changes enough starting in 1992 (its NHISCORE.PDF roughly triples in page count that year) that the crosswalk-building parser's match rate drops hard, and unlike 1986-1991, a meaningful share of what doesn't match already has a descriptive native variable name anyway (e.g. REGION, HEIGHT, WEIGHT for 1993), so the gap matters less than the raw match-rate drop suggests. Extending the crosswalk past 1991 is possible future work, not done here.

See Also

nhis_data_years() for years with data available; nhis_mortality_link() to join mortality follow-up onto the result.

Examples

hh_2015 <- nhis_download("household", "2015")

Description

List NHIS survey years with a public-use LMF

Usage

nhis_lmf_years()

Value

Character vector of NHIS survey years, "1986" through "2018".

See Also

nhis_mortality_link(), nhis_mortality_download()

Description

Downloads the fixed-width .dat mortality files from the CDC FTP server for one or more NHIS survey years. Files are cached locally; re-downloading is skipped unless refresh = TRUE.

Usage

nhis_mortality_download(
  years = NULL,
  refresh = FALSE,
  quiet = !getOption("nhanesR.verbose", TRUE)
)

Arguments

Details

NCHS distributes NHIS mortality linkage as one file per survey year (unlike NHANES's one file per 2-year cycle). The public-use LMF provides mortality follow-up through December 31, 2019 for NHIS 1986-2018.

Value

Invisibly, a named character vector of local file paths (one per year). The primary side-effect is writing files to the cache directory under ⁠mortality/dat/⁠.

See Also

nhis_mortality_parse(), nhis_mortality_link(), nhanes_mortality_download() for the NHANES equivalent.

Examples

# Download specific years (downloading all 33 available years at once,
# via nhis_mortality_download() with no arguments, works the same way but
# is a much larger multi-file FTP batch -- prefer a specific year vector
# for routine use)
nhis_mortality_download(c("2015", "2016", "2017"))

Description

Performs a left join of the parsed NHIS LMF onto a data frame containing NHIS participants, matched on the participant public-use ID and survey year.

Usage

nhis_mortality_link(
  nhis_data,
  years = NULL,
  keep_vars = NULL,
  download = TRUE,
  publicid_col = "PUBLICID",
  year_col = "SRVY_YR"
)

Arguments

Details

nhis_data must come from somewhere else – nhanesR does not download NHIS survey data (see the package-level scoping note in this file's source, or ?nhis_mortality_download). Typical sources are NCHS's own NHIS public-use microdata site or IPUMS Health Surveys (IPUMS NHIS).

Value

nhis_data with LMF columns appended. Rows with no mortality record (PUBLICID/year combinations absent from the LMF) will have NA for all LMF columns.

Why the join requires a year column, unlike nhanes_mortality_link()

nhanes_mortality_link() matches on SEQN alone, which is safe because NHANES's SEQN numbering does not overlap across the 2-year cycles this package pools. NHIS's PUBLICID construction is not documented clearly enough (see NCHS's linkage-methods appendix, referenced in the LMF codebook) to assume the same global uniqueness across survey years, so this function matches conservatively on the ⁠(PUBLICID, year)⁠ pair rather than PUBLICID alone.

See Also

nhis_lmf_years() for years with a public-use LMF; nhis_mortality_parse() which produces the input to this join; nhanes_mortality_link() for the NHANES equivalent.

Examples

# nhis_data must be supplied from elsewhere -- nhanesR does not download it
# nhis_data <- your_nhis_loading_function(...)
# nhis_data_mort <- nhis_mortality_link(nhis_data)

Description

Reads the fixed-width .dat files (downloading them first if needed) and returns a named list of data frames, one per survey year.

Usage

nhis_mortality_parse(years = NULL, refresh = FALSE, download = TRUE)

Arguments

Details

Variable labels are attached as the "label" attribute on each column, following the haven/labelled convention – same as nhanes_mortality_parse().

Value

A named list of data frames. Each data frame contains:

PUBLICID

NHIS public-use identifier (join key – character, not numeric; NHIS does not use NHANES's SEQN).

ELIGSTAT

Eligibility: 1=eligible; 2=under 18; 3=insufficient data.

MORTSTAT

Vital status: 0=assumed alive; 1=assumed deceased.

UCOD_LEADING

Underlying cause of death (ICD-10 recode).

DIABETES

Diabetes mentioned on death certificate (1=yes).

HYPERTEN

Hypertension mentioned on death certificate (1=yes).

DODQTR

Quarter of death (1-4).

DODYEAR

Year of death.

WGT_NEW

Person-level sample weight, adjusted for linkage ineligibility. Blank for 1986 (NCHS recommends WTFA from the NHIS public-use file that year instead).

SA_WGT_NEW

Sample Adult sample weight, adjusted for linkage ineligibility. Only populated 1997 onward (the Sample Adult File did not exist before the 1997 NHIS redesign).

Note

Unlike the NHANES LMF, NHIS's public-use LMF has no PERMTH_INT/PERMTH_EXM-equivalent person-months variable. Constructing follow-up time requires combining DODQTR/DODYEAR with the participant's own NHIS interview year/quarter, which comes from the NHIS survey data itself, not this file. There is no nhis_survival_prep() analogous to nhanes_survival_prep() for this reason – see nhis_mortality_link()'s documentation for how far this package takes NHIS mortality linkage.

See Also

nhis_mortality_download() to download the raw .dat files; nhis_mortality_link() to join parsed mortality data onto NHIS data.

Examples

lmf <- nhis_mortality_parse(c("2015", "2016"))
lmf[["2015"]]

Description

Takes a fitted cph object and a fitted svycoxph object with the same formula, and returns a modified cph-class object with survey-correct coefficients and variance-covariance matrix while preserving the rms $Design structure needed for anova.rms(), Predict(), summary.rms(), and related generics.

Usage

svycph_fuse(fit_cph, fit_svy)

Arguments

Details

anova.rms() constructs Wald tests as $(L\beta)^\top (LVL^\top)^{-1} (L\beta)$ where $L$ is a contrast matrix derived from $Design and $V$ is $var. Substituting the survey-corrected $V$ from svycoxph yields design-correct Wald statistics while preserving the rms term-identification machinery.

Degrees of freedom in anova.rms() are based on contrast matrix rank, not survey PSU count. For fully correct F-test df, use survey::regTermTest() directly on fit_svy.

Value

A modified cph object with survey-correct inference. The $var slot contains the sandwich variance-covariance matrix from fit_svy; $coefficients contains the weighted partial likelihood estimates. The $Design and all structural slots are preserved from fit_cph.

References

Binder, D.A. (1992). Fitting Cox's proportional hazards models from survey data. Biometrika, 79(1), 139–147.

Lin, D.Y. (2000). On fitting Cox's proportional hazards models to survey data. Biometrika, 87(1), 37–47.

See Also

weighted_basehaz, svycph_set_basehaz

Description

Replaces the baseline hazard estimate in a fused cph object with the survey-weighted version from weighted_basehaz(), enabling survplot() to produce design-correct survival curves.

Usage

svycph_set_basehaz(fit_fused, h0)

Arguments

Value

The modified fused object with weighted baseline hazard.

See Also

svycph_fuse, weighted_basehaz

Description

Extracts one statistic from a mortality_tabulation() result as a matrix with one covariate down the rows and another across the columns. The margins ("All") are included as the last row and column.

Usage

tabulation_grid(tab, rows, cols, value = "rate", fixed = NULL)

Arguments

Value

A matrix with rows levels (plus "All") by cols levels (plus "All").

See Also

mortality_tabulation()

Description

Implements the weighted Breslow estimator and its linearization-based variance following Lin (2000). The point estimate weights each event's contribution by its survey weight; the variance uses the influence function of the weighted estimator combined with the survey design's stratified cluster structure.

Usage

weighted_basehaz(
  fit_svy,
  design,
  centered = TRUE,
  se_type = c("lin", "greenwood")
)

Arguments

Details

The weighted Breslow increment at each event time $t_k$ is:

$d\hat{H}_0^w(t_k) = \frac{\sum_{i: t_i = t_k, \delta_i=1} w_i} {\sum_{j \in \mathcal{R}(t_k)} w_j \exp(\mathbf{X}_j^\top \hat{\beta})}$

The influence function of $d\hat{H}_0^w(t_k)$ for observation $i$ is (Lin 2000, eq. 2.3):

$\phi_i(t_k) = \frac{I(t_i = t_k,\, \delta_i = 1)}{Y^w(t_k)} - \frac{n^w(t_k)}{[Y^w(t_k)]^2}\, I(t_i \geq t_k)\, \exp(\mathbf{X}_i^\top\hat{\beta})$

where $Y^w(t_k) = \sum_{j \in \mathcal{R}(t_k)} w_j \exp(\mathbf{X}_j^\top\hat{\beta})$ and $n^w(t_k) = \sum_{i: t_i=t_k, \delta_i=1} w_i$.

The cumulative influence $\Phi_i(t) = \sum_{t_k \leq t} \phi_i(t_k)$ is used to construct the linearization variance estimate (Lin 2000, eq. 2.4):

$\widehat{\mathrm{Var}}(\hat{H}_0^w(t)) = \sum_h \frac{n_h}{n_h - 1} \sum_{\alpha \in h} \left(e_{h\alpha}(t) - \bar{e}_h(t)\right)^2$

where $e_{h\alpha}(t) = \sum_{i \in \text{PSU}\,\alpha} \Phi_i(t)$ is the PSU-level total of influence functions within stratum $h$.

Note: this variance conditions on $\hat{\beta}$ and does not propagate uncertainty from coefficient estimation. For large samples this contribution is negligible relative to the design variance.

Value

A data frame with columns:

Choosing se_type

For NHANES-scale populations the Lin design variance is orders of magnitude smaller than the Greenwood-weighted variance because the former captures only PSU-selection uncertainty (very small for rare events), while the latter captures statistical uncertainty from the weighted event count. The ratio is approximately proportional to the square root of the mean survey weight. Use se_type = "greenwood" when the goal is survplot() confidence bands that convey statistical reliability; use "lin" when the goal is design-consistent variance for formal population inference.

References

Lin, D.Y. (2000). On fitting Cox's proportional hazards models to survey data. Biometrika, 87(1), 37–47.

See Also

svycph_fuse, svycph_set_basehaz