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
See common/README.md for more details and references.
Charlson Comorbidity Index
Categories are: Myocardial infarction, Congestive heart failure, Peripheral vascular disease, Cerebrovascular disease, Dementia, Chronic pulmonary disease, Rheumatic disease, Peptic ulcer disease, Mild liver disease, Diabetes without chronic complication, Diabetes with chronic complication, Hemiplegia or paraplegia, Renal disease, Any malignancy, including lymphoma and leukemia, except malignant neoplasm of skin, Moderate or severe liver disease, Metastatic solid tumor, AIDS/HIV. The Danish/Thygesen variant instead keeps Any tumor, Leukemia, and Lymphoma as three separate categories, as in the original 1987 Charlson paper.
- 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")
- Deyo et al. 1992 (Deyo 1992) – ICD-9-CM (
- 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")
- Charlson et al. 1987 (Charlson 1987) (
Elixhauser Comorbidity Index
Categories are: Congestive heart failure, Cardiac arrhythmias, Valvular disease, Pulmonary circulation disorders, Peripheral vascular disorders, Hypertension uncomplicated, Hypertension complicated, Paralysis, Other neurological disorders, Chronic pulmonary disease, Diabetes uncomplicated, Diabetes complicated, Hypothyroidism, Renal failure, Liver disease, Peptic ulcer disease excluding bleeding, AIDS/HIV, Lymphoma, Metastatic cancer, Solid tumor without metastasis, Rheumatoid arthritis/collagen vascular diseases, Coagulopathy, Obesity, Weight loss, Fluid and electrolyte disorders, Blood loss anemia, Deficiency anemia, Alcohol abuse, Drug abuse, Psychoses, Depression.
- 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")
- Elixhauser et al. 1998 (Elixhauser 1998) – ICD-9-CM (
- Weights:
- van Walraven et al. 2009 (van Walraven 2009) (
weights="van_walraven") - Thompson et al. 2015 (Thompson 2015) (
weights="thompson_30"orweights="thompson_29") - AHRQ v3.7, Moore et al. 2017 (Moore 2017) – ICD-9-CM (
weights="ahrq"; always used withimplementation="ahrq_icd9") - AHRQ Refined v2026.1 (AHRQ Comorbidity Software) – ICD-10-CM (
weights="ahrq"; always used withimplementation="ahrq_icd10") - Swiss, Sharma et al. 2021 (Sharma 2021) (
weights="swiss")
- van Walraven et al. 2009 (van Walraven 2009) (
Combined Comorbidity Score
Categories are: Alcohol abuse, Any tumor, Cardiac arrhythmias, Chronic pulmonary disease, Coagulopathy, Complicated diabetes, Congestive heart failure, Deficiency anemia, Dementia, Fluid and electrolyte disorders, Hemiplegia, HIV/AIDS, Hypertension, Liver disease, Metastatic cancer, Peripheral vascular disease, Psychosis, Pulmonary circulation disorders, Renal failure, Weight loss.
- 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")
- Gagne et al. 2011 (Gagne 2011) – ICD-9-CM (
- Weights:
- Gagne et al. 2011 (Gagne 2011) (
score="combined")
- Gagne et al. 2011 (Gagne 2011) (
Hospital Frailty Risk Score
- Mappings:
- Gilbert et al. 2018 (Gilbert 2018) – ICD-10 (
score="hfrs")
- Gilbert et al. 2018 (Gilbert 2018) – ICD-10 (
- Weights:
- Gilbert et al. 2018 (Gilbert 2018) (
score="hfrs")
- Gilbert et al. 2018 (Gilbert 2018) (
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 docstrings in each module for details on 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. With path, it writes them to a folder. read_reporting reads such a folder back into arguments for a "custom" index, so a published definition can be reused.
from pycomorb import comorbidity, comorbidity_reporting, read_reporting
template, weights, codes, hierarchy = comorbidity_reporting(
"charlson",
implementation="quan",
icd_version="icd10",
path="charlson_report", # Writes template.md, weights.csv, codes.csv, hierarchy.csv
data_sources="Example EHR", # Optional study information
look_back_period="1 year",
)
# Recompute the score from the reported definition
custom = comorbidity("custom", df, id_col="id", code_col="code", **read_reporting("charlson_report"))
The resulting template.md (study information you don't pass stays empty, to be filled in by hand):
| domain | information |
|---|---|
| Data source(s) | Example EHR |
| Method of data extraction | |
| Comorbidity weighting reference | Charlson et al. (1987) |
| Comorbidity weighting list | weights.csv |
| Disease classification system | ICD-10 |
| Disease code reference | Quan et al. (2005) |
| Disease code list | codes.csv |
| Coding practice | |
| Age adjustment | Age points: 0 (<50 years), 1 (50-59), 2 (60-69), 3 (70-79), 4 (>=80) |
| Hierarchy rules | 'Diabetes with chronic complication' replaces 'Diabetes without chronic complication'; 'Moderate or severe liver disease' replaces 'Mild liver disease'; 'Metastatic solid tumor' replaces 'Any malignancy, including lymphoma and leukemia, except malignant neoplasm of skin' |
| Look-back period | 1 year |
| Timing of data extraction | |
| Software | pycomorb 1.20261001.1 |
License and Documentation
- Free software: MIT license (see LICENSE)
- Citation: see CITATION.cff (GitHub "Cite this repository" button)
- Documentation: (TODO)
- Data sources and attributions (incl. BfArM ICD-10-GM): see NOTICE; variant references in common/README.md
Metadata
Release files for pycomorb 1.20261001.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pycomorb-1.20261001.1.tar.gz | 204.7 kB | Without provenance | Details for pycomorb-1.20261001.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pycomorb-1.20261001.1-py3-none-any.whl | Python 3 | none | any | Details for pycomorb-1.20261001.1-py3-none-any.whl |
Total release size: 313.5 kB
Release files / pycomorb-1.20261001.1.tar.gz
| Download URL | pycomorb-1.20261001.1.tar.gz |
|---|---|
| Size | 204.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
638678972cef58252890cd1d91826ddb51a89937e10c0439c9fc0c26ea12ee93
|
|
BLAKE2b-256 checksum How to use checksums |
c7f868861638be0312c1feb0f4a56e82195eeaa752025dbd7683a50514adc87d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
Release files / pycomorb-1.20261001.1-py3-none-any.whl
| Download URL | pycomorb-1.20261001.1-py3-none-any.whl |
|---|---|
| Size | 108.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2c87b459a608c165547f00733fb2adea069d1f435b677bc91d48a5d98f463f37
|
|
BLAKE2b-256 checksum How to use checksums |
3895ee2c5212836b5f80d532314cea0b4665bd6e72fb4bc4c462035e80f2bed0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
Security for pycomorb 1.20261001.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.