---
title: "Available NHANES Datasets"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Available NHANES Datasets}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r}
#| label: setup
#| include: false

library(dplyr)
library(reactable)

knitr::opts_chunk$set(
  collapse = TRUE,
  eval = FALSE,
  comment = "#>"
)

config <- yaml::read_yaml(
  system.file("extdata", "datasets.yml", package = "nhanesdata")
)

catalog <- do.call(rbind, lapply(config$datasets, function(x) {
  data.frame(
    Dataset = toupper(x$name),
    Description = x$description,
    Category = tools::toTitleCase(x$category),
    stringsAsFactors = FALSE
  )
}))

catalog <- rbind(catalog, data.frame(
  Dataset = "MORTALITY",
  Description = "NHANES-Linked Mortality (NDI) - Follow-up Through 2019",
  Category = "Linkage",
  stringsAsFactors = FALSE
))
```

## Available Datasets

This package provides `r nrow(catalog)` NHANES datasets, automatically updated annually with data from 1999-2023 (excluding the 2019-2020 cycle).

### Quick Start
```r
library(nhanesdata)

# Load demographics data
demo <- read_nhanes('demo')

# Search for variables
term_search('blood pressure')
```

> **Easter Egg: Mortality Linkage Data**
>
> The package includes harmonized NHANES-linked mortality data accessible via `read_nhanes("mortality")`. This dataset links NHANES participants to death certificate records from the National Death Index (NDI), enabling survival analysis and mortality risk studies.
>
> **Key features:**  
> * Follow-up through December 31, 2019  
> * Cause-specific mortality (ICD-10 codes)  
> * Person-months of follow-up  
> * Vital status and mortality flags  
>
> **Important:** Mortality linkage requires understanding of survey weights, censoring, and survival analysis methods. Always consult the [NCHS data linkage documentation](https://www.cdc.gov/nchs/linked-data/mortality-files/?CDC_AAref_Val=https://www.cdc.gov/nchs/data-linkage/mortality-public.htm) and the [NHANES analytic guidelines](https://wwwn.cdc.gov/nchs/nhanes/analyticguidelines.aspx) before analyzing mortality outcomes.
>
> See the [Public-Use Linked Mortality Files](https://www.cdc.gov/nchs/linked-data/mortality-files/) for methodology and variable definitions.

### Categories

**Questionnaire/Interview Tables** - Self-reported data from participant interviews

**Examination Tables** - Physical measurements and laboratory results

```{r}
#| label: reactable-of-datasets
#| echo: false
#| eval: true

catalog |>
  arrange(Dataset) |>
  reactable::reactable(
    searchable = TRUE,
    columns = list(
      Dataset = reactable::colDef(width = 120),
      Category = reactable::colDef(width = 140),
      Description = reactable::colDef(minWidth = 300)
    )
  )
```

### Notes

- All datasets span multiple survey cycles (1999-2023)
- Each includes `year` and `seqn` columns for merging
- Data types are harmonized across cycles
- Variable names match CDC documentation

For detailed variable information, use `term_search()` or visit the [CDC NHANES website](https://wwwn.cdc.gov/nchs/nhanes/).

> **Warning:** CDC may change data periodically. The data was aggregated as
> best as possible to reconcile variable types that changed across cycles.
> **ALWAYS** reference the CDC documentation with
> `nhanesdata::get_url(dataset)`!
>
> See `get_url()` documentation.