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"))

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)[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).

classmethod load(source_vocabulary, target_vocabulary, refresh_cache=False)[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.

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']

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.