readmit: Tools for Working with Hospital Readmissions Data

Description

Contains tools for working with and analyzing hospital readmissions data. The package provides utilities for components of the Hospital Readmissions Reduction Program (HRRP), including program timeline functions, Hospital-Specific Report (HSR) helpers, and general importing tools for the Provider Data Catalog (PDC).

Author(s)

Maintainer: Alex Zajichek alex@centralstatz.com [copyright holder]

See Also

Useful links:

• https://centralstatz.github.io/readmit/

• https://github.com/centralstatz/readmit

• Report bugs at https://github.com/centralstatz/readmit/issues

Find relevant dates from the Hospital Readmissions Reduction Program (HRRP)

Description

Identifies key dates (see hrrp_keydates) from the Hospital Readmissions Reduction Program (HRRP) that are associated with an input reference date, such as performance and payment periods.

Usage

hrrp_get_dates(ref, period = c("payment", "performance"), discharge = TRUE)

Arguments

Value

A tibble::tibble

See Also

hrrp_keydates

Examples

my_date <- as.Date("2022-01-01")

# What are the payment periods for this discharge?
hrrp_get_dates(my_date, period = "payment", discharge = TRUE)

# What performance periods is this discharge included in?
hrrp_get_dates(my_date, period = "performance", discharge = TRUE)

# What is the payment period overlapping this date?
hrrp_get_dates(my_date, period = "payment", discharge = FALSE)

# What is the performance period whose penalty period overlaps this date?
hrrp_get_dates(my_date, period = "performance", discharge = FALSE)

# What is the performance period for current penalty enforcement?
hrrp_get_dates(Sys.Date(), period = "performance", discharge = FALSE)

Key dates from the Hospital Readmissions Reduction Program (HRRP)

Description

A collection of datasets giving important dates involved in the Hospital Readmissions Reduction Program (HRRP), including performance periods, payment periods, review and correction periods, claims snapshot dates, and cohort inclusion status for program years since 2019. The data is manually abstracted from QualityNet and was most recently updated on 11/21/2025.

All tables contain the ProgramYear, which is the HRRP program (or federal fiscal year) in question. Tables with date ranges contain a StartDate and EndDate contain the beginning and end dates of the respective interval. Other tables contain individual dates or indicators for cohort inclusion (see descriptions).

Usage

hrrp_keydates

hrrp_performance_periods

hrrp_payment_periods

hrrp_review_periods

hrrp_snapshot_dates

hrrp_cohort_inclusion

Format

hrrp_performance_periods

Start and end dates for discharges evaluated for readmissions. Note some program years have multiple performance intervals and are represented on separate rows of this table.

hrrp_payment_periods

Start and end dates for when payment penalties are applied by CMS to hospital reimbursement.

hrrp_review_periods

Start and end dates for the review and correction period where hospitals could review discharge-level data and downstream calculations of penalty amounts.

hrrp_snapshot_dates

The as of date for when claims data were extracted by CMS for evaluation in the program. Note some discrepancies exist in CMS documentation for these dates (e.g., FY2026) when comparing anticipated versus actual snapshot date. The latter was used in this case.

hrrp_cohort_inclusion

Indicators of whether each cohort was included in the program for the given year. 1 = included, 0 = excluded.

AMI

Acute Myocardial Infarction

COPD

Chronic Obstructive Pulmonary Disease

HF

Heart Failure

PN

Pneumonia

CABG

Coronary Artery Bypass Graft

HK

Total Hip/Knee Replacement

hrrp_keydates

A combined table that joins all of the above individual tables into a single common table with altered column names.

An object of class tbl_df (inherits from tbl, data.frame) with 11 rows and 3 columns.

An object of class tbl_df (inherits from tbl, data.frame) with 9 rows and 3 columns.

An object of class tbl_df (inherits from tbl, data.frame) with 8 rows and 3 columns.

An object of class tbl_df (inherits from tbl, data.frame) with 9 rows and 2 columns.

An object of class tbl_df (inherits from tbl, data.frame) with 9 rows and 7 columns.

Source

https://qualitynet.cms.gov/inpatient/hrrp/resources#tab1

Extract risk model coefficients from a Hospital-Specific Report (HSR)

Description

Parses out the regression coefficients from the logistic regression model used by CMS to estimate discharge-level readmission risk, including the hospital-level and hospital average intercept terms.

Note: CMS changed the format of Hospital-Specific Reports (HSRs) for FY2026 (see here). The current HSR functions support formats through FY2025.

Usage

hsr_coefficients(file, cohort)

Arguments

Value

A tibble::tibble() containing the columns:

• Factor: The model term name (as listed in the file)

• Value: The model coefficient value (on the linear predictor scale)

Examples

# Access a report
my_report <- hsr_mock_reports("FY2025_HRRP_MockHSR.xlsx")

