Skip to contents

Read CCSR Mapping Files from Disk

Source: R/read_ccsr.R
read_ccsr.Rd

Reads previously downloaded CCSR mapping files from disk. If no file path is provided, automatically finds and reads cached files from download_ccsr().

Usage

read_ccsr(
  file_path = NULL,
  type = NULL,
  version = "latest",
  clean_names = TRUE,
  as_data_table = NULL,
  name = NULL
)

Arguments

file_path

Optional character string, path to a CCSR mapping file. Can be:

  • A ZIP file path (will be extracted and read)

  • A CSV/Excel file path (will be read directly)

  • A directory path containing extracted CCSR files If NULL (default), automatically searches the cache directory for files downloaded via download_ccsr().

type

Character string specifying the type of CCSR file. Must be one of: "diagnosis" (or "dx") for ICD-10-CM diagnosis codes, or "procedure" (or "pr") for ICD-10-PCS procedure codes. If NULL and file_path is NULL, defaults to "diagnosis". If file_path is provided, the function will attempt to infer the type from the file name or contents.

version

Character string specifying the CCSR version to read from cache. Use "latest" (default) to read the most recent version, or specify a version like "v2026.1", "v2025.1", etc. Only used when file_path is NULL.

clean_names

Logical. If TRUE (default), column names are cleaned to follow R naming conventions (snake_case).

as_data_table

Logical or NULL. If TRUE and the data.table package is available, returns a data.table object instead of a tibble. If FALSE, returns a tibble. If NULL (default), prompts the user interactively to choose (only in interactive sessions). In non-interactive sessions, defaults to FALSE. Note: tibbles are already data frames and work with all standard R data frame operations.

name

Optional character string, suggested variable name for the returned data. This is only used for display/messaging purposes and does not automatically assign the data to a variable. You must still assign the result: my_data <- read_ccsr(). If NULL (default), a name is suggested based on the file type and version.

Value

A tibble (or data.table if as_data_table = TRUE) containing the CCSR mapping data. Tibbles are data frames and can be used with all standard R data frame operations, including dplyr, data.table, and base R functions.

Details

This function can read CCSR files in several formats:

  • ZIP files downloaded from HCUP (will extract and read the CSV/Excel file)

  • CSV files (extracted from ZIP or saved separately)

  • Excel files (if readxl package is available)

  • Directories containing extracted files

  • Cached files from download_ccsr() (automatic if file_path is NULL)

The function automatically detects the file format and handles encoding issues, preserving leading zeros in ICD-10 codes.

When file_path is NULL, the function automatically searches the cache directory (tempdir()/HCUPtools_cache/) for files matching the specified type and version. This makes it easy to read previously downloaded files without needing to know the exact file path.

Note

To use the data, assign it to a variable: my_data <- read_ccsr(). The name parameter is only for display purposes and does not automatically assign the data.

Examples

# \donttest{
# Populate cache, then read (requires network)
invisible(download_ccsr("diagnosis"))
#> Using cached file: /tmp/RtmpHPIK2k/HCUPtools_cache/DXCCSR-v2026-1.zip
#> Reading mapping file: DXCCSR_v2026-1.csv
dx_map <- read_ccsr(as_data_table = FALSE)
#> 
#> === Available Cached CCSR Files ===
#> 
#>  1. DXCCSR-v2026-1.zip (Diagnosis, v2026-1)
#>  2. PRCCSR_v2025-1.zip (Procedure, v2025-1)
#> 
invisible(download_ccsr("procedure"))
#> Cached files found (v2025.1) but latest is v2026.1. Downloading latest version...
#> Downloading from: https://hcup-us.ahrq.gov/toolssoftware/ccsr/PRCCSR_v2026-1.zip
#> Download complete: /tmp/RtmpHPIK2k/HCUPtools_cache/PRCCSR_v2026-1.zip
#> Reading mapping file: PRCCSR_v2026-1.csv
pr_map <- read_ccsr(type = "procedure", as_data_table = FALSE)
#> 
#> === Available Cached CCSR Files ===
#> 
#>  1. PRCCSR_v2025-1.zip (Procedure, v2025-1)
#>  2. PRCCSR_v2026-1.zip (Procedure, v2026-1)
#> 

# From a local file on your machine (uncomment and set the path):
# dx_map <- read_ccsr("/path/to/DXCCSR-v2026-1.zip", as_data_table = FALSE)
# dx_map <- read_ccsr("/path/to/DXCCSR_v2026_1.csv", as_data_table = FALSE)
# dx_map <- read_ccsr("/path/to/extracted_ccsr_files/", as_data_table = FALSE)

head(dx_map)
#> # A tibble: 6 × 19
#>   icd10cm_code icd10cm_code_description                   default_ccsr_categor…¹
#>   <chr>        <chr>                                      <chr>                 
#> 1 A000         Cholera due to Vibrio cholerae 01, biovar… DIG001                
#> 2 A001         Cholera due to Vibrio cholerae 01, biovar… DIG001                
#> 3 A009         Cholera, unspecified                       DIG001                
#> 4 A0100        Typhoid fever, unspecified                 DIG001                
#> 5 A0101        Typhoid meningitis                         NVS001                
#> 6 A0102        Typhoid fever with heart involvement       INF003                
#> # ℹ abbreviated name: ¹​default_ccsr_category_ip
#> # ℹ 16 more variables: default_ccsr_category_description_ip <chr>,
#> #   default_ccsr_category_op <chr>, default_ccsr_category_description_op <chr>,
#> #   ccsr_category_1 <chr>, ccsr_category_1_description <chr>,
#> #   ccsr_category_2 <chr>, ccsr_category_2_description <chr>,
#> #   ccsr_category_3 <chr>, ccsr_category_3_description <chr>,
#> #   ccsr_category_4 <chr>, ccsr_category_4_description <chr>, …
nrow(dx_map)
#> [1] 75725
# }