Metadata-Version: 2.4
Name: nhisml
Version: 0.6.1
Summary: Survey-aware ML starter kit for NHIS Adults (2023/2024): fetch, build core data, train baselines, export reproducible outputs.
Author: Catherine Lamoreaux, Jan Simson, Christoph Kern, Frauke Kreuter
Author-email: Nicholas Lugu Reign <lreign1@umd.edu>
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: pyarrow>=14
Requires-Dist: scikit-learn>=1.4
Requires-Dist: joblib>=1.3
Requires-Dist: requests>=2.31
Requires-Dist: tqdm>=4.66
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff<0.16,>=0.6; extra == "dev"
Requires-Dist: zensical>=0.0.11; python_version >= "3.10" and extra == "dev"
Requires-Dist: mkdocstrings-python>=1.16; python_version >= "3.10" and extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == "viz"
Provides-Extra: duckdb
Requires-Dist: duckdb>=1.0; extra == "duckdb"
Dynamic: license-file

# nhisml

<img src="https://raw.githubusercontent.com/soda-lmu/nhisml/main/docs/assets/logo.svg" alt="nhisml logo" width="200" align="right" />

[![Tests](https://github.com/soda-lmu/nhisml/actions/workflows/tests.yml/badge.svg)](https://github.com/soda-lmu/nhisml/actions/workflows/tests.yml)
[![PyPI version](https://badge.fury.io/py/nhisml.svg)](https://badge.fury.io/py/nhisml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)

**nhisml** is a survey-aware machine learning toolkit for the [National Health Interview Survey (NHIS)](https://www.cdc.gov/nchs/nhis/index.html) 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

```bash
pip install nhisml
```

To include visualization support:

```bash
pip install "nhisml[viz]"
```

For development and testing:

```bash
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.

```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

```bash
# 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

| Task name         | Target variable    | Positive class             |
|-------------------|--------------------|----------------------------|
| `srh_binary`      | PHSTAT_A           | Fair or Poor self-rated health (values 4-5) |
| `smoking_current` | SMKCIGST_A / SMKNOW_A | Current every-day or some-day smoker |

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

```bash
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)

```bash
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

```bash
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](CONTRIBUTING.md) for guidelines on filing issues, submitting pull requests, adding new prediction tasks, and extending the feature set registry.

## Citation

```bibtex
@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](LICENSE) for details.
