ICD Mappings

0.6.2 verified Sat May 09 auth: no python

Python tool for mapping ICD diagnostic codes across classifications (e.g., ICD-10 to CCS, CCI, CCC, ICD-9, chapters, blocks). Current version 0.6.2, supports Python 3.8-3.14. Active development with monthly releases.

pip install icd-mappings

Common errors

error ModuleNotFoundError: No module named 'icd_mappings.mappers' ↓

cause Old import path used; module structure changed in v0.3.0.

fix

Import from correct subpackage: from icd_mappings.mappers import Icd10Mapper

error AttributeError: 'NoneType' object has no attribute '...' ↓

cause Mapper returned None because code is unmappable (v0.3.0+ behavior).

fix

Check if result is None before accessing attributes: result = mapper.map(code, target); if result: ...

error icd_mappings.exceptions.CodeNotMappedError ↓

cause Using version <0.3.0, which raises exceptions for unmappable codes.

fix

Upgrade to >=0.3.0 and handle None returns, or catch the exception.

Warnings

breaking In v0.3.0, mappers no longer raise errors for unmappable codes; they return None. Code that relied on exceptions will break. ↓

fix Update code to handle None returns instead of catching exceptions.

deprecated Top-level imports like `from icd_mappings import Icd10Mapper` were removed in v0.3.0. ↓

fix Use `from icd_mappings.mappers import Icd10Mapper`.

gotcha Input codes work with or without dots (normalized automatically). However, be aware that normalization removes dots before validation, so 'J450' and 'J45.0' are treated identically. ↓

fix No fix needed; rely on consistency.

gotcha Mapper data is downloaded on first use; ensure internet connectivity or preload data. ↓

fix Use `mapper = Icd10Mapper(use_cache=True)` to cache data locally.

Imports

Icd10Mapper
wrong
```
from icd_mappings import Icd10Mapper
```
correct
```
from icd_mappings.mappers import Icd10Mapper
```
Top-level import was removed in v0.3.0; mappers moved to subpackage.

Icd9Mapper

wrong

from icd_mappings.mappers import Icd9Mapper

correct

from icd_mappings.mappers import Icd9Mapper

No common mistake; keep correct pattern.

CcsMapper

from icd_mappings.mappers import CcsMapper

Quickstart

Initialize a mapper and convert ICD-10 codes to chapters or blocks.

from icd_mappings.mappers import Icd10Mapper

mapper = Icd10Mapper()
# Map single code
print(mapper.map('J45.0', target='chapter'))  # '10 - Diseases of the respiratory system'
# Map multiple codes
codes = ['J45.0', 'E11.9']
results = {code: mapper.map(code, target='blocks') for code in codes}
print(results)