MedCode#

Translating Between Medical Standards#

Healthcare data comes in many different coding systems and standards. PyHealth’s medical code mapping enables:

Cross-system mapping (e.g., ICD9CM → CCSCM, NDC → ATC)
Within-system ontology lookup (e.g., ancestors/descendants in ICD, ATC hierarchy)

Quick Examples#

from pyhealth.medcode import CrossMap, InnerMap

# Cross-system mapping: ICD-9-CM → CCS
icd9_to_ccs = CrossMap.load("ICD9CM", "CCSCM")
print(icd9_to_ccs.map("82101"))  # example diagnosis code

# Drug code mapping: NDC → ATC
ndc_to_atc = CrossMap.load("NDC", "ATC")
print(ndc_to_atc.map("00527051210"))

# Within-system lookup: ICD-9-CM
icd9cm = InnerMap.load("ICD9CM")
print(icd9cm.lookup("428.0"))
print(icd9cm.get_ancestors("428.0"))

# Translating between ICD versions
icd9_to_icd10 = CrossMap.load("ICD9CM", "ICD10CM")
print(icd9_to_icd10.map("428.0"))          # ['I50.9']

# Grouping ICD-10 into CCSR categories
icd10_to_ccsr = CrossMap.load("ICD10CM", "CCSR")
print(icd10_to_ccsr.map("I50.9"))          # ['CIR019']

# Coarser groupings, useful when a cohort is small
print(CrossMap.load("ICD9CM", "ICD9CHAPTER").map("428.0"))       # ['7']
print(CrossMap.load("ICD10CM", "ICD10CHAPTER").map("E11.9"))     # ['E00-E89']
print(CrossMap.load("ICD10CM", "ICD10BLOCK").map("A41.9"))       # ['A30-A49']

# Binary chronic-condition flags
print(CrossMap.load("ICD9CM", "CCI").map("428.0"))               # ['1']
print(CrossMap.load("ICD9CM", "CCI").map("486"))                 # ['0']

# Which source served the mapping
print(icd10_to_ccsr.backend)                                     # 'icdmappings'

We provide medical code mapping tools for (i) ontology mapping within one coding system and (ii) mapping the same concept cross different coding systems.

class pyhealth.medcode.InnerMap(vocabulary, refresh_cache=False)[source]#

Bases: ABC

Contains information for a specific medical code system.

InnerMap is a base abstract class for all medical code systems. It will be instantiated as a specific medical code system with InnerMap.load(vocabulary).

Note

This class cannot be instantiated using __init__() (throws an error).

classmethod load(vocabulary, refresh_cache=False)[source]#

Initializes a specific medical code system inheriting from InnerMap.

Parameters:

vocabulary (str) – vocabulary name. E.g., “ICD9CM”, “ICD9PROC”.
refresh_cache (bool) – whether to refresh the cache. Default is False.

Examples

>>> from pyhealth.medcode import InnerMap
>>> icd9cm = InnerMap.load("ICD9CM")
>>> icd9cm.lookup("428.0")
'Congestive heart failure, unspecified'
>>> icd9cm.get_ancestors("428.0")
['428', '420-429.99', '390-459.99', '001-999.99']

property available_attributes: List[str]#

Returns a list of available attributes.

Return type:: List[str]
Returns:: List of available attributes.

stat()[source]#: Prints statistics of the code system.

static standardize(code)[source]#

Standardizes a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

static convert(code, **kwargs)[source]#

Converts a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

lookup(code, attribute='name')[source]#

Looks up the code.

Parameters:

code (str) – code to look up.
attribute (str) – attribute to look up. One of self.available_attributes. Default is “name”.

Returns:

The attribute value of the code.

get_ancestors(code)[source]#

Gets the ancestors of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

get_descendants(code)[source]#

Gets the descendants of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

class pyhealth.medcode.CrossMap(source_vocabulary, target_vocabulary, refresh_cache=False, backend='auto')[source]#

Bases: object

Contains mapping between two medical code systems.

CrossMap is a base class for all possible mappings. It will be initialized with two specific medical code systems with CrossMap.load(source_vocabulary, target_vocabulary).

Mappings PyHealth hosts itself are always preferred. Pairs PyHealth has no table for – ICD-9 <-> ICD-10 and the grouper vocabularies – are served by the icd-mappings package instead. CrossMap.backend records which source was used.

Examples

>>> from pyhealth.medcode import CrossMap
>>> # PyHealth's own table, selected automatically
>>> mapping = CrossMap.load("ICD9CM", "CCSCM")
>>> mapping.backend
'pyhealth'
>>> mapping.map("428.0")
['108']
>>> # translating between ICD versions
>>> CrossMap.load("ICD9CM", "ICD10CM").map("250.00")
['E11.9']
>>> CrossMap.load("ICD10CM", "ICD9CM").map("N17.9")
['584.9']
>>> # grouping into a coarser vocabulary
>>> CrossMap.load("ICD10CM", "CCSR").map("J18.9")
['RSP002']
>>> CrossMap.load("ICD10CM", "ICD10CHAPTER").map("E11.9")
['E00-E89']
>>> # translation is not symmetric: mapping back lands elsewhere
>>> CrossMap.load("ICD9CM", "ICD10CM").map("038.9")
['A41.9']
>>> CrossMap.load("ICD10CM", "ICD9CM").map("A41.9")
['995.91']

property s_class#: The source vocabulary instance, resolved on first use.

property t_class#: The target vocabulary instance, resolved on first use.

property unmapped_codes#: Source codes seen so far that had no target in this mapping.

classmethod load(source_vocabulary, target_vocabulary, refresh_cache=False, backend='auto')[source]#

Initializes the mapping between two medical code systems.

Parameters:

source_vocabulary (str) – source medical code system.
target_vocabulary (str) – target medical code system.
refresh_cache (bool) – whether to refresh the cache. Default is False.
backend (str) – which data source to use. “auto” (the default) prefers PyHealth’s own mapping tables and falls back to the icd-mappings package for pairs PyHealth has no table for. “pyhealth” and “icdmappings” force one or the other.

Examples

>>> from pyhealth.medcode import CrossMap
>>> mapping = CrossMap("ICD9CM", "CCSCM")
>>> mapping.map("428.0")
['108']

>>> mapping = CrossMap.load("NDC", "ATC")
>>> mapping.map("00527051210", target_kwargs={"level": 3})
['A11C']

>>> mapping = CrossMap.load("ICD10CM", "CCSR")
>>> mapping.map("I50.9")
['CIR019']

Forcing a backend. ICD9CM->CCSCM is servable by both sources; it stays on PyHealth’s table by default, and the same mapping can be had offline on request:

>>> CrossMap.load("ICD9CM", "CCSCM", backend="icdmappings").backend
'icdmappings'

map(source_code, source_kwargs=None, target_kwargs=None)[source]#

Maps a source code to a list of target codes.

Parameters:

source_code (str) – source code.
**source_kwargs (Optional[Dict]) – additional arguments for the source code. Will be passed to self.s_class.convert(). Default is empty dict.
**target_kwargs (Optional[Dict]) – additional arguments for the target code. Will be passed to self.t_class.convert(). Default is empty dict.

Return type:

List[str]

Returns:

A list of target codes.

Diagnosis codes:#

class pyhealth.medcode.ICD9CM(**kwargs)[source]#

Bases: InnerMap

9-th International Classification of Diseases, Clinical Modification.

static standardize(code)[source]#: Standardizes ICD9CM code.

property available_attributes: List[str]#

Returns a list of available attributes.

Return type:: List[str]
Returns:: List of available attributes.

static convert(code, **kwargs)#

Converts a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

get_ancestors(code)#

Gets the ancestors of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

get_descendants(code)#

Gets the descendants of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

classmethod load(vocabulary, refresh_cache=False)#

Initializes a specific medical code system inheriting from InnerMap.

Parameters:

vocabulary (str) – vocabulary name. E.g., “ICD9CM”, “ICD9PROC”.
refresh_cache (bool) – whether to refresh the cache. Default is False.

Examples

>>> from pyhealth.medcode import InnerMap
>>> icd9cm = InnerMap.load("ICD9CM")
>>> icd9cm.lookup("428.0")
'Congestive heart failure, unspecified'
>>> icd9cm.get_ancestors("428.0")
['428', '420-429.99', '390-459.99', '001-999.99']

