Learn R Programming

icd

Fast comorbidities from ICD-9 and ICD-10 codes, decoding, manipulation and validation

Introduction

Calculate comorbidities, medical risk scores, and work very quickly and precisely with ICD-9 and ICD-10 codes. This package enables a work flow from raw tables of ICD codes in hospital databases to comorbidities. ICD-9 and ICD-10 comorbidity mappings from Quan (Deyo and Elixhauser versions), Elixhauser and AHRQ included. Common ambiguities and code formats are handled. Comorbidity computation includes Hierarchical Condition Codes, and an implementation of AHRQ Clinical Classifications. Risk scores include those of Charlson and van Walraven. US Clinical Modification, Word Health Organization, Belgian and French ICD-10 codes are supported, most of which are downloaded on demand.

icd is used by many researchers around the world who work in public health, epidemiology, clinical research, nutrition, journalism, health administration, insurance, and more. I’m grateful for contact from people in these fields for their feedback and code contributions, and I’m pleased to say that icd has been used in works like the Pulitzer finalist work on maternal death by ProPublica.

Features

  • find comorbidities of patients based on ICD-9 or ICD-10 codes, e.g. Cancer, Heart Disease
    • several standard mappings of ICD codes to comorbidities are included (Quan, Deyo, Elixhauser, AHRQ, PCCC)
    • very fast assignment of ICD codes to comorbidities (using novel matrix multiplication algorithm and C++ internally – see ‘efficiency’ vignette for details)
  • use your existing wide or long data format, icd can guess which columns are ICD-9 or ICD-10 codes.
  • explain and summarize groups of ICD codes in natural language, using ICD editions from the WHO, USA, France and Belgium. Many different annual editions of these data are available, and these may be downloaded automatically when used, or in bulk with download_all_icd_data().
  • Charlson and Van Walraven score calculations
  • Hierarchical Condition Codes (HCC) from CMS
  • Clinical Classifications Software (CCS) comorbidities from AHRQ
  • Pediatric Complex Chronic Condition comorbidities
  • AHRQ ICD-10 procedure code classification
  • correct conversion between different representations of ICD codes, with and without a decimal points, leading and trailing characters (this is not trivial for ICD-9-CM). ICD-9 to ICD-10 cross-walk is not yet implemented
  • comprehensive test suite to increase confidence in accurate processing of ICD codes

Examples

See also the vignettes and examples embedded in the help for each function for more. Here’s a taste:

# install.packages("icd")
library(icd)

# Typical diagnostic code data, with many-to-many relationship
patient_data
#>   visit_id  icd9
#> 1     1000 40201
#> 2     1000  2258
#> 3     1000  7208
#> 4     1000 25001
#> 5     1001 34400
#> 6     1001  4011
#> 7     1002  4011
#> 8     1000  <NA>

# get comorbidities using Quan's application of Deyo's Charlson comorbidity groups
comorbid_charlson(patient_data)
#>         MI   CHF   PVD Stroke Dementia Pulmonary Rheumatic   PUD LiverMild
#> 1000 FALSE  TRUE FALSE  FALSE    FALSE     FALSE     FALSE FALSE     FALSE
#> 1001 FALSE FALSE FALSE  FALSE    FALSE     FALSE     FALSE FALSE     FALSE
#> 1002 FALSE FALSE FALSE  FALSE    FALSE     FALSE     FALSE FALSE     FALSE
#>         DM  DMcx Paralysis Renal Cancer LiverSevere  Mets   HIV
#> 1000  TRUE FALSE     FALSE FALSE  FALSE       FALSE FALSE FALSE
#> 1001 FALSE FALSE      TRUE FALSE  FALSE       FALSE FALSE FALSE
#> 1002 FALSE FALSE     FALSE FALSE  FALSE       FALSE FALSE FALSE

# or go straight to the Charlson scores:
charlson(patient_data)
#> 1000 1001 1002 
#>    2    2    0

# plot summary of Uranium Cancer Registry sample data using AHRQ comorbidities
plot_comorbid(uranium_pathology)

Comorbidities example: make “Table 1” summary data

