Skip to content

README.md

Latest commit

 

History

History
102 lines (61 loc) · 5.5 KB

README.md

File metadata and controls

102 lines (61 loc) · 5.5 KB
Raw

HCUPkit

Tools for Working with HCUP Nationwide Inpatient Sample (NIS) Data in R.

HCUPkit provides an end-to-end pipeline for NIS research: load data, flag conditions, create survey objects, calculate rates, test trends, and produce publication-ready tables. It embeds methodological guardrails that prevent the most common errors identified in NIS literature (Khera et al., JAMA 2017).

Installation

# Install from GitHub
remotes::install_github("cgbielick/HCUPkit")

Requires R >= 4.1.0 and NIS data files purchased from HCUP.

Key Features

Data Loading -- Year-specific NIS loaders (2011-2022) with automatic handling of the 2012 redesign, 2015 ICD-9/ICD-10 transition, and 2019-2020 data revisions.

Condition Flagging -- flag_nis() identifies hospitalizations matching ICD-9/ICD-10 codes, CCS/CCSR categories, or a curated library of 31 conditions (HIV, opportunistic infections, malignancies, neurologic/hematologic complications).

Elixhauser Comorbidity Index -- 30 POA-independent measures with Van Walraven weighted scoring and 7 comorbidity group aggregates. Appropriate for NIS data (which does not contain discharge-level POA indicators).

Survey Design -- Correct NIS stratification (NIS_STRATUM, HOSP_NIS, DISCWT) with trend weight handling for analyses crossing the 2012 redesign boundary.

Rate Calculations -- Population-based rates using CDC Atlas Plus denominators with confidence intervals via SE propagation.

Trend Analysis -- Survey-weighted quasi-Poisson regression for linear trends, annual percent change, and between-group trend comparisons.

Publication Tables -- DUA-compliant Table 1 (via gtsummary), rate tables, trend tables, and count tables with automatic cell suppression.

Cost Conversion -- TOTCHG to estimated costs via HCUP cost-to-charge ratio (CCR) files. CCR files are HCUP-restricted supplemental files and are not distributed with this package; point ccr_dir at the CCR files that come with your HCUP data purchase.

Methodological Guardrails

HCUPkit includes 8 guardrails addressing common NIS analytical errors. Four of the seven violation categories documented in Khera et al. (JAMA 2017) are enforced or detected programmatically; the remaining three (discharge-vs-patient interpretation, hospital-level inference, nonspecific secondary diagnosis codes) are addressed through documentation and startup messaging rather than hard enforcement.

Hard enforcement (errors that block execution):

  1. State-level analysis prevention -- Error when attempting sub-regional stratification (NIS design does not support state-level inference)
  2. Survey design enforcement -- Required strata, clusters, and weights; errors on constant/uniform weights
  3. 2012 redesign handling -- Automatic trend weight detection; errors when crossing the redesign boundary without trend weights
  4. ICD-9/ICD-10 transition -- Automatic coding system detection per year, including the 2015 Q1-Q3/Q4 split

Warnings and detection:

  1. DUA cell suppression -- Cells with n <= 10 flagged with complementary suppression
  2. Subpopulation analysis protection -- Warning when data appears pre-filtered before survey design creation
  3. Charge vs. cost distinction -- Warning when charges are used without cost-to-charge ratio conversion
  4. Discharge-not-patient messaging -- Startup reminder that NIS records are hospitalizations, not unique patients

Getting Started

library(HCUPkit)

# See all available conditions in the code library
list_conditions()

# Get ICD codes for a condition
get_condition_codes("HIV", version = "both")

# Calculate Elixhauser comorbidities
data_elix <- calculate_elixhauser(your_data)

# Create survey design
survey <- create_survey_object(your_data)

# Weighted summaries with DUA compliance
summaries <- calculate_survey_summaries(survey, conditions = c("HIV", "PJP"))

See the vignettes for complete workflows:

  • vignette("getting-started") -- From raw NIS files to your first weighted estimate
  • vignette("rate-calculation-workflow") -- Full rate calculation pipeline
  • vignette("survey-analysis-workflow") -- Survey design and analysis patterns
  • vignette("trend-analysis-workflow") -- Trend analysis and visualization

Citation

If you use HCUPkit in your research, please cite:

Bielick C (2026). HCUPkit: Tools for Working with HCUP Nationwide Inpatient Sample Data in R. R package version 1.1.0. https://github.com/cgbielick/HCUPkit

Note on Package Name

This package was formerly developed under the name HCUPtools. It was renamed to HCUPkit to avoid confusion with an unrelated CRAN package of that name (which downloads CCSR reference files and accesses summary trend tables). HCUPkit is different in scope: it provides a complete NIS analysis pipeline with methodological guardrails.

HCUP Data Use Agreement

Users must comply with the HCUP Data Use Agreement. Key requirements include suppression of cells with n <= 10 unweighted observations and no publishing of state or hospital identifiers. HCUPkit enforces cell suppression automatically. See the full DUA from AHRQ for complete details.

No HCUP microdata or restricted supplemental files (including cost-to-charge ratio files) are distributed with this package. All bundled reference material comes from freely available AHRQ/HCUP and CDC public resources, and all test fixtures are synthetic (seeded random generation; see data-raw/create_nis_synthetic.R).

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT