GitHub

API reference

Nothing is exported, so every name below is reached as NHANES.name. This page is the supported surface. Anything absent from it is an implementation detail, documented under Internals.

NHANES.DownloadError — Type
DownloadError <: NHANESError

Thrown when downloading data from CDC fails.

Fields

  • url::String: The URL that failed
  • message::String: Descriptive error message
  • status::Union{Int,Nothing}: HTTP status code if available
source
NHANES.MetadataError — Type
MetadataError <: NHANESError

Thrown when parsing metadata (codebooks, variable lists) fails.

Fields

  • source::String: The metadata source (e.g., "codebook", "variable_list")
  • message::String: Descriptive error message
source
NHANES.TableNotFoundError — Type
TableNotFoundError <: NHANESError

Thrown when a requested NHANES table does not exist.

Fields

  • table::String: The requested table name
  • message::String: Descriptive error message
source
NHANES.codebook — Method
codebook(table::AbstractString, variable::Symbol; force::Bool=false) -> DataFrame

Get the codebook (value codes and labels) for a variable.

Codes and labels come from the CDC codebook page, one row per row CDC publishes. Counts are computed from the data, so a continuous variable reports how many observations fall in its published range rather than one row per distinct measurement.

Arguments

  • table::AbstractString: Table name with suffix (e.g., "DEMO_J")
  • variable::Symbol: Variable name (e.g., :RIAGENDR)
  • force::Bool=false: Force refresh from CDC (ignore cache)

Returns

  • DataFrame: Value codes with columns:
    • code::String: Code exactly as CDC publishes it, "." for missing
    • label::String: Human-readable label
    • count::Int: Number of observations in the data

Examples

# Get gender codes from 2017-2018 Demographics
NHANES.codebook("DEMO_J", :RIAGENDR)
# code | label   | count
# "1"  | Male    | 4557
# "2"  | Female  | 4697
# "."  | Missing | 0

# A continuous variable reports its range, not every observed value
NHANES.codebook("BMX_J", :BMXWT)
# code           | label           | count
# "3.2 to 242.6" | Range of Values | 8580
# "."            | Missing         | 124

See Also

source
NHANES.download — Method
download(table::AbstractString; translate::Bool=true, force::Bool=false) -> DataFrame

Download an NHANES data table and return it as a DataFrame.

Translation applies to categorical variables only. A variable whose codebook publishes a range of values is a measurement, so its column keeps its numeric element type and its coded missing values (7777 "Refused", 9999 "Don't know" and friends) stay numeric. Call codebook to find out which numbers a continuous variable reserves for those meanings, and filter them out before analysis.

Arguments

  • table::AbstractString: Table name with suffix (e.g., "DEMO_J" for 2017-2018 Demographics)
  • translate::Bool=true: Translate coded values to human-readable labels
  • force::Bool=false: If true, re-download even if cached

Returns

  • DataFrame: The requested data table

Throws

  • TableNotFoundError: If CDC has no such table
  • DownloadError: If the download fails for any other reason

Examples

# Download 2017-2018 Demographics
demo = NHANES.download("DEMO_J")

# Download without value translation
demo = NHANES.download("DEMO_J"; translate=false)

See Also

  • tables: List available tables for a component and year
  • variables: List variables in a table
  • codebook: Codes and labels for a single variable
source
NHANES.dxa — Method
dxa(year::Int; suppl::Bool=false, force::Bool=false) -> DataFrame

Download DXA data for a survey cycle.

Note: DXA data contains 5 sets of imputed values per participant. Analyze all 5 sets separately - do NOT average them.

Arguments

  • year::Int: Start year (1999, 2001, 2003, or 2005)
  • suppl::Bool=false: If true, download supplemental data (highly variable imputation)
  • force::Bool=false: Force re-download even if cached

Returns

  • DataFrame: DXA measurements with 5 imputation sets

Examples

dxa_data = NHANES.dxa(2005)
dxa_suppl = NHANES.dxa(2005; suppl=true)

Throws

  • ArgumentError: If the year has no DXA data
  • TableNotFoundError: If CDC has no file for the table
  • DownloadError: If the download fails for any other reason

See Also

source
NHANES.dxa_tables — Method
dxa_tables(year::Int; suppl::Bool=false) -> DataFrame

List available DXA tables for a survey cycle.

Arguments

  • year::Int: Start year (1999, 2001, 2003, or 2005)
  • suppl::Bool=false: If true, list supplemental tables (highly variable imputation data)

Returns

  • DataFrame: Available DXA tables with columns: name, description, url

Examples