A common requirement for medical research involving patients is determining new or existing comorbidities. This is often reported in Table 1 of research papers to demonstrate the similarity or differences of groups of patients. This package is focussed on fast and accurate generation of this comorbidity information from raw lists of ICD-9 and ICD-10 codes.

Here we are using the US National Hospital Discharge Survey 2010 data from the nhds package. For the sake of example, let us compare emergency to other admissions. A real table would have more patient features; this primarily demonstrates how to get ICD codes into your Table 1.

NHDS 2010 comorbidities to demonstrate Table One creation. Presented as counts (percentage prevalence in group).

nhds <- nhds::nhds2010
# get the comorbidities using the Quan-Deyo version of the Charlson categories
cmb <- icd::comorbid_quan_deyo(nhds, abbrev_names = FALSE)
nhds <- cbind(nhds, cmb, stringsAsFactors = FALSE)
Y <- nhds$adm_type == "emergency"
tab_dat <- vapply(
  unname(unlist(icd_names_charlson)),
  function(x) {
    c(sprintf("%i (%.2f%%)", 
              sum(nhds[Y, x]), 
              100 * mean(nhds[Y, x])),
      sprintf("%i (%.2f%%)",
              sum(nhds[!Y, x]),
              100 * mean(nhds[!Y, x])))
  },
  character(2)
)
knitr::kable(t(tab_dat), col.names = c("Emergency", "Not emergency"))
EmergencyNot emergency
Myocardial Infarction2707 (3.69%)1077 (1.38%)
Congestive Heart Failure12339 (16.84%)5628 (7.19%)
Periphral Vascular Disease3798 (5.18%)3042 (3.89%)
Cerebrovascular Disease5329 (7.27%)2748 (3.51%)
Dementia2175 (2.97%)728 (0.93%)
Chronic Pulmonary Disease11989 (16.36%)6762 (8.64%)
Connective Tissue Disease-Rheumatic Disease1527 (2.08%)1131 (1.44%)
Peptic Ulcer Disease1044 (1.42%)473 (0.60%)
Mild Liver Disease2030 (2.77%)1011 (1.29%)
Diabetes without complications14399 (19.65%)9125 (11.66%)
Diabetes with complications2719 (3.71%)1449 (1.85%)
Paraplegia and Hemiplegia1386 (1.89%)852 (1.09%)
Renal Disease9322 (12.72%)4604 (5.88%)
Cancer2724 (3.72%)3496 (4.47%)
Moderate or Severe Liver Disease893 (1.22%)352 (0.45%)
Metastatic Carcinoma2100 (2.87%)1663 (2.12%)
HIV/AIDS0 (0.00%)0 (0.00%)

How to get help

Look at the help files for details and examples of almost every function in this package. There are several vignettes showing the main features (See list with vignette(package = "icd")):

  • Introduction vignette("introduction", package = "icd")
  • Charlson scores vignette("charlson-scores", package = "icd")
  • Examples using ICD-10 codes vignette("ICD-10", package = "icd")
  • CMS Hierarchical Condition Codes (HCC) vignette("CMS-HCC", package = "icd")
  • Pediatric Complex Chronic Conditions (PCCC) vignette("PCCC", package = "icd")
  • Working with ICD code ranges vignette("ranges", package = "icd")
  • Comparing comorbidity maps vignette("compare-maps", package = "icd")
  • Paper detailing efficient matrix method of comorbidities vignette("efficiency", package = "icd")

Many users have emailed me directly for help, and I’ll do what I can, but it is often better to examine or add to the list of issues so we can help each other. Advanced users may look at the source code, particularly the extensive test suite which exercises all the key functions.

?comorbid
?comorbid_hcc
?explain_code
?is_valid

ICD-9 codes

ICD-9 codes are still in heavy use around the world, particularly in the USA where the ICD-9-CM (Clinical Modification) was in widespread use until the end of 2015. ICD-10 has been used worldwide for reporting cause of death for more than a decade, and ICD-11 is due to be released in 2019. ICD-10-CM is now the primary coding scheme for US hospital admission and discharge diagnoses used for regulatory purposes and billing. A vast amount of electronic patient data is recorded with ICD-9 codes of some kind: this package enables their use in R alongside ICD-10.