lookup(code, attribute='name')#

Looks up the code.

Parameters:

code (str) – code to look up.
attribute (str) – attribute to look up. One of self.available_attributes. Default is “name”.

Returns:

The attribute value of the code.

stat()#: Prints statistics of the code system.

class pyhealth.medcode.ICD10CM(**kwargs)[source]#

Bases: InnerMap

10-th International Classification of Diseases, Clinical Modification.

static standardize(code)[source]#: Standardizes ICD10CM code.

property available_attributes: List[str]#

Returns a list of available attributes.

Return type:: List[str]
Returns:: List of available attributes.

static convert(code, **kwargs)#

Converts a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

get_ancestors(code)#

Gets the ancestors of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

get_descendants(code)#

Gets the descendants of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

classmethod load(vocabulary, refresh_cache=False)#

Initializes a specific medical code system inheriting from InnerMap.

Parameters:

vocabulary (str) – vocabulary name. E.g., “ICD9CM”, “ICD9PROC”.
refresh_cache (bool) – whether to refresh the cache. Default is False.

Examples

>>> from pyhealth.medcode import InnerMap
>>> icd9cm = InnerMap.load("ICD9CM")
>>> icd9cm.lookup("428.0")
'Congestive heart failure, unspecified'
>>> icd9cm.get_ancestors("428.0")
['428', '420-429.99', '390-459.99', '001-999.99']

lookup(code, attribute='name')#

Looks up the code.

Parameters:

code (str) – code to look up.
attribute (str) – attribute to look up. One of self.available_attributes. Default is “name”.

Returns:

The attribute value of the code.

stat()#: Prints statistics of the code system.

class pyhealth.medcode.CCSCM(**kwargs)[source]#

Bases: InnerMap

Classification of Diseases, Clinical Modification.

property available_attributes: List[str]#

Returns a list of available attributes.

Return type:: List[str]
Returns:: List of available attributes.

static convert(code, **kwargs)#

Converts a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

get_ancestors(code)#

Gets the ancestors of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

get_descendants(code)#

Gets the descendants of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

classmethod load(vocabulary, refresh_cache=False)#

Initializes a specific medical code system inheriting from InnerMap.

Parameters:

vocabulary (str) – vocabulary name. E.g., “ICD9CM”, “ICD9PROC”.
refresh_cache (bool) – whether to refresh the cache. Default is False.

Examples

>>> from pyhealth.medcode import InnerMap
>>> icd9cm = InnerMap.load("ICD9CM")
>>> icd9cm.lookup("428.0")
'Congestive heart failure, unspecified'
>>> icd9cm.get_ancestors("428.0")
['428', '420-429.99', '390-459.99', '001-999.99']

lookup(code, attribute='name')#

Looks up the code.

Parameters:

code (str) – code to look up.
attribute (str) – attribute to look up. One of self.available_attributes. Default is “name”.

Returns:

The attribute value of the code.

static standardize(code)#

Standardizes a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

stat()#: Prints statistics of the code system.

Procedure codes:#

class pyhealth.medcode.ICD9PROC(**kwargs)[source]#

Bases: InnerMap

9-th International Classification of Diseases, Procedure.

static standardize(code)[source]#: Standardizes ICD9PROC code.

property available_attributes: List[str]#

Returns a list of available attributes.

Return type:: List[str]
Returns:: List of available attributes.

static convert(code, **kwargs)#

Converts a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

get_ancestors(code)#

Gets the ancestors of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

get_descendants(code)#

Gets the descendants of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

classmethod load(vocabulary, refresh_cache=False)#

Initializes a specific medical code system inheriting from InnerMap.

Parameters:

vocabulary (str) – vocabulary name. E.g., “ICD9CM”, “ICD9PROC”.
refresh_cache (bool) – whether to refresh the cache. Default is False.

Examples

>>> from pyhealth.medcode import InnerMap
>>> icd9cm = InnerMap.load("ICD9CM")
>>> icd9cm.lookup("428.0")
'Congestive heart failure, unspecified'
>>> icd9cm.get_ancestors("428.0")
['428', '420-429.99', '390-459.99', '001-999.99']

lookup(code, attribute='name')#

Looks up the code.

Parameters:

