pycomorb

Python package to calculate comorbidity and frailty scores using ICD codes and polars DataFrames.

Overview

pycomorb provides fast, flexible, and reproducible calculation of clinical risk scores from ICD-coded data. It supports multiple comorbidity and frailty indices, including several international variants.

It is inspired by the R package comorbidity by Alessandro Gasparini and the corresponding Python rewrite comorbidipy by Vishnu V Chandrabalan.

As a special feature, it also implements the history of the German Modification of the ICD-10 (ICD-10-GM) coding system, allowing users to apply the correct mappings and weights based on the year of diagnosis.

Included Indices / Scores

• Charlson Comorbidity Index (multiple mappings and weights)
• Elixhauser Comorbidity Index (multiple mappings and weights)
• Combined Comorbidity Score (Gagne et al.)
• Hospital Frailty Risk Score (HFRS)

Supported Variants

Details, options and category names are in the documentation; references in common/README.md.

Charlson Comorbidity Index

• Mappings:
  • Deyo et al. 1992 (Deyo 1992) – ICD-9-CM (implementation="deyo")
  • Romano et al. 1993 (Romano 1993) – ICD-9-CM (implementation="romano")
  • D'Hoore et al. 1996 (D'Hoore 1996) – ICD-9-CM (implementation="dhoore")
  • Australia, Sundararajan et al. 2004 (Sundararajan 2004) – ICD-10-AM (implementation="australia")
  • Quan et al. 2005 (Quan 2005) – ICD-9-CM and ICD-10 (implementation="quan")
  • RCS, Armitage and van der Meulen 2010 (Armitage & van der Meulen 2010) – ICD-10 (always used with RCS weights) (implementation="rcs")
  • Denmark, Thygesen et al. 2011 (Thygesen 2011) – ICD-10 (implementation="thygesen")
  • Sweden, Ludvigsson et al. 2021 (Ludvigsson 2021) – ICD-9 and ICD-10 (implementation="sweden")
  • UK SHMI, NHS Digital v1.60 (June 2026) – ICD-10 (always used with SHMI weights) (implementation="uk_shmi")
  • Germany, Sokołowski et al. 2026 (Sokołowski 2026) – ICD-10-GM (year-specific; requires year_col) (implementation="sokolowski")
• Weights:
  • Charlson et al. 1987 (Charlson 1987) (weights="charlson")
  • Schneeweiss et al. 2003 (Schneeweiss 2003) (weights="schneeweiss")
  • RCS, Armitage and van der Meulen 2010 (Armitage & van der Meulen 2010) (weights="rcs")
  • Quan et al. 2011 (Quan 2011) (weights="quan")
  • UK SHMI, NHS Digital v1.60 (June 2026) (negative totals are floored at zero) (weights="uk_shmi")

Elixhauser Comorbidity Index

• Mappings:
  • Elixhauser et al. 1998 (Elixhauser 1998) – ICD-9-CM (implementation="elixhauser")
  • Quan et al. 2005 (Quan 2005) – ICD-9-CM and ICD-10 (implementation="quan")
  • AHRQ v3.7 (AHRQ Comorbidity Software) – ICD-9-CM (implementation="ahrq_icd9")
  • AHRQ Refined v2026.1 (AHRQ Comorbidity Software) – ICD-10-CM (year-specific; requires year_col) (implementation="ahrq_icd10")
• Weights:
  • van Walraven et al. 2009 (van Walraven 2009) (weights="van_walraven")
  • Thompson et al. 2015 (Thompson 2015) (weights="thompson_30" or weights="thompson_29")
  • AHRQ v3.7, Moore et al. 2017 (Moore 2017) – ICD-9-CM (weights="ahrq"; always used with implementation="ahrq_icd9")
  • AHRQ Refined v2026.1 (AHRQ Comorbidity Software) – ICD-10-CM (weights="ahrq"; always used with implementation="ahrq_icd10")
  • Swiss, Sharma et al. 2021 (Sharma 2021) (weights="swiss")

Combined Comorbidity Score

• Mappings:
  • Gagne et al. 2011 (Gagne 2011) – ICD-9-CM (score="combined", icd_version="icd9"; Charlson conditions after Romano 1993, Elixhauser conditions after Quan 2005)
  • Sun et al. 2017 (Sun 2017) – ICD-10-CM (score="combined", icd_version="icd10")
• Weights:
  • Gagne et al. 2011 (Gagne 2011) (score="combined")

Hospital Frailty Risk Score

• Mappings:
  • Gilbert et al. 2018 (Gilbert 2018) – ICD-10 (score="hfrs")
• Weights:
  • Gilbert et al. 2018 (Gilbert 2018) (score="hfrs")

Documentation

Full documentation, including all supported variants, options, ICD modification handling and reporting, is at https://cub-corr.github.io/pycomorb/:

• Scores: mappings, weights and categories of every variant
• Input and output
• ICD modification: year-specific ICD-10-GM and ICD-10-CM mappings
• Reporting: document the exact definition behind a score
• References

Installation

You can install pycomorb via pip:

pip install pycomorb

Usage

import polars as pl
from pycomorb import comorbidity

# Example: Calculate Charlson score
df = pl.DataFrame({
    "id": [1, 2, 3],
    "code": ["I21", "E119", "C349"],
    "age": [65, 72, 80]
})

charlson = comorbidity(
    score="charlson",
    df=df,
    id_col="id",
    code_col="code",
    age_col="age",
    icd_version="icd10",
    implementation="quan",
    return_categories=True
)

See the documentation for all arguments and supported variants.

Reporting

comorbidity_reporting documents the exact definition behind a score: a methods table to paste into a manuscript, plus the weights, code list and hierarchy rules used. read_reporting reads such a folder back, so a published definition can be reused as a "custom" index. See the reporting documentation.

License and citation

• Free software: MIT license (see LICENSE)
• Citation: see CITATION.cff (GitHub "Cite this repository" button)
• Data sources and attributions (incl. BfArM ICD-10-GM): see NOTICE; variant references in common/README.md