ICD-9 codes are not numbers, and great care is needed when matching individual codes and ranges of codes. It is easy to make mistakes, hence the need for this package. ICD-9 codes can be presented in short 5 character format, or decimal format, with a decimal place separating the code into two groups. There are also codes beginning with V and E which have different validation rules. Zeroes after a decimal place are meaningful, so numeric ICD-9 codes cannot be used in most cases. In addition, most clinical databases contain invalid codes, and even decimal and non-decimal format codes in different places. This package primarily deals with ICD-9-CM (Clinical Modification) codes, but should be applicable or easily extendable to the original WHO ICD-9 system.

ICD-10 codes

ICD-10 has a somewhat simpler format, with consistent use of a letter, then two alphanumeric characters. However, especially for ICD-10-CM, there are a multitude of qualifiers, e.g. specifying recurrence, laterality, which vastly increase the number of possible codes. This package recognizes validity of codes by syntax alone, or whether the codes appear in a canonical list. There is not yet the capability of converting between ICD-9 and ICD-10, but comorbidities can be generated from older ICD-9 codes and newer ICD-10 codes in parallel, and the comorbidities can then be compared.

Copy Link

Version

Monthly Downloads

169

Version

4.0.9

License

GPL-3

Maintainer

Last Published

May 31st, 2020

Functions in icd (4.0.9)

apply_hier

Apply hierarchy and choose naming for each comorbidity map
charlson

Calculate Charlson Comorbidity Index (Charlson Score)
as.comorbidity_map

Set the class of a named list to show it is a comorbidity map.
as.decimal_diag

Get or set whether ICD codes have have an attribute indicating 'short' or 'decimal' format
children

Get children of ICD codes
categorize_simple

Categorize codes according to a mapping
charlson_from_comorbid

Calculate Charlson scores from precomputed Charlson comorbidities
comorbid_mat_to_df

convert comorbidity data frame from matrix
attr_decimal_diag

Set ICD short-form diagnosis code attribute
count_codes_wide

Count ICD codes given in wide format
combine

Combine ICD codes
comorbid_df_to_mat

convert comorbidity matrix to data frame
attr_short_diag

Set short diagnosis flag in C++
chapters_to_map

Convert chapters to lists of codes for use as a comorbidity map
count_comorbid

Count number of comorbidities per patient
convert

Convert ICD data between formats and structures.
download_all_icd_data

Download all the additional data at once
diff_comorbid

show the difference between two comorbidity mappings
comorbid

Find comorbidities from ICD-9 codes.
expand_range_major

Expand two major codes to a range
comorbid_hcc

Get Hierarchical Condition Codes (HCC)
condense

Condense ICD-9 code by replacing complete families with parent codes
cr

sequence columns of comorbidities
generate_neds_pts

Generate simulated 'NEDS' data for 'PCCC' and bigger wide data testing
count_codes

Count ICD codes or comorbidities for each patient
expand_range.icd10cm

Expand range of ICD-10 codes returning only defined codes in ICD-10-CM
explain_code

Explain ICD-9 and ICD-10 codes in English
get_icd10be2014

Belgian ICD-10-BE
expand_range

Generate a set of codes between two ICD codes including encompassed children
explain_table

Explain ICD-9 and ICD-10 codes in English from decimal (123.45 style), Tabulates the decimal format alongside converted non-decimal format.
get_billable

Get the subset of codes that are billable according to ICD-9-CM or ICD-10-CM
explain_table_worker

generate table of ICD code explanations
get_icd10cm2014

ICD-10-CM 2014
get_icd10be2014_pc

ICD-10-BE 2014 procedure codes
get_cim10fr2019

Localised synonym for get_icd10fr2019, with French column names
get_icd10cm_version

Get the data for a given version (four-digit year) of ICD-10-CM
icd10_comorbid_reduce

ICD-10 comorbidities by reducing problem size
get_icd10cm2016

ICD-10-CM 2016
get_defined

Select only defined ICD codes
decimal_to_short

Convert Decimal format ICD codes to short format
get_icd10fr2019

French ICD-10-FR modification of WHO ICD-10 used in France
get_icd10who2016

2016 WHO ICD-10 data
get_icd10cm2016_pc

ICD-10-CM Procedure codes for 2016
icd10_map_ahrq_pcs