code (str) – code to look up.
attribute (str) – attribute to look up. One of self.available_attributes. Default is “name”.

Returns:

The attribute value of the code.

stat()#: Prints statistics of the code system.

class pyhealth.medcode.ICD10PROC(**kwargs)[source]#

Bases: InnerMap

10-th International Classification of Diseases, Procedure.

property available_attributes: List[str]#

Returns a list of available attributes.

Return type:: List[str]
Returns:: List of available attributes.

static convert(code, **kwargs)#

Converts a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

get_ancestors(code)#

Gets the ancestors of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

get_descendants(code)#

Gets the descendants of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

classmethod load(vocabulary, refresh_cache=False)#

Initializes a specific medical code system inheriting from InnerMap.

Parameters:

vocabulary (str) – vocabulary name. E.g., “ICD9CM”, “ICD9PROC”.
refresh_cache (bool) – whether to refresh the cache. Default is False.

Examples

>>> from pyhealth.medcode import InnerMap
>>> icd9cm = InnerMap.load("ICD9CM")
>>> icd9cm.lookup("428.0")
'Congestive heart failure, unspecified'
>>> icd9cm.get_ancestors("428.0")
['428', '420-429.99', '390-459.99', '001-999.99']

lookup(code, attribute='name')#

Looks up the code.

Parameters:

code (str) – code to look up.
attribute (str) – attribute to look up. One of self.available_attributes. Default is “name”.

Returns:

The attribute value of the code.

static standardize(code)#

Standardizes a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

stat()#: Prints statistics of the code system.

class pyhealth.medcode.CCSPROC(**kwargs)[source]#

Bases: InnerMap

Classification of Diseases, Procedure.

property available_attributes: List[str]#

Returns a list of available attributes.

Return type:: List[str]
Returns:: List of available attributes.

static convert(code, **kwargs)#

Converts a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

get_ancestors(code)#

Gets the ancestors of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

get_descendants(code)#

Gets the descendants of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

classmethod load(vocabulary, refresh_cache=False)#

Initializes a specific medical code system inheriting from InnerMap.

Parameters:

vocabulary (str) – vocabulary name. E.g., “ICD9CM”, “ICD9PROC”.
refresh_cache (bool) – whether to refresh the cache. Default is False.

Examples

>>> from pyhealth.medcode import InnerMap
>>> icd9cm = InnerMap.load("ICD9CM")
>>> icd9cm.lookup("428.0")
'Congestive heart failure, unspecified'
>>> icd9cm.get_ancestors("428.0")
['428', '420-429.99', '390-459.99', '001-999.99']

lookup(code, attribute='name')#

Looks up the code.

Parameters:

code (str) – code to look up.
attribute (str) – attribute to look up. One of self.available_attributes. Default is “name”.

Returns:

The attribute value of the code.

static standardize(code)#

Standardizes a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

stat()#: Prints statistics of the code system.

Medication codes:#

class pyhealth.medcode.NDC(**kwargs)[source]#

Bases: InnerMap

National Drug Code.

property available_attributes: List[str]#

Returns a list of available attributes.

Return type:: List[str]
Returns:: List of available attributes.

static convert(code, **kwargs)#

Converts a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

get_ancestors(code)#

Gets the ancestors of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

get_descendants(code)#

Gets the descendants of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

classmethod load(vocabulary, refresh_cache=False)#

Initializes a specific medical code system inheriting from InnerMap.

Parameters:

vocabulary (str) – vocabulary name. E.g., “ICD9CM”, “ICD9PROC”.
refresh_cache (bool) – whether to refresh the cache. Default is False.

Examples

>>> from pyhealth.medcode import InnerMap
>>> icd9cm = InnerMap.load("ICD9CM")
>>> icd9cm.lookup("428.0")
'Congestive heart failure, unspecified'
>>> icd9cm.get_ancestors("428.0")
['428', '420-429.99', '390-459.99', '001-999.99']

lookup(code, attribute='name')#

Looks up the code.

Parameters:

code (str) – code to look up.
attribute (str) – attribute to look up. One of self.available_attributes. Default is “name”.

Returns:

The attribute value of the code.

static standardize(code)#

Standardizes a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

stat()#: Prints statistics of the code system.

class pyhealth.medcode.RxNorm(**kwargs)[source]#

