comorbidipy

A high-performance Python package for calculating comorbidity scores and clinical risk scores from ICD codes.

Built with Polars for blazing-fast processing of large datasets.

Features

• Charlson Comorbidity Index – Multiple mapping variants (Quan, Swedish, Australian, SHMI) and weighting schemes
• Elixhauser Comorbidity Index – Quan mapping with van Walraven or Swiss weights
• Hospital Frailty Risk Score (HFRS) – For patients ≥75 years
• Disability & Sensory Impairments – Learning disabilities, visual and hearing impairments

Installation

pip install comorbidipy

Requires Python 3.13+.

Quick Start

Python API

import polars as pl
from comorbidipy import comorbidity, hfrs, disability

# Sample data
df = pl.DataFrame({
    "id": ["P001", "P001", "P002", "P002"],
    "code": ["I21", "E112", "I50", "J44"],
    "age": [65, 65, 72, 72],
})

# Calculate Charlson Comorbidity Index
result = comorbidity(df, id_col="id", code_col="code", age_col="age")

# Calculate Hospital Frailty Risk Score
frailty = hfrs(df, id_col="id", code_col="code")

# Identify disabilities
disabilities = disability(df, id_col="id", code_col="code")

Command Line Interface

# Charlson score
comorbidipy charlson input.csv output.csv --age-col age

# Elixhauser score
comorbidipy elixhauser input.parquet output.parquet --weights van_walraven

# Hospital Frailty Risk Score
comorbidipy hfrs input.csv output.csv

# Disability identification
comorbidipy disability input.csv output.csv

# Show available options
comorbidipy info

Supported file formats: CSV, Parquet, JSON, NDJSON, Avro.

Charlson Variants

Mapping	ICD-9	ICD-10	Description
quan	✅	✅	Quan et al. (2005)
swedish	❌	✅	Swedish National Patient Register
australian	❌	✅	Australian IHW adaptation
shmi	❌	✅	UK SHMI specification

Weighting	Description
charlson	Original 1987 weights
quan	Quan et al. updated weights
shmi	UK SHMI weights
shmi_modified	Modified SHMI weights

Documentation

Full documentation: https://vvcb.github.io/comorbidipy

License

MIT License – see LICENSE for details.

Credits

• Inspired by the R library comorbidity by Alessandro Gasparini
• Built with Polars and Typer