# Show coefficients for heart failure model
hsr_coefficients(my_report, "HF")

Extract cohort summary information from a Hospital-Specific Report (HSR)

Description

Parses the Table 2 cohort summary from the HSR, including (but not limited to) the discharge/readmission volumes, predicted/expected readmission rates, peer group medians, and DRG ratios.

Note: CMS changed the format of Hospital-Specific Reports (HSRs) for FY2026 (see here). The current HSR functions support formats through FY2025.

Usage

hsr_cohort_summary(file)

Arguments

Value

A tibble::tibble() containing the full Table 2 parsed from the report.

Examples

# Access a report
my_report <- hsr_mock_reports("FY2025_HRRP_MockHSR.xlsx")

# Extract the cohort summary as a dataset
hsr_cohort_summary(my_report)

Extract discharge-level data from a Hospital-Specific Report (HSR)

Description

Parses out the discharge-level data for a specific program cohort that contributed to penalty program in the reporting fiscal year (FY).

Note: CMS changed the format of Hospital-Specific Reports (HSRs) for FY2026 (see here). The current HSR functions support formats through FY2025.

Usage

hsr_discharges(
  file,
  cohort,
  discharge_phi = TRUE,
  risk_factors = FALSE,
  eligible_only = FALSE
)

Arguments

Details

The first set of columns in the discharge level data (typically through column R) contain the protected health information (PHI) associated with the discharges, such as medical record identifiers, admission/discharge/readmission dates, index diagnoses, etc. which can be used to identify the specific patients contributing (and not contributing) to the CMS penalty calculation for the cohort.

The risk factors contain the discharge-level clinical information used for individual risk adjustment by CMS to estimate individual level readmission rates. These can be useful to explore to understand risk factor distributions and prevalence, especially in combination with hsr_coefficients() which indicates the risk factors most heavily-weighted in the readmission risk calculation.

The HSR contains discharges that were not necessarily included/eligible to be counted in the Hospital Readmissions Reduction Program (HRRP). Setting eligible_only = TRUE will filter the returned result to only those that are eligible, and thus should match the denominator displayed in hsr_cohort_summary().

Value

A tibble::tibble()

Examples

# Access a report
my_report <- hsr_mock_reports("FY2025_HRRP_MockHSR.xlsx")

# All discharges
hsr_discharges(my_report, "HF")


# Discharges eligible for HRRP
hsr_discharges(my_report, "HF", eligible_only = TRUE)


# Only show risk factors for eligible discharges
hsr_discharges(
   file = my_report,
   cohort = "HF",
   discharge_phi = FALSE,
   risk_factors = TRUE,
   eligible_only = TRUE
)

# Row count matches denominator for HF
hsr_cohort_summary(my_report)

Extract dually-eligible discharges from a Hospital-Specific Report (HSR)

Description

Parses the discharge-level records from the HSR of patients who were dually-eligible for Medicare and Medicaid benefits (see details).

Note: CMS changed the format of Hospital-Specific Reports (HSRs) for FY2026 (see here). The current HSR functions support formats through FY2025.

Usage

hsr_dual_stays(file)

Arguments

Details

In the Hospital Readmissions Reduction Program (HRRP), hospitals' readmission rates are compared against a peer group of "like" hospitals, which determines whether or not they will get penalized financially.

The peer group allocation done by CMS is determined by creating hospital groupings based on the share of Medicare beneficiaries who were also eligible for Medicaid benefits, a marker of socioeconomic status in the hospital population. hsr_dual_stays() extracts the list of discharges accounting for the numerator of this ratio.

Value

A tibble::tibble()

Examples

# Access a report
my_report <- hsr_mock_reports("FY2025_HRRP_MockHSR.xlsx")

# Extract dually-eligible stays as a dataset
hsr_dual_stays(my_report)

Retrieve file location of mock Hospital-Specific Reports (HSR)

Description

Provides the location of mock HSRs downloaded from QualityNet that come with the package that users can import. These files are a representation of what a hospital's real report looks like when received from CMS. They contain mock data for sensitive fields (discharge level data, etc.), but real data for national level results (e.g., model coefficients). Thus, it gives user ability to practice/explore package functions and translate them to their own hospital reports. Files include fiscal years (FY) 2019-2025 and were downloaded on 11/8/2025 from https://qualitynet.cms.gov/inpatient/hrrp/reports. File names were changed for better identifiability.

Note: CMS changed the format of Hospital-Specific Reports (HSRs) for FY2026 (see here). The current HSR functions support formats through FY2025.

Usage

hsr_mock_reports(path = NULL)

Arguments

Details

This function was adapted from readxl::readxl_example().

Value

A character string or vector of strings

Examples

# Show all available mock reports
hsr_mock_reports()