Bases: InnerMap

RxNorm.

property available_attributes: List[str]#

Returns a list of available attributes.

Return type:: List[str]
Returns:: List of available attributes.

static convert(code, **kwargs)#

Converts a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

get_ancestors(code)#

Gets the ancestors of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

get_descendants(code)#

Gets the descendants of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

classmethod load(vocabulary, refresh_cache=False)#

Initializes a specific medical code system inheriting from InnerMap.

Parameters:

vocabulary (str) – vocabulary name. E.g., “ICD9CM”, “ICD9PROC”.
refresh_cache (bool) – whether to refresh the cache. Default is False.

Examples

>>> from pyhealth.medcode import InnerMap
>>> icd9cm = InnerMap.load("ICD9CM")
>>> icd9cm.lookup("428.0")
'Congestive heart failure, unspecified'
>>> icd9cm.get_ancestors("428.0")
['428', '420-429.99', '390-459.99', '001-999.99']

lookup(code, attribute='name')#

Looks up the code.

Parameters:

code (str) – code to look up.
attribute (str) – attribute to look up. One of self.available_attributes. Default is “name”.

Returns:

The attribute value of the code.

static standardize(code)#

Standardizes a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

stat()#: Prints statistics of the code system.

class pyhealth.medcode.ATC(**kwargs)[source]#

Bases: InnerMap

Anatomical Therapeutic Chemical.

static convert(code, level=5)[source]#: Convert ATC code to a specific level.

get_ddi(gamenet_ddi=False, refresh_cache=False)[source]#

Gets the drug-drug interactions (DDI).

Parameters:

gamenet_ddi (bool) – Whether to use the DDI from the GAMENet paper, which is a subset of the DDI from the ATC.
refresh_cache (bool) – Whether to refresh the cache. Default is False.

Return type:

List[str]

property available_attributes: List[str]#

Returns a list of available attributes.

Return type:: List[str]
Returns:: List of available attributes.

get_ancestors(code)#

Gets the ancestors of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

get_descendants(code)#

Gets the descendants of the code.

Parameters:: code (str) – code to look up.
Return type:: List[str]
Returns:: List of ancestors ordered from the closest to the farthest.

classmethod load(vocabulary, refresh_cache=False)#

Initializes a specific medical code system inheriting from InnerMap.

Parameters:

vocabulary (str) – vocabulary name. E.g., “ICD9CM”, “ICD9PROC”.
refresh_cache (bool) – whether to refresh the cache. Default is False.

Examples

>>> from pyhealth.medcode import InnerMap
>>> icd9cm = InnerMap.load("ICD9CM")
>>> icd9cm.lookup("428.0")
'Congestive heart failure, unspecified'
>>> icd9cm.get_ancestors("428.0")
['428', '420-429.99', '390-459.99', '001-999.99']

lookup(code, attribute='name')#

Looks up the code.

Parameters:

code (str) – code to look up.
attribute (str) – attribute to look up. One of self.available_attributes. Default is “name”.

Returns:

The attribute value of the code.

static standardize(code)#

Standardizes a given code.

Subclass will override this method based on different medical code systems.

Return type:: str

stat()#: Prints statistics of the code system.

ICD translation and grouper vocabularies#

PyHealth hosts its own mapping tables and always prefers them. Pairs it has no table for are served by the icd-mappings package, whose data ships inside its wheel and therefore needs no network access. CrossMap.backend reports which source was used, and the choice can be forced with CrossMap.load(..., backend="pyhealth") or backend="icdmappings".

ICD9CM->CCSCM is the one pair both sources can serve. It stays on PyHealth’s hosted table under backend="auto" so that existing pipelines are unaffected; pass backend="icdmappings" explicitly to get the same mapping offline.

Supported pairs, by source:

Warning

ICD-9 <-> ICD-10 translation is a primary-mapping approximation, not the full many-to-many GEM relation. map() returns at most one target code, some codes have no mapping at all, and the translation does not round-trip (428.0 maps to I50.9, which maps back to 428.9). Measured on the 581 distinct ICD-9 codes in the MIMIC-III demo, 561 mapped and 17 distinct ICD-9 codes collapsed onto a shared ICD-10 code. Inspect CrossMap.unmapped_codes after a pass over a dataset to quantify the loss.

