This repository contains Version 2 of the NHANES exposome–phenome-wide association study (PheEWAS) analysis pipeline.
The workflow is organized as a seven-step pipeline spanning data preparation, quality control, discovery and replication analyses, formal effect measure modification testing by race/ethnicity, and final visualization.
PheEWAS_paper_v2/
├── step1/
├── step2/
├── step3/
├── step4/
├── step5/
├── step6/
├── step7/
├── .gitignore
└── README.md
Each directory corresponds to one stage of the analysis pipeline.
Step 1 establishes the initial NHANES analysis dataset and reconciles the study variable set.
Major tasks include:
- Defining the analysis variables used in the study
- Reconciling the intended variable list with the available NHANES variables
- Applying initial exclusions and QC rules
- Preparing survey design variables and weights
- Creating discovery and replication survey-design datasets
- Documenting variable availability and reconciliation decisions
Key files include the reconciled variable table, analysis variable metadata, survey design files, and the Step 1 QC notebook.
Step 2 prepares the analysis cohorts and classifies variables for downstream analyses.
Major tasks include:
- Auditing the reconciled variable set
- Categorizing variables as continuous, binary, or categorical
- Preparing adult analysis cohorts
- Separating discovery and replication datasets
- Applying covariate availability requirements
- Generating metadata describing the selected analysis variables
Large intermediate serialized datasets generated during this step are not stored in the public repository.
Step 3 performs phenotype-specific quality control and transformation.
Major tasks include:
- Evaluating phenotype distributions
- Identifying outliers
- Calculating percent-zero metrics
- Evaluating skewness
- Determining whether phenotype transformation is needed
- Creating transformation plans
- Applying consistent transformation rules across discovery and replication
- Comparing pre- and post-transformation distributions
Diagnostic tables and phenotype distribution plots are retained in the repository.
Step 4 performs exposure-specific QC and prepares exposures for PheEWAS modeling.
Major tasks include:
- Classifying exposure analysis types
- Applying QC criteria to candidate exposures
- Identifying continuous-exposure outliers
- Evaluating exposure skewness
- Creating transformation plans
- Applying cross-cohort transformation rules
- Creating exposure adjustment mappings
- Assigning NHANES survey weight variables
- Preparing urinary exposure adjustment variables where applicable
Urinary exposures are modeled with the appropriate urinary adjustment covariate, including creatinine adjustment where required.
Step 5 performs the primary exposome–phenome association analyses.
The general model evaluates associations between each eligible exposure and phenotype while accounting for study covariates and the NHANES survey design.
The workflow includes:
- Running survey-weighted PheEWAS models in the discovery dataset
- Identifying discovery-selected exposure–phenotype hypotheses
- Determining replication eligibility
- Testing selected associations in the replication dataset
- Combining discovery and replication results
- Applying multiple-testing correction
- Generating FDR- and Bonferroni-significant result tables
Replication testing is restricted to hypotheses selected during the discovery phase rather than re-testing every possible exposure–phenotype pair.
Output tables include:
- Discovery PheEWAS results
- Replication PheEWAS results
- Combined discovery/replication results
- FDR-significant replicated associations
- Bonferroni-significant replicated associations
Step 6 formally evaluates whether exposure–phenotype associations differ across race/ethnicity groups.
The primary analysis groups are:
- Non-Hispanic White (NHW)
- Non-Hispanic Black (NHB)
- Mexican American (MA)
Formal effect measure modification is evaluated using an interaction model of the general form:
phenotype ~ exposure
+ race_ethnicity
+ exposure × race_ethnicity
+ age
+ sex
+ BMI
+ SES
+ survey_year
+ exposure-specific adjustment terms
Survey-weighted models are used.
A joint Wald test is used to evaluate the overall exposure × race/ethnicity interaction.
When evidence of interaction is present, group-specific exposure effects and pairwise contrasts are used to interpret the source and direction of effect heterogeneity.
Outputs include:
- Formal EMM results
- Joint interaction test results
- Group-specific exposure effects
- Pairwise race/ethnicity contrasts
- FDR-significant EMM results
- Bonferroni-significant EMM results
This step distinguishes descriptive stratified associations from formal statistical evidence of effect measure modification.
Step 7 generates the final figures and graphical summaries of the study results.
Visualizations include:
- Discovery volcano plots
- Replication volcano plots
- Combined and race/ethnicity-specific volcano panels
- Ranked exposure–phenotype association networks
- Exposure connection rankings
- Phenotype connection rankings
- Top connected exposure plots
- Top connected phenotype plots
- Sunplots for highly connected exposures and phenotypes
- Formal EMM group-specific effect plots
- Formal EMM pairwise contrast plots
The plotting workflow uses reconciled variable descriptions so that figures display interpretable exposure and phenotype names rather than only NHANES variable codes.
The study follows a discovery–replication framework.
Associations are first evaluated in the discovery dataset. Exposure–phenotype pairs meeting the prespecified discovery criteria are then carried forward for replication testing.
Multiplicity correction in the replication stage is therefore applied to the discovery-selected hypotheses rather than to the full universe of possible exposure–phenotype combinations.
Associations that reproduce across discovery and replication are summarized using both false discovery rate and Bonferroni correction thresholds.
Analyses account for the complex NHANES survey design.
Models incorporate the appropriate NHANES sampling weights and relevant analysis covariates. Survey-weight selection is determined by the NHANES variables and cycles included in each analysis.
Exposure-specific adjustment variables are incorporated where required.
This repository contains analysis code, notebooks, metadata, diagnostic summaries, aggregate results, and figures required to document the workflow.
Large intermediate objects and selected analysis datasets are excluded from version control using .gitignore.
Examples of excluded files include:
*.pkl
large intermediate analysis datasets
temporary files
cluster logs
raw or restricted datasets
Participant-level or restricted-access data are not intended to be distributed through this repository.
The pipeline is designed to be run sequentially:
Step 1
↓
Step 2
↓
Step 3
↓
Step 4
↓
Step 5
↓
Step 6
↓
Step 7
Outputs generated by earlier steps are used as inputs to later stages of the workflow.
For best reproducibility, notebooks should be executed in numerical order.
This repository contains the updated seven-step NHANES PheEWAS pipeline, including:
- Expanded variable reconciliation and QC
- Formal discovery–replication tracking
- Updated exposure and phenotype preprocessing
- Formal race/ethnicity effect measure modification testing
- Joint Wald interaction tests
- Group-specific effects and pairwise contrasts
- Updated visualization and network analyses
The original analysis pipeline is archived here:
Citation information will be added following manuscript finalization.