AHRQ ICD-10-PCS categories
get_icd10who2008fr

2008 WHO ICD-10 data in French
get_icd10cm2014_pc

ICD-10-CM Procedure codes for 2014
get_invalid

Get invalid ICD codes
get_icd10be2017_pc

ICD-10-BE 2017 procedure codes
get_icd10be2017

ICD-10-BE 2017
get_icd9cm2014_leaf

ICD-9-CM, just billable/leaf codes
icd9_map_hcc

Medicare Hierarchical Condition Categories
get_icd10cm2015_pc

ICD-10-CM Procedure codes for 2015
icd9_map_pccc

Pediatric Complex Chronic Conditions
is_valid.default

Test whether an ICD code is major
get_icd10cm2015

ICD-10-CM 2015
get_valid

invalid subset of decimal or short_code ICD-9 codes
long_to_wide

Convert ICD data from long to wide format
icd9_map_ahrq

AHRQ comorbidities
get_leaf

Get billable ICD codes
get_icd10cm_available

Get the ICD-10-CM versions available in this package
get_icd10cm2017

ICD-10-CM 2017
get_icd10cm2018_pc

ICD-10-CM Procedure codes for 2018
filter_valid

Filter ICD codes by validity.
filter_poa

Filters data frame based on present-on-arrival flag
get_icd10cm2018

ICD-10-CM 2018
poa_choices

Present-on-admission flags
get_icd10cm2017_pc

ICD-10-CM Procedure codes for 2017
is_leaf

Determine whether codes are billable leaf-nodes
icd9_map_elix

Elixhauser comorbidities
print.comorbidity_map

Print a comorbidity map
icd10_sub_chapters

ICD-10 sub-chapters
get_icd10cm_latest

The latest available version of ICD-10-CM in this package
get_icd10cm2019_pc

ICD-10-CM Procedure Codes
get_icd10cm2019

ICD-10-CM 2019
icd10cm2019

United States and Belgium ICD-10-CM
guess_short

Guess whether codes are short_code or decimal_code
icd9_map_quan_deyo

Quan adaptation of Deyo/Charlson comorbidities
names_elix

Comorbidity names
van_walraven

Calculate van Walraven Elixhauser Score
short_to_decimal

Convert ICD codes from short to decimal forms
wide_to_long

Convert ICD data from wide to long format
guess_version

Guess version of ICD codes
is_valid

Check whether ICD-9 codes are syntactically valid
shortcode_icd9

set short_to_decimal attribute
with_icd10cm_version

Evaluate code with a particular version of ICD-10-CM
icd-package

icd: Comorbidity Calculations and Tools for ICD-9 and ICD-10 Codes
plot_comorbid

Basic ordered bar plot showing counts of each comorbidity
icd10_chapters

ICD-10 chapters
is.icd9

Test presence of ICD classes
wide_vs_long

Set the ICD data structure class of a matrix or data.frame.
is.icd_long_data

Test for class describing patient data
icd9_chapters

ICD-9 chapters
vermont_dx

Hospital discharge data from Vermont
subset

extract subset(s) from ICD data
icd9_map_quan_elix

Quan adaptation of Elixhauser comorbidities
icd9_map_single_ccs

Clinical Classifications Software (CCS) for ICD9/10-CM
icd9_sub_chapters

ICD-9 sub-chapters
print.icd9

Print ICD codes and comorbidity maps cleanly
is_billable

Check whether a code is billable according to ICD-9-CM or ICD-10-CM
icd9MajMinToCode

Convert mjr and mnr vectors to single code
set_icd_class

Construct ICD-9 and ICD-10 data types
icd9cm2014_leaf

The final ICD-9-CM list of leaf (‘billable’) codes
is_defined

Check whether ICD-9 codes exist
set_icd10cm_active_year

Get or set the annual version of ICD-10-CM to use
icd9cm_hierarchy

ICD-9-CM diagnosis codes including leaf nodes and branch names up to the three-digit codes.
set_icd_data_dir

Set up the data download cache, give permission to download data
sort_icd

Sort or order ICD-9 or ICD-10 codes according to published sequence
uranium_pathology

United States Transuranium & Uranium Registries
[[.comorbidity_map

Extract vector of codes from an ICD comorbidity map