For grouping mixed ICD-9/ICD-10 data into one feature space, prefer mapping both versions into a shared grouper (CCS or CCSR) rather than translating one version into the other.

class pyhealth.medcode.FlatMap(vocabulary, refresh_cache=False)[source]#

Bases: ABC

Contains information for a flat, non-hierarchical code system.

Some code systems are groupers: they assign a code to a category drawn from a small, flat label set. CCSR, the AHRQ chronic condition indicators, and the ICD chapter/block systems are all of this kind. They have no code/parent_code ontology file on PyHealth’s resource server, so they cannot be InnerMap subclasses – there is no graph to build.

FlatMap supplies exactly the surface that CrossMap requires of a vocabulary – standardize() and convert() – and nothing more. It never touches the network.

Because the graph-backed methods of InnerMap (lookup, get_ancestors, get_descendants, stat) have no meaning without an ontology, they are deliberately absent and raise AttributeError.

Examples

>>> from pyhealth.medcode import FlatMap
>>> ccsr = FlatMap.load("CCSR")
>>> ccsr.vocabulary
'CCSR'
>>> ccsr.standardize("CIR019")
'CIR019'

Each grouper normalizes its own codespace, so upstream quirks do not leak into the returned codes:

>>> FlatMap.load("ICD10BLOCK").standardize(
...     "I30-I5A | Other forms of heart disease"
... )
'I30-I5A'
>>> FlatMap.load("CCI").standardize(True)
'1'

classmethod load(vocabulary, refresh_cache=False)[source]#

Initializes a flat code system by name.

Parameters:

vocabulary (str) – the name of the code system, e.g. "CCSR".
refresh_cache (bool) – accepted and ignored.

Return type:

FlatMap

Returns:

The vocabulary instance.

Examples

>>> from pyhealth.medcode import FlatMap
>>> chapters = FlatMap.load("ICD10CHAPTER")
>>> chapters.vocabulary
'ICD10CHAPTER'

static standardize(code)[source]#

Standardizes a code. Grouper codes are already canonical.

Return type:: str

static convert(code, **kwargs)[source]#

Converts a code. Grouper codes have no alternate representations.

Return type:: str

class pyhealth.medcode.CCSR(**kwargs)[source]#

Bases: FlatMap

Clinical Classifications Software Refined, for ICD-10-CM.

AHRQ’s successor to CCS: 530 categories, ICD-10-CM only. Codes look like "CIR019" – a body-system prefix plus an index.

Examples

>>> from pyhealth.medcode import CrossMap
>>> ccsr = CrossMap.load("ICD10CM", "CCSR")
>>> ccsr.map("I50.9")          # heart failure
['CIR019']
>>> ccsr.map("E11.9")          # type 2 diabetes
['END002']
>>> ccsr.map("J18.9")          # pneumonia
['RSP002']
>>> ccsr.map("N17.9")          # acute kidney failure
['GEN002']

static convert(code, **kwargs)#

Converts a code. Grouper codes have no alternate representations.

Return type:: str

classmethod load(vocabulary, refresh_cache=False)#

Initializes a flat code system by name.

Parameters:

vocabulary (str) – the name of the code system, e.g. "CCSR".
refresh_cache (bool) – accepted and ignored.

Return type:

FlatMap

Returns:

The vocabulary instance.

Examples

>>> from pyhealth.medcode import FlatMap
>>> chapters = FlatMap.load("ICD10CHAPTER")
>>> chapters.vocabulary
'ICD10CHAPTER'

static standardize(code)#

Standardizes a code. Grouper codes are already canonical.

Return type:: str

class pyhealth.medcode.CCI(**kwargs)[source]#

Bases: FlatMap

Chronic Condition Indicator, for ICD-9-CM.

A binary flag: is this diagnosis a chronic condition? The upstream package returns a Python bool; PyHealth normalizes it to "1" or "0" so that the vocabulary behaves like every other code system.

Examples

>>> from pyhealth.medcode import CrossMap
>>> cci = CrossMap.load("ICD9CM", "CCI")
>>> cci.map("428.0")           # heart failure is chronic
['1']
>>> cci.map("250.00")          # so is diabetes
['1']
>>> cci.map("486")             # pneumonia is not
['0']