NHANES.dxa_tables(2005)
NHANES.dxa_tables(2005; suppl=true)
source
NHANES.historical_download — Method
historical_download(survey::Symbol, name::AbstractString; force::Bool=false) -> DataFrame

Download a historical NHANES SAS transport file and return it as a DataFrame.

name is resolved against the historical_tables listing for survey. Only transport files (.xpt) can be read this way, which in practice means NHANES III. NHANES I and II publish fixed-width text whose column layout lives in a separate SAS input statement, so fetch those with historical_file and parse them yourself.

Codes are left as published. Historical surveys have no codebook pages of the kind translate reads.

Arguments

  • survey::Symbol: One of :nhanes1, :nhanes2, :nhanes3
  • name::AbstractString: File name as reported by historical_tables
  • force::Bool=false: If true, re-download even if cached

Returns

  • DataFrame: The requested data file

Throws

  • ArgumentError: If the survey is unknown, or the file is not a transport file
  • TableNotFoundError: If the listing holds no file of that name
  • DownloadError: If the download fails

Examples

NHANES.historical_download(:nhanes3, "SSNH3MGM")

See Also

source
NHANES.historical_file — Method
historical_file(survey::Symbol, name::AbstractString; force::Bool=false) -> String

Download a historical NHANES data file into the cache and return its path.

Handles every file historical_tables lists, whatever its format. Use it for the fixed-width text of NHANES I and II: reading those needs the column layout from the SAS input statement CDC publishes beside the data, which this package does not carry.

Arguments

  • survey::Symbol: One of :nhanes1, :nhanes2, :nhanes3
  • name::AbstractString: File name as reported by historical_tables
  • force::Bool=false: If true, re-download even if cached

Returns

  • String: Path to the cached file, under the extension CDC publishes

Throws

  • ArgumentError: If the survey is not one of the historical surveys
  • TableNotFoundError: If the listing holds no file of that name
  • DownloadError: If the download fails

Examples

path = NHANES.historical_file(:nhanes1, "DU4111")

See Also

source
NHANES.historical_tables — Method
historical_tables(survey::Symbol; force::Bool=false) -> DataFrame

List available data files for a historical NHANES survey.

Arguments

  • survey::Symbol: One of :nhanes1, :nhanes2, :nhanes3
  • force::Bool=false: Force refresh from CDC (ignore cache)

Returns

  • DataFrame: Available data files with columns: name, description, url

Examples

NHANES.historical_tables(:nhanes3)

Throws

  • ArgumentError: If the survey is not one of the historical surveys
  • DownloadError: If the listing page cannot be fetched

Note

Historical survey data has different structure than continuous NHANES, so download does not handle it. Fetch a listed file with historical_download for the SAS transport files NHANES III publishes, or historical_file for the fixed-width text files of NHANES I and II.

See Also

source
NHANES.search — Method
search(pattern::AbstractString; component::Union{Symbol,Nothing}=nothing,
       years::Union{Int,AbstractRange,Nothing}=nothing,
       force::Bool=false) -> DataFrame

Search for variables matching a pattern across NHANES tables.

Each component and cycle needs one variable list page from CDC, and those pages run to several hundred kilobytes. An unfiltered search fetches one per combination, around 60 pages, SEARCH_CONCURRENCY at a time. Results are cached, so later calls are fast. Narrow the search with component and years to fetch fewer pages.

Arguments

  • pattern::AbstractString: Regex pattern to match variable names or descriptions
  • component::Union{Symbol,Nothing}=nothing: Filter to specific component
  • years::Union{Int,AbstractRange,Nothing}=nothing: Filter to specific survey cycles
  • force::Bool=false: Force refresh from CDC (ignore cached variable lists)

Returns

  • DataFrame: Matching variables with columns:
    • variable: Variable name
    • description: Variable description
    • table: Table containing the variable
    • component: Component type
    • cycle: Survey cycle start year, or :P for pre-pandemic

Examples

# Search for blood pressure variables
NHANES.search("blood pressure")

# Search in Laboratory component only
NHANES.search("glucose"; component=:Laboratory)

# Search in specific years
NHANES.search("BMI"; years=2015:2018)

See Also

source
NHANES.search_table_names — Method
search_table_names(pattern::AbstractString;
                   component::Union{Symbol,Nothing}=nothing,
                   years::Union{Int,AbstractRange,Nothing}=nothing,
                   force::Bool=false) -> DataFrame

Search for tables by name pattern.

Table lists come from the same CDC pages as search, so the same fetching cost applies.

