Coding
“Coding” is a key concept used throughout highdicom. By “coding”, we are referring to the use of standardized nomenclatures or terminologies to describe medical (or related) concepts. For example, instead of using the English word “liver” (or a word in another human language) to describe the liver, we instead use a code such as ‘10200004’ from the SNOMED-CT nomenclature to describe the liver in standardized way. Use of coding is vital to ensure that these concepts are expressed unambiguously within DICOM files. Coding is especially fundamental within structured reporting, but is also found in other places around the DICOM standard and, in turn, highdicom.
To communicate a concept in DICOM using a coding scheme, three elements are necessary:
A coding scheme: an identifier of the pre-defined terminology used to define the concept.
A code value: the code value conveys a unique identifier for the specific concept. It is often a number or alphanumeric string that may not have any inherent meaning outside of the terminology.
A code meaning. The code meaning conveys the concept in a way that is understandable to humans.
Any coding scheme that operates in this way may be used within DICOM objects, including ones that you create yourself. However, it is highly recommended to use a well-known and widely accepted standard terminology to ensure that your DICOM objects will be as widely understood and as interoperable as possible. Examples of widely used medical terminologies include:
The DCM terminology. This terminology is defined within the DICOM standard itself and is used to refer to DICOM concepts, as well as other concepts within the radiology workflow.
SNOMED-CT. This terminology contains codes to describe medical concepts including anatomy, diseases, and procedures.
RadLex. A standardized terminology for concepts in radiology.
UCUM. A terminology specifically to describe units of measurement.
See this page for a list of terminologies used within DICOM.
Highdicom defines the highdicom.sr.CodedConcept class to encapsulate
a coded concept. To create a highdicom.sr.CodedConcept, you pass
values for the coding scheme, code value, and code meaning. For example, to
describe a tumor using the SNOMED-CT terminology, you could do this:
import highdicom as hd
tumor_code = hd.sr.CodedConcept(
value="108369006",
scheme_designator="SCT",
meaning="Tumor"
)
Codes within Pydicom
The pydicom library, upon which highdicom is built, has its own class
pydicom.sr.coding.Code that captures coded concepts in the same way that
highdicom.sr.CodedConcept does. The reason for the difference is that
the highdicom class is a sub-class of pydicom.Dataset with the relevant
attributes such that it can be included directly into a DICOM object. pydicom
also includes within it values for a large number of coded concepts within
the DCM, SNOMED-CT, and UCUM terminologies. For example, instead of manually
creating the “tumor” concept above, we could have just used the pre-defined
value in pydicom:
from pydicom.sr.codedict import codes
tumor_code = codes.SCT.Tumor
print(tumor_code.value)
# '108369006'
print(tumor_code.scheme_designator)
# 'SCT'
print(tumor_code.meaning)
# 'tumor'
Here are some other examples of codes within pydicom:
from pydicom.sr.codedict import codes
# A patient, as described by the DCM terminology
patient_code = codes.DCM.Patient
print(patient_code)
# Code(value='121025', scheme_designator='DCM', meaning='Patient', scheme_version=None)
# A centimeter, a described by the UCUM coding scheme
cm_code = codes.UCUM.cm
print(cm_code)
# Code(value='cm', scheme_designator='UCUM', meaning='cm', scheme_version=None)
The two classes can be used interoperably throughout highdicom: anywhere in the
highdicom API that you can pass a highdicom.sr.CodedConcept, you
can pass an pydicom.sr.coding.Code instead and it will be converted behind
the scenes for you. Furthermore, equality is defined between the two classes
such that it evaluates to true if they represent the same concept, and they
hash to the same value if you use them within sets or as keys in dictionaries.
import highdicom as hd
from pydicom.sr.codedict import codes
tumor_code_hd = hd.sr.CodedConcept(
value="108369006",
scheme_designator="SCT",
meaning="Tumor"
)
tumor_code = codes.SCT.Tumor
assert tumor_code_hd == tumor_code
assert len({tumor_code_hd, tumor_code}) == 1
For equality and hashing, two codes are considered equivalent if they have the same coding scheme, and value, regardless of how their meaning is represented.
Context Groups
Many places where codes are used in the standard are associated with a Context Group. These are sets of codes determined to be suitable for a particular purpose. Most are extensible, meaning you can choose codes outside the context group if you wish. However, it is best practice to use a code within the context group if a suitable code exists within it.
Context groups are have an identifier called a CID. For example, CID 7150 is the context group containing codes to use to describe segmented properties categories in a DICOM segmentation and CID 7151 contains values for the more specific segmented property types. Note that this second example includes other CIDs recursively.
Finding Suitable Codes
The pydicom code dictionary allows searching for concepts via simple string matching. You can also search with context groups.
from pydicom.sr.codedict import codes
print(codes.SCT.dir('liver'))
# ['DeliveredRadiationDose',
# 'HistoryOfPrematureDelivery',
# 'Liver',
# 'LiverStructure']
print(codes.SCT.Liver)
# Code(value='10200004', scheme_designator='SCT', meaning='Liver', scheme_version=None)
# Search within a context group (e.g. CID7150)
print(codes.cid7150.dir())
# ['AnatomicalStructure',
# 'BodySubstance',
# 'Function',
# 'MorphologicallyAbnormalStructure',
# 'PhysicalObject',
# 'SpatialAndRelationalConcept',
# 'Substance',
# 'Tissue']
# Check whether a code lies within a context group
print(codes.SCT.BodySubstance in codes.cid7150)
# True
However, for more advanced searching it is generally advisable to search the documentation for the coding scheme itself. This webpage is a nice interactive tool for searching the terms and Context Groups defined within DICOM.
UCUM
UCUM works a little differently to the other coding schemes discussed here. Rather than a finite set of codes, it defines codes for a set of fundamental units and a syntax for combining them to give derived units (e.g. “mm/s” for millimeters per second), meaning there are potentially infinite codes. Pydicom defines a list of the most common units, but this will not cover every use case.
We recommend this page, a useful validator for checking UCUM syntax.
Codes With Modifiers
Some attributes in DICOM allow a code to be accompanied by one or more modifier codes that refine the meaning of the root code. A typical example is laterality: rather than needing a separate code for “left kidney” and “right kidney”, you can use the single code for “kidney” together with the modifier “left” or “right”. The codes used as modifiers are generally drawn from CID 2 “Anatomic Modifier”.
In the DICOM standard, each place where modifiers are allowed has its own
sequence attribute for holding them (for example “Segmented Property Type
Modifier Code Sequence” next to “Segmented Property Type Code Sequence”).
Highdicom provides a class for each such attribute. They are all
sub-classes of highdicom.sr.CodedConcept, and are constructed from a
root code and an optional sequence of modifier codes (either
pydicom.sr.coding.Code or highdicom.sr.CodedConcept objects):
Class |
Describes |
Used in |
|---|---|---|
The property that a segment represents (CID 7151) |
|
|
The property that an annotation group represents (CID 8135) |
|
|
The anatomic region into which an object falls (e.g. CID 4) |
|
|
The anatomic structure that an object represents |
|
Each class stores its modifiers in the attribute with the corresponding
standard name, so that the object can be placed directly into a DICOM dataset.
The classes are not interchangeable: for example an
highdicom.AnatomicRegion cannot be used where a
highdicom.seg.SegmentedPropertyType is expected, and doing so raises a
TypeError.
To create an instance of one of these classes, pass a
pydicom.sr.coding.Code or highdicom.sr.CodedConcept to serve as
the root concept, then optionally a list of further codes to the modifiers
parameter.
import highdicom as hd
from pydicom.sr.codedict import codes
# A segmented property type of "Kidney", modified by "Left"
left_kidney = hd.seg.SegmentedPropertyType(
codes.SCT.Kidney,
modifiers=[codes.SCT.Left],
)
# The value, meaning, and scheme_designator properties behave as they do
# for a plain CodedConcept
print(left_kidney.scheme_designator, left_kidney.value, left_kidney.meaning)
# SCT 64033007 Kidney
# Access the modifiers using the modifiers property (this is the same for
# every one of the classes above)
print([m.meaning for m in left_kidney.modifiers])
# ['Left']
# Access the root code on its own, without the modifiers
assert left_kidney.unmodified == codes.SCT.Kidney
Two modified codes are equal if they have the same root code and the same set
of modifiers. The order of the modifiers is not significant, and the class of
the modified code (e.g. highdicom.seg.SegmentedPropertyType or
highdicom.AnatomicRegion) is not considered. The hash is consistent
with this definition, so these objects may be used in sets and as dictionary
keys.
a = hd.seg.SegmentedPropertyType(
codes.SCT.Kidney,
modifiers=[codes.SCT.Left, codes.SCT.Posterior],
)
b = hd.seg.SegmentedPropertyType(
codes.SCT.Kidney,
modifiers=[codes.SCT.Posterior, codes.SCT.Left],
)
assert a == b
assert len({a, b}) == 1
# Different modifiers means a different code
assert a != hd.seg.SegmentedPropertyType(codes.SCT.Kidney)
A modified code that has no modifiers is considered equal to the plain code,
but one that has modifiers does not. When you want to compare only the root
code regardless of modifiers, use the unmodified property or the
ignore_modifiers option of highdicom.sr.codes_equal():
assert hd.seg.SegmentedPropertyType(codes.SCT.Kidney) == codes.SCT.Kidney
assert a != codes.SCT.Kidney
assert a.unmodified == codes.SCT.Kidney
assert hd.sr.codes_equal(a, codes.SCT.Kidney, ignore_modifiers=True)
Gotcha: Comparing With pydicom.sr.coding.Code
The == operator is not symmetric when a code with modifiers is compared
with a pydicom.sr.coding.Code. When the Code is on the left, the
comparison is evaluated by pydicom, whose Code class knows nothing about
modifiers (and is not under the control of highdicom), so the modifiers are
silently ignored:
left_kidney = hd.seg.SegmentedPropertyType(
codes.SCT.Kidney,
modifiers=[codes.SCT.Left],
)
# The modifiers are considered: not equal
assert left_kidney != codes.SCT.Kidney
# The modifiers are not considered, since pydicom evaluates this: equal!
assert codes.SCT.Kidney == left_kidney
This also affects code that compares implicitly, such as code in
list_of_codes, list_of_codes.index(code) and the order of operands in an
assert expected == actual statement. Comparing two
highdicom.sr.CodedConcept objects (or objects of any of its
sub-classes) does not have this problem, because the operator of the
sub-class is always tried first.
To compare codes safely in every situation, use the function
highdicom.sr.codes_equal(). It gives the same result regardless of the
order of its arguments and of the types of its arguments, and treats a plain
Code as having no modifiers:
assert not hd.sr.codes_equal(left_kidney, codes.SCT.Kidney)
assert not hd.sr.codes_equal(codes.SCT.Kidney, left_kidney)
# Compare only the root codes, ignoring modifiers
assert hd.sr.codes_equal(
codes.SCT.Kidney,
left_kidney,
ignore_modifiers=True,
)
The behavior of the == operator for the possible combinations of types is
summarized below.
Expression |
Considers modifiers? |
|---|---|
|
Yes |
|
Yes |
|
No |
|
Yes (unless |
Coding Scheme Identification
Every code in a DICOM object carries only the designator of its coding scheme
(e.g. "SCT"), not a full definition of the scheme. For the schemes that are
listed within the DICOM standard itself (those on this page,
including "DCM", "SCT", "LN", "UCUM" and others), the
designator is enough for a reader to know exactly which terminology is meant.
It is valid to use other coding schemes, but then the designator may not be
understood by the recipient of the file. In this case, it is a best practice to
place information describing the scheme(s) used in the instance’s “Coding
Scheme Identification Sequence”. This sequence maps each designator used within
an instance to more information about the scheme, including the scheme’s full
name, its version, the organization responsible for it, a UID or external
registry identifier, and links to resources describing it.
In highdicom, each coding scheme may be described by an item of type
highdicom.coding_schemes.CodingSchemeIdentificationItem. Only the
designator is required, but you should provide as much additional
information as you can. Pass a sequence of such items to the coding_schemes
parameter of the constructor of highdicom.SOPClass, and they will be
placed into the Coding Scheme Identification Sequence of the new object. The
constructors of all IODs implemented in highdicom (such as the SR, Parametric
Map and Segmentation classes) accept a coding_schemes argument (via the
**kwargs argument, which forwards arguments to highdicom.SOPClass).
Below, we show two examples of this, one for publicly available coding schemes
listed in a public registry, the other for private codes that are only used
within a particular organization.
Publicly Registered Coding Scheme
For a scheme that is registered in an external registry, use the registry
parameter, and additionally specify either the uid of the scheme (if
it has an ISO 8824 object identifier compatible with the DICOM UI value
representation) or its identifier within the registry as external_id.
It is an error to give both, or neither, when registry is used:
hl7_scheme = CodingSchemeIdentificationItem(
designator="ICD10",
name="International Classification of Diseases, 10th Revision",
registry="HL7",
uid="2.16.840.1.113883.6.3",
)
Each designator used in the instance should be described by at most one item.
Private Codes
If no existing terminology contains the concept you need to describe, you may define your own “private” or “local” codes. Doing so should be a last resort, since other software will not be able to interpret them. Before creating private codes, look through the terminologies above (and the tools described in Finding Suitable Codes) for a suitable existing code. When you do need to create them:
Designator: the DICOM standard reserves coding scheme designators starting with
"99"for private use (e.g."99MYORG"). Choose a designator that is specific to your organization or project to avoid collisions with those of other users. The designator is a DICOM Short String, so it may be at most 16 characters long, and it must not contain backslashes or control characters.Value: any code value that is unique within your scheme, up to 16 characters. It need not be numeric.
Meaning: a human-readable description of the concept. Because receivers cannot look the code up elsewhere, make this clear and complete.
Version: if your scheme is likely to change over time, set
scheme_versionon the code so that its meaning is unambiguous.Identification: describe the scheme with a
highdicom.coding_schemes.CodingSchemeIdentificationItemas above, so that readers can discover who defines the scheme and where to find its documentation. The designator of every code used in the instance that is not from a standard terminology ("99MYORG"here) should have a matchingCodingSchemeIdentificationItemin thecoding_schemeslist.
Putting this together, the following creates a private code and an instance that uses it and describes its scheme. This example skips over most of the detail on how to create the Structured Report instance to focus on the use of the coding scheme. See Structured Report Documents (SRs) for a full explanation of SRs.
import highdicom as hd
from highdicom.coding_schemes import (
CodingSchemeIdentificationItem,
CodingSchemeResourceItem,
)
from highdicom.enum import CodingSchemeURLTypeValues
# An example coded concept using a private coding scheme. This can
# be used anywhere a CodedConcept may be passed
private_motion_artifact_code = hd.sr.CodedConcept(
value="FIND-0042",
scheme_designator="99MYORG",
meaning="Suspected motion artifact",
scheme_version="2.1",
)
# Define a CodingSchemeIdentificationItem that describes this private coding
# scheme, with the designator matching that used above
my_scheme = CodingSchemeIdentificationItem(
designator="99MYORG",
name="My Organization Findings Terminology",
version="2.1",
responsible_organization="My Organization, contact@example.com",
resources=[
CodingSchemeResourceItem(
url="https://example.com/terminology/v2.1/description.html",
url_type=CodingSchemeURLTypeValues.DOC,
),
CodingSchemeResourceItem(
url="https://example.com/terminology/v2.1/terms.csv",
url_type=CodingSchemeURLTypeValues.CSV,
),
],
)
# Pass the coding scheme to the constructor of any highdicom IOD, here a
# structured report as an example
instance = hd.sr.Comprehensive3DSR(
content=MeasurementReport(
imaging_measurements=[
hd.sr.MeasurementsAndQualitativeEvaluations(
...,
finding_type=private_motion_artifact_code,
)
],
...,
),
...,
coding_schemes=[my_scheme],
)