static standardize(code)[source]#

Standardizes a CCI indicator to "1" or "0".

Return type:: str

static convert(code, **kwargs)#

Converts a code. Grouper codes have no alternate representations.

Return type:: str

classmethod load(vocabulary, refresh_cache=False)#

Initializes a flat code system by name.

Parameters:

vocabulary (str) – the name of the code system, e.g. "CCSR".
refresh_cache (bool) – accepted and ignored.

Return type:

FlatMap

Returns:

The vocabulary instance.

Examples

>>> from pyhealth.medcode import FlatMap
>>> chapters = FlatMap.load("ICD10CHAPTER")
>>> chapters.vocabulary
'ICD10CHAPTER'

class pyhealth.medcode.CCIR(**kwargs)[source]#

Bases: FlatMap

Chronic Condition Indicator Refined, for ICD-10-CM.

The ICD-10 counterpart of CCI, normalized the same way.

Examples

>>> from pyhealth.medcode import CrossMap
>>> ccir = CrossMap.load("ICD10CM", "CCIR")
>>> ccir.map("I50.9")          # heart failure is chronic
['1']
>>> ccir.map("S72.001A")       # a femur fracture is acute
['0']

static standardize(code)[source]#

Standardizes a CCIR indicator to "1" or "0".

Return type:: str

static convert(code, **kwargs)#

Converts a code. Grouper codes have no alternate representations.

Return type:: str

classmethod load(vocabulary, refresh_cache=False)#

Initializes a flat code system by name.

Parameters:

vocabulary (str) – the name of the code system, e.g. "CCSR".
refresh_cache (bool) – accepted and ignored.

Return type:

FlatMap

Returns:

The vocabulary instance.

Examples

>>> from pyhealth.medcode import FlatMap
>>> chapters = FlatMap.load("ICD10CHAPTER")
>>> chapters.vocabulary
'ICD10CHAPTER'

class pyhealth.medcode.ICD9CHAPTER(**kwargs)[source]#

Bases: FlatMap

Chapters of ICD-9-CM: 19 top-level groupings, numbered "1"-"19".

Kept separate from ICD10CHAPTER because the two chapter systems are different codespaces despite the shared name.

Examples

>>> from pyhealth.medcode import CrossMap
>>> chapters = CrossMap.load("ICD9CM", "ICD9CHAPTER")
>>> chapters.map("428.0")      # 7 = circulatory system
['7']
>>> chapters.map("038.9")      # 1 = infectious and parasitic
['1']
>>> chapters.map("800.0")      # 17 = injury and poisoning
['17']

static convert(code, **kwargs)#

Converts a code. Grouper codes have no alternate representations.

Return type:: str

classmethod load(vocabulary, refresh_cache=False)#

Initializes a flat code system by name.

Parameters:

vocabulary (str) – the name of the code system, e.g. "CCSR".
refresh_cache (bool) – accepted and ignored.

Return type:

FlatMap

Returns:

The vocabulary instance.

Examples

>>> from pyhealth.medcode import FlatMap
>>> chapters = FlatMap.load("ICD10CHAPTER")
>>> chapters.vocabulary
'ICD10CHAPTER'

static standardize(code)#

Standardizes a code. Grouper codes are already canonical.

Return type:: str

class pyhealth.medcode.ICD10CHAPTER(**kwargs)[source]#

Bases: FlatMap

Chapters of ICD-10-CM: 22 top-level groupings, keyed by code range.

The upstream package returns "I00-I99 | Diseases of the circulatory system". PyHealth keeps the range ("I00-I99") as the code, since the description is a label rather than an identifier.

Examples

>>> from pyhealth.medcode import CrossMap
>>> chapters = CrossMap.load("ICD10CM", "ICD10CHAPTER")
>>> chapters.map("I50.9")      # circulatory system
['I00-I99']
>>> chapters.map("E11.9")      # endocrine, nutritional, metabolic
['E00-E89']
>>> chapters.map("A41.9")      # infectious and parasitic
['A00-B99']

static standardize(code)[source]#

Reduces an ICD-10 chapter value to its code range.

Return type:: str

static convert(code, **kwargs)#

Converts a code. Grouper codes have no alternate representations.

Return type:: str

