nhisml

nhisml is a survey-aware machine learning toolkit for the National Health Interview Survey (NHIS) Adults public-use microdata. It provides a reproducible, end-to-end pipeline — from raw data download through model training, cross-year evaluation, and subgroup fairness analysis — designed for researchers in public health, epidemiology, and health services research.

Disclaimer: nhisml is an independent research project and not affiliated with, endorsed by, or officially connected to the National Health Interview Survey (NHIS), the U.S. Centers for Disease Control and Prevention (CDC), the National Center for Health Statistics (NCHS), or any other government agency.

Statement of Need

The NHIS Adults dataset is a rich, nationally representative survey with complex survey weights, multi-year structure, and domain-specific missing-data conventions. Researchers who want to apply machine learning to NHIS data must repeatedly solve the same data-engineering problems: downloading and caching raw files, harmonizing variable names across survey years, handling NHIS-specific missing codes (7/8/9/97/98/99), applying survey weights correctly in model fitting and evaluation, and computing fairness metrics across demographic subgroups. nhisml encodes these survey-specific conventions into reusable, well-tested software components, lowering the barrier to rigorous, reproducible ML research on NHIS data.

Features

• Survey-aware preprocessing — NHIS missing-code remapping, binary-coded (1/2 → 1/0) variables, rare-category bucketing, and stable missingness-flag columns
• Task-aware label generation — built-in definitions for self-rated health (SRH) and current cigarette smoking, with clean eligibility masking
• Survey-weighted metrics — AUC, PR-AUC, F1, Brier score, log-loss, and ECE, all computed with NHIS analytic weights (WTFA_A)
• Calibration — out-of-fold (OOF) probability calibration via isotonic regression with threshold optimization
• Cross-year evaluation — train on 2023, evaluate on 2024 in a single command
• Subgroup fairness analysis — built-in sex, age-band, and education-level recoding with per-subgroup metric deltas vs. overall
• Publication-ready outputs — structured run directories with manifests, OOF predictions, metrics JSON, and CSV subgroup tables
• Extensible — add new tasks, feature sets, or models by registering them in the appropriate module

Installation

pip install nhisml

To include visualization support:

pip install "nhisml[viz]"

For development and testing:

git clone https://github.com/soda-lmu/nhisml.git
cd nhisml
pip install -e ".[dev]"

Getting Started

Python API

The quickest way to get going is straight from within Python.

import nhisml
from sklearn.linear_model import LogisticRegression
from sklearn.pipeline import Pipeline

# Downloads, builds and caches the dataset
df = nhisml.load_core_year(2023)

# Task and feature set definitions. Not every featureset column is present
# in every survey year (e.g. some psychological-distress items were added
# in 2024), so restrict to columns actually available in this year's data.
task = nhisml.make_task("srh_binary")
featureset = nhisml.get_featureset("core", filter=df.columns)

# Labels, eligibility mask, and survey weights normalized to mean 1
y, eligible = task.make_labels(df)
df, y = df.loc[eligible].reset_index(drop=True), y[eligible]
weights = nhisml.normalize_weights(df["WTFA_A"])

# Build the preprocessing pipeline and fit a simple survey-weighted model.
preprocessor = nhisml.build_preprocessor(
    binary_cols=featureset.binary_12,
    ordinal_cols=featureset.ordinal,
    categorical_cols=featureset.categorical,
)
model = Pipeline([
  ("prep", preprocessor),
  ("clf", LogisticRegression(max_iter=1000))
])
model.fit(df, y, clf__sample_weight=weights)

proba = model.predict_proba(df)[:, 1]

print(
    f"Fit on {len(df):,} eligible rows; predicted probability range: "
    f"[{proba.min():.3f}, {proba.max():.3f}]"
)

For survey-weighted OOF threshold tuning, calibration, cross-year evaluation, and subgroup fairness metrics, use the lower-level utilities in nhisml.utils and nhisml.subgroup, or use the CLI below.

Command Line

# 1. Download and cache raw NHIS Adults public-use files from the CDC FTP server
nhisml fetch --year 2023 --year 2024

# 2. Extract and harmonize predictor and label columns into parquet file(s)
nhisml build-core --year 2023
nhisml build-core --year 2024

# 3. Train a baseline model: elastic-net logistic regression (default) with
# survey-weighted OOF threshold tuning
nhisml train --in data/core_2023.parquet --task srh_binary

# Random forest with probability calibration
nhisml train --in data/core_2023.parquet --task srh_binary --model rf --calibrate

# 4. Evaluate on held-out year data
nhisml evaluate --task srh_binary --latest --year 2024

# 5. Subgroup fairness analysis
nhisml subgroup --task srh_binary --latest --year 2024 --by sex age education

Supported Prediction Tasks

List all available tasks and describe them from the command line:

nhisml list-tasks
nhisml describe-task srh_binary

Available Feature Sets

The core feature set includes 69 NHIS Adults predictors spanning:

• Health conditions (hypertension, diabetes, cardiovascular disease, respiratory, etc.)
• Mental health (depression, anxiety, psychological distress indices)
• Healthcare access (insurance coverage, usual place of care, medication delays)
• Socioeconomic status (income-to-poverty ratio, education, employment)
• Demographics (region, urbanicity, marital status)

nhisml list-featuresets
nhisml describe-featureset core

Run Directory Structure

Each nhisml train call produces a timestamped run directory under runs/:

runs/
└── 20240115-143022_task=srh_binary_model=lasso_fs=core/
    ├── manifest.json          # full provenance record
    ├── model.joblib           # fitted sklearn Pipeline
    ├── thresholds.json        # OOF-tuned decision threshold
    ├── oof_predictions.parquet
    └── oof_metrics.json

After evaluation and subgroup analysis:

    ├── metrics_task=srh_binary.json
    ├── predictions_task=srh_binary.parquet
    └── subgroups_task=srh_binary.csv

Running the Tests

pip install -e ".[dev]"
pytest tests/ -v

The test suite covers task logic, preprocessing correctness, metric computation, run-resolution utilities, subgroup recoding, fetch caching behavior, and the CLI entry points. Tests do not require downloading NHIS data; synthetic data is generated within each test where needed.

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for guidelines on filing issues, submitting pull requests, adding new prediction tasks, and extending the feature set registry.

Citation

@software{nhisml,
  title   = {{nhisml: A survey-aware machine learning toolkit for NHIS Adults data}},
  author  = {Lugu Reign, Nicholas and Lamoreaux, Catherine and Simson, Jan and Kern, Christoph and Kreuter, Frauke},
  year    = {2026},
  url     = {https://github.com/soda-lmu/nhisml}
}

License

MIT License. See LICENSE for details.