# Show path to a single report
hsr_mock_reports("FY2025_HRRP_MockHSR.xlsx")

# Use mock report for testing package functions
hsr_payment_summary(hsr_mock_reports("FY2025_HRRP_MockHSR.xlsx"))

Extract payment summary information from a Hospital-Specific Report (HSR)

Description

Parses the Table 1 payment summary from the HSR, including (but not limited to) the payment penalty, peer group the hospital was compared against, and dual proportion that determines peer group assignment.

Note: CMS changed the format of Hospital-Specific Reports (HSRs) for FY2026 (see here). The current HSR functions support formats through FY2025.

Usage

hsr_payment_summary(file)

hsr_count_dual_stays(file)

hsr_count_total_stays(file)

hsr_dual_proportion(file)

hsr_peer_group(file)

hsr_neutrality_modifier(file)

hsr_payment_adjustment_factor(file)

hsr_payment_penalty(file)

Arguments

Value

• hsr_payment_summary() returns a tibble::tibble() containing the full Table 1 parsed from the report.

• Additional convenience functions extract specific columns from this table, and always return a numeric value.

Examples

# Access a report
my_report <- hsr_mock_reports("FY2025_HRRP_MockHSR.xlsx")

# Full payment summary table
payment_summary <- hsr_payment_summary(my_report)
payment_summary


# Extract individual components (from file)
hsr_payment_penalty(my_report)

# Or existing extract
hsr_payment_penalty(payment_summary)

Compute discharge-level readmission risks in a Hospital-Specific Report (HSR)

Description

Computes the predicted and expected readmission risks for each eligible discharge in the specified cohort.

Note: CMS changed the format of Hospital-Specific Reports (HSRs) for FY2026 (see here). The current HSR functions support formats through FY2025.

Usage

hsr_readmission_risks(file, cohort)

Arguments

Details

The readmission measure is what CMS uses to grade performance in the Hospital Readmissions Reduction Program (HRRP).

Individual discharges are assigned an adjusted readmission risk (based on clinical history), which then get aggregated into a hospital-level score and compared to peer groups for penalty determination. Specifically, a random-intercept logistic regression model is built for each cohort (see methodology) which serves as the basis for two (2) readmission risks assigned to each discharge:

• Predicted: Adjusted for patient-specific clinical factors plus the hospital-specific effect (random intercept term)

• Expected: Adjusted for patient-specific clinical factors plus the hospital-average effect

These quantities are then aggregated across all discharges and their ratio is taken to form the Excess Readmission Ratio (ERR), which is then used as the cohort-specific comparison metric. Thus, it is a comparative measure of how likely patients are to be readmitted at your hospital versus the average hospital, given your hospital's clinical characteristics.

Value

A tibble::tibble() containing the following columns:

• ⁠ID Number⁠: The unique discharge identifier (see hsr_discharges())

• Predicted: The predicted readmission risk for the discharge

• Expected: The expected readmission risk for the discharge

Examples

# Access a report
my_report <- hsr_mock_reports("FY2025_HRRP_MockHSR.xlsx")

# Compute readmission risks for HF discharges
hf_risks <- hsr_readmission_risks(my_report, "HF")
hf_risks

# Compute the ERR from scratch
hf_risks |>
 dplyr::summarize(
   Discharges = dplyr::n(),
   Predicted = mean(Predicted),
   Expected = mean(Expected),
   ERR = Predicted / Expected
 )


# Check that this matches the report table
hsr_cohort_summary(my_report) |>
 dplyr::select(
  dplyr::matches(
     paste0(
       "^Measure|",
       "^Number of Eligible Discharges|",
       "^Predicted|",
       "^Expected|",
       "^Excess"
     )
   )
 )

Import datasets from the Provider Data Catalog (PDC)

Description

Explore and import datasets directly from the CMS Provider Data Catalog (PDC).

• pdc_topics(): Retrieves the list of topics (subcategories) that data is available for

• pdc_datasets(): Retrieves identifiers, names, descriptions, and other metadata associated with the datasets in the (optionally specified) topics

• pdc_read(): Imports a full dataset for the given identifier (datasetid). These are found in pdc_datasets().

Usage

pdc_read(datasetid, ...)

pdc_datasets(topics = NULL)

pdc_topics()

Arguments

Value

A character vector listing available data topics, or a tibble::tibble() containing the requested data/metadata.

Examples

# 1. See list of available data topics
pdc_topics()


# 2. See list of datasets available for a topic
hospital_data <- pdc_datasets("Hospitals")
hospital_data

# Find a dataset you want
hospital_data |>
   dplyr::filter(
      stringr::str_detect(
         title,
         pattern = "(?i)readmission"
      )
   )


# 3. Use that data set ID to import
pdc_read("9n3s-kdb3")