classmethod load(vocabulary, refresh_cache=False)#

Initializes a flat code system by name.

Parameters:

vocabulary (str) – the name of the code system, e.g. "CCSR".
refresh_cache (bool) – accepted and ignored.

Return type:

FlatMap

Returns:

The vocabulary instance.

Examples

>>> from pyhealth.medcode import FlatMap
>>> chapters = FlatMap.load("ICD10CHAPTER")
>>> chapters.vocabulary
'ICD10CHAPTER'

class pyhealth.medcode.ICD10BLOCK(**kwargs)[source]#

Bases: FlatMap

Blocks of ICD-10-CM: 226 groupings nested inside chapters.

Normalized the same way as ICD10CHAPTER.

Examples

>>> from pyhealth.medcode import CrossMap
>>> blocks = CrossMap.load("ICD10CM", "ICD10BLOCK")
>>> blocks.map("I50.9")        # other forms of heart disease
['I30-I5A']
>>> blocks.map("E11.9")        # diabetes mellitus
['E08-E13']
>>> blocks.map("A41.9")        # other bacterial diseases
['A30-A49']

static standardize(code)[source]#

Reduces an ICD-10 block value to its code range.

Return type:: str

static convert(code, **kwargs)#

Converts a code. Grouper codes have no alternate representations.

Return type:: str

classmethod load(vocabulary, refresh_cache=False)#

Initializes a flat code system by name.

Parameters:

vocabulary (str) – the name of the code system, e.g. "CCSR".
refresh_cache (bool) – accepted and ignored.

Return type:

FlatMap

Returns:

The vocabulary instance.

Examples

>>> from pyhealth.medcode import FlatMap
>>> chapters = FlatMap.load("ICD10CHAPTER")
>>> chapters.vocabulary
'ICD10CHAPTER'

class pyhealth.medcode.CCC(**kwargs)[source]#

Bases: FlatMap

Pediatric Complex Chronic Condition category.

Sparse by design: most diagnoses are not complex chronic conditions and map to no category at all, which surfaces as an empty list.

Examples

>>> from pyhealth.medcode import CrossMap
>>> ccc = CrossMap.load("ICD10CM", "CCC")
>>> ccc.map("I50.9")           # cardiovascular
['cvd']
>>> ccc.map("J18.9")           # pneumonia: not a complex chronic
[]

static standardize(code)[source]#

Standardizes a CCC category by trimming surrounding whitespace.

Return type:: str

static convert(code, **kwargs)#

Converts a code. Grouper codes have no alternate representations.

Return type:: str

classmethod load(vocabulary, refresh_cache=False)#

Initializes a flat code system by name.

Parameters:

vocabulary (str) – the name of the code system, e.g. "CCSR".
refresh_cache (bool) – accepted and ignored.

Return type:

FlatMap

Returns:

The vocabulary instance.

Examples

>>> from pyhealth.medcode import FlatMap
>>> chapters = FlatMap.load("ICD10CHAPTER")
>>> chapters.vocabulary
'ICD10CHAPTER'

class pyhealth.medcode.CCCSUB(**kwargs)[source]#

Bases: FlatMap

Pediatric Complex Chronic Condition subcategory.

The finer level beneath CCC. Upstream values carry trailing whitespace, which is trimmed here.

Examples

>>> from pyhealth.medcode import CrossMap
>>> sub_map = CrossMap.load("ICD10CM", "CCCSUB")
>>> sub_map.map("I50.9")
['Other Cardiovascular']
>>> sub_map.map("J18.9")
[]

static standardize(code)[source]#

Standardizes a CCC subcategory by trimming surrounding whitespace.

Return type:: str

static convert(code, **kwargs)#

Converts a code. Grouper codes have no alternate representations.

Return type:: str

classmethod load(vocabulary, refresh_cache=False)#

Initializes a flat code system by name.

Parameters:

vocabulary (str) – the name of the code system, e.g. "CCSR".
refresh_cache (bool) – accepted and ignored.

Return type:

FlatMap

Returns:

The vocabulary instance.

Examples

>>> from pyhealth.medcode import FlatMap
>>> chapters = FlatMap.load("ICD10CHAPTER")
>>> chapters.vocabulary
'ICD10CHAPTER'