Importing SNOMED and LOINC

Bunsen supports querying data with arbitrary code systems, but includes specialized support for importing SNOMED and LOINC since they are prevalent in a number of FHIR-related use cases.

Users must load the reference data in order to use queries aware of LOINC, SNOMED, or other terminologies. Users are responsible for ensuring they have the appropriate licenses to use this content and downloading it from the given sources.

Obtaining LOINC

The LOINC Multiaxial Hierarchy is published at https://loinc.org/download/loinc-multiaxial-hierarchy/. It can be downloaded and extracted into the mappings root with the following structure. Bunsen can ingest the multiaxial hierarchy from the CSV file available in that download, such as:

/path/to/mappings/loinc_hierarchy/2.56/LOINC_2.56_MULTI-AXIAL_HIERARCHY.CSV

Obtaining SNOMED

SNOMED RF2 Files are published at https://www.nlm.nih.gov/healthit/snomedct/international.html. It can be downloaded and extracted into the mappings root with the following structure. Bunsen can ingest the relationship snapshot, such as:

/path/to/mappings/snomedct_rf2/20160901/Snapshot/Terminology/sct2_Relationship_Snapshot_US1000124_20160901.txt

Loading the Ontologies

Once the content is downloaded, users can import it with the following commands. See the with_loinc_hierarchy() and with_relationships() functions for details.

>>> from bunsen.mapping import get_empty
>>> from bunsen.mapping.loinc import with_loinc_hierarchy
>>> from bunsen.mapping.snomed import with_relationships
>>>
>>> # Add SNOMED ot the concept maps
>>> concept_maps = with_relationships(
>>>       spark,
>>>       get_empty(spark),
>>>       '/path/to/mappings/snomedct_rf2/20160901/Snapshot/Terminology/sct2_Relationship_Snapshot_US1000124_20160901.txt',
>>>       '20160901')
>>>
>>> # Add LOINC to the concept maps.
>>> concept_maps = with_loinc_hierarchy(
>>>        spark,
>>>        concept_maps,
>>>        '/path/to/mappings/loinc_hierarchy/2.56/LOINC_2.56_MULTI-AXIAL_HIERARCHY.CSV',
>>>       '2.56')
>>>
>>> # Write the SNOMED and LOINC data to the ontologies database, where it is visible
>>> # in Bunsen's valueset functions.
>>> concept_maps.write_to_database('ontologies')

FHIR ConceptMap APIs

Core library for working with Concept Maps in Bunsen. This class See the ConceptMaps class for details.

class bunsen.mapping.ConceptMaps(spark_session, jconcept_maps)

An immutable collection of FHIR Concept Maps to be used to map value sets and for ontologically-based queries.

add_mappings(url, version, mappings)

Returns a new ConceptMaps instance with the given mappings added to an existing map. The mappings parameter must be a list of tuples of the form [(source_system, source_value, target_system, target_value, equivalence)].

get_ancestors(uri=None, version=None)

Returns a dataset of all ancestors.

get_map_as_xml(url, version)

Returns an XML string containing the specified concept map.

get_mappings(uri=None, version=None)

Returns a dataset of all mappings.

get_maps()

Returns a dataset of FHIR ConceptMaps without the nested mapping content, allowing users to explore mapping metadata.

The mappings themselves are excluded because they can become quite large, so users should use the get_mappings method above to explore a table of them.

latest_version(uri)

Returns the latest version of a map, or None if there is none.”

with_new_map(url, version, source, target, experimental=True, mappings=[])

Returns a new ConceptMaps instance with the given map added. Callers may include a list of mappings tuples in the form of [(source_system, source_value, target_system, target_value, equivalence)].

write_to_database(database)

Writes the mapping content to the given database, creating a mappings and conceptmaps table if they don’t exist.

bunsen.mapping.get_default(spark_session)
bunsen.mapping.get_empty(spark_session)

Support for importing the LOINC Hierarchy into Bunsen.

bunsen.mapping.loinc.with_loinc_hierarchy(sparkSession, concept_maps, loinc_hierarchy_path, loinc_version)

Returns a concept maps instance that includes the LOINC hierarchy read from the given location.

Support for importing SNOMED relationship files into Bunsen.

bunsen.mapping.snomed.with_relationships(sparkSession, concept_maps, snomed_relationship_path, snomed_version)

Returns a concept maps instance that includes the SNOMED relationships read from the given location.