Arguments

  • pattern::AbstractString: Regex pattern to match table names
  • component::Union{Symbol,Nothing}=nothing: Filter to specific component
  • years::Union{Int,AbstractRange,Nothing}=nothing: Filter to specific survey cycles
  • force::Bool=false: Force refresh from CDC (ignore cached table lists)

Returns

  • DataFrame: Matching tables with columns:
    • name: Table name
    • description: Table description
    • component: Component type
    • cycle: Survey cycle start year, or :P for pre-pandemic

Examples

# Find all BMX tables
NHANES.search_table_names("BMX")

# Find tables in Laboratory component
NHANES.search_table_names("GLU"; component=:Laboratory)

See Also

source
NHANES.search_var_name — Method
search_var_name(varname::AbstractString;
                years::Union{Int,AbstractRange,Nothing}=nothing,
                force::Bool=false) -> DataFrame

Search for a specific variable name across all NHANES tables.

Searches every component, so the same fetching cost as search applies.

Arguments

  • varname::AbstractString: Exact variable name to search for (case-insensitive)
  • years::Union{Int,AbstractRange,Nothing}=nothing: Filter to specific survey cycles
  • force::Bool=false: Force refresh from CDC (ignore cached variable lists)

Returns

  • DataFrame: Tables containing the variable with columns:
    • variable: Variable name
    • table: Table name
    • component: Component type
    • cycle: Survey cycle start year, or :P for pre-pandemic

Examples

# Find all tables containing BMXLEG variable
NHANES.search_var_name("BMXLEG")

# Search in specific years
NHANES.search_var_name("BPXPULS"; years=2005:2010)

See Also

source
NHANES.tables — Method
tables(component::Symbol, year::Union{Int,Symbol}; force::Bool=false) -> DataFrame

List available data tables for a component and survey cycle.

Arguments

  • component::Symbol: One of :Demographics, :Dietary, :Examination, :Laboratory, :Questionnaire
  • year::Union{Int,Symbol}: Start year of the survey cycle (e.g., 2017), or :P for pre-pandemic
  • force::Bool=false: Force refresh from CDC (ignore cache)

Returns

  • DataFrame: Available tables with columns:
    • name: Table name (e.g., "DEMOJ", "PBMX")
    • description: Table description

Examples

# List all laboratory tables for 2017-2018
NHANES.tables(:Laboratory, 2017)

# List demographics tables for 2015-2016
NHANES.tables(:Demographics, 2015)

# List pre-pandemic examination tables (2017-March 2020)
NHANES.tables(:Examination, :P)

See Also

source
NHANES.translate! — Method
translate!(df::DataFrame, table::AbstractString, column::Symbol)

Replace numeric codes with text labels in-place.

Only the codebook labels are fetched, so translating several columns reads the data table once.

Arguments

  • df::DataFrame: DataFrame to modify
  • table::AbstractString: Table name (for looking up codebook)
  • column::Symbol: Column to translate

Throws

  • MetadataError: If the codebook does not describe the column
  • ArgumentError: If the column holds measurements rather than codes

Examples

demo = NHANES.download("DEMO_J"; translate=false)
NHANES.translate!(demo, "DEMO_J", :RIAGENDR)
# Column now contains "Male"/"Female" instead of 1/2

See Also

source
NHANES.translate! — Method
translate!(df::DataFrame, table::AbstractString, columns::Vector{Symbol})

Translate multiple columns in-place.

source
NHANES.translate — Method
translate(df::DataFrame, table::AbstractString, column::Symbol) -> DataFrame
translate(df::DataFrame, table::AbstractString, columns::Vector{Symbol}) -> DataFrame

Return a new DataFrame with codes replaced by labels.

Non-mutating version of translate!.

Arguments

  • df::DataFrame: Source DataFrame
  • table::AbstractString: Table name (for looking up codebook)
  • column::Symbol or columns::Vector{Symbol}: Column(s) to translate

Returns

  • DataFrame: New DataFrame with translated column(s)

Examples

demo = NHANES.download("DEMO_J"; translate=false)
demo_labeled = NHANES.translate(demo, "DEMO_J", :RIAGENDR)
demo_labeled = NHANES.translate(demo, "DEMO_J", [:RIAGENDR, :RIDRETH1])
source
NHANES.variables — Method
variables(table::AbstractString; force::Bool=false) -> DataFrame

List variables in an NHANES data table.

Arguments

  • table::AbstractString: Table name with suffix (e.g., "DEMO_J")
  • force::Bool=false: Force refresh from CDC (ignore cache)

Returns

  • DataFrame: Variables with columns:
    • name: Variable name
    • label: Variable description/label

Examples

# List variables in 2017-2018 Demographics
NHANES.variables("DEMO_J")

See Also

source