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