Author: Anoop Shah
Date: 2026-06-24

# Converting and creating codelists

#### Anoop Shah

#### 2026-06-24

# Converting and creating codelists

This vignette describes a suggested method for creating and reviewing SNOMED CT codelists. Before using the code in this vignette, please follow the vignette ‘Using SNOMED dictionaries and codelists’ to download the NHS SNOMED distribution and create a R SNOMED dictionary. If you want to include inactive concept descriptions, ensure that the `active_only` option is set to FALSE when creating the SNOMED dictionary using `loadSNOMED`.

## Searching for and using inactive concepts in SNOMED CT

As SNOMED CT is maintained over time, some concepts are inactivated because they are duplicates, ambiguous or no longer used. Data in existing database may still be recorded using inactive concepts, so it is important that queries account for this.

Prior to using any codelist to perform a search in a healthcare database, it is important to use the NHS Digital query table (downloadable from NHS Digital TRUD - https://isd.digital.nhs.uk/trud/user/guest/group/0/home) to augment the codelist with inactive concepts. The Query Table contains ancestor - descendant relationships for inactive concepts which correspond to current locations in the SNOMED CT hierarchy. This allows appropriate inactive terms to be included as needed, as per your chosen provenance level.

The available provenance levels are:

- 0: subsumption is always true (i.e. the descendant is always a subtype of the ancestor)
- 1: subsumption is usually true (but there is a theoretical risk of false positives)
- 2: both ancestors and descendents are only approximately known
- 3: the original concept has at least two distinct meanings, so there is a risk of false positives

The NHS Digital history table contains mappings of inactive SNOMED CT concepts to new/current concepts.

Both the query table and the history table are automatically loaded using the loadSNOMED function if they are included in the folders specified when the function is called. The query table should have a name containing “SNOMEDQueryTable” and the history table should have a name containing “HistorySubstitutionTable_Concepts”.

    library(Rdiagnosislist)
    require(data.table)

    # Use one thread only for CRAN
    data.table::setDTthreads(threads = 1)

    SNOMED <- sampleSNOMED()

    # Create a codelist for right heart failure
    rhf <- SNOMEDcodelist('Right heart failure', include_desc = TRUE)

    ## Converting 1 concept(s) to a codelist

    addInactiveConcepts(rhf)

    ## Key: <conceptId>
    ##             conceptId
    ##       <SNOMEDconcept>
    ##  1:          10335000
    ##  2:          13839000
    ##  3:          44313006
    ##  4:          49584005
    ##  5:          61783007
    ##  6:          66989003
    ##  7:          67189007
    ##  8:          78862003
    ##  9:          79955004
    ## 10:          80479009
    ## 11:          83291003
    ## 12:          87837008
    ## 13:          92506005
    ## 14:         128404006
    ## 15:         155323004
    ## 16:         155324005
    ## 17:         155325006
    ## 18:         155327003
    ## 19:         155330005
    ## 20:         194880009
    ## 21:         194881008
    ## 22:         194884000
    ## 23:         194885004
    ## 24:         194887007
    ## 25:         194889005
    ## 26:         195548008
    ## 27:         195549000
    ## 28:         233925005
    ## 29:         266233000
    ## 30:         274096000
    ## 31:         277639002
    ## 32:         286952009
    ## 33:         286953004
    ## 34:         359617009
    ## 35:         359620001
    ## 36:         367363000
    ## 37:         426012001
    ## 38:    23341000119109
    ## 39:   390771000000106
    ## 40:   425991000000100
    ## 41:   608451000000100
    ## 42:   639401000000103
    ## 43:   653021000000102
    ## 44:   673641000000101
    ## 45:   684231000000104
    ## 46:   689201000000109
    ## 47:   834741000000101
    ## 48: 15964701000119109
    ## 49: 16838951000119100
    ##             conceptId
    ##       <SNOMEDconcept>
    ##                                                                                          term
    ##                                                                                        <char>
    ##  1:                                              Chronic right-sided heart failure (disorder)
    ##  2:                                                            Bernheim's syndrome (disorder)
    ##  3:                            Right heart failure secondary to left heart failure (disorder)
    ##  4:                                                            Acute cor pulmonale (disorder)
    ##  5:                                                                                      <NA>
    ##  6:                                   Chronic right-sided congestive heart failure (disorder)
    ##  7:                                                  Acute pulmonary heart disease (disorder)
    ##  8:                                                              Ayerza's syndrome (disorder)
    ##  9:                                                          Chronic cor pulmonale (disorder)
    ## 10:                                     Acute right-sided congestive heart failure (disorder)
    ## 11:                                                                  Cor pulmonale (disorder)
    ## 12:                                                Chronic pulmonary heart disease (disorder)
    ## 13:                                         Biventricular congestive heart failure (disorder)
    ## 14:                                                            Right heart failure (disorder)
    ## 15:                                                                                      <NA>
    ## 16:                                                                                      <NA>
    ## 17:                                                                                      <NA>
    ## 18:                                                                                      <NA>
    ## 19:                                                                                      <NA>
    ## 20:                                                                                      <NA>
    ## 21:                                                                                      <NA>
    ## 22:                                                                                      <NA>
    ## 23:                                                                                      <NA>
    ## 24:                                                                                      <NA>
    ## 25:                                                                                      <NA>
    ## 26:                                                                                      <NA>
    ## 27:                                                                                      <NA>
    ## 28:                                                                                      <NA>
    ## 29:                                                                                      <NA>
    ## 30:                                                                                      <NA>
    ## 31:                                    Sepsis-associated right ventricular failure (disorder)
    ## 32:                                                                                      <NA>
    ## 33:                                                                                      <NA>
    ## 34:                                                Acute right-sided heart failure (disorder)
    ## 35:                                                      Acute right heart failure (disorder)
    ## 36:                                                      Right ventricular failure (disorder)
    ## 37:                              Right heart failure due to pulmonary hypertension (disorder)
    ## 38:                              Congestive heart failure with right heart failure (disorder)
    ## 39:                                                                                      <NA>
    ## 40:                                                                                      <NA>
    ## 41:                                                                                      <NA>
    ## 42:                                                                                      <NA>
    ## 43:                                                                                      <NA>
    ## 44:                                                                                      <NA>
    ## 45:                                                                                      <NA>
    ## 46:                                                                                      <NA>
    ## 47:                                                                                      <NA>
    ## 48: Acute cor pulmonale co-occurrent and due to saddle embolus of pulmonary artery (disorder)
    ## 49:                          Acute on chronic right-sided congestive heart failure (disorder)
    ##                                                                                          term
    ##                                                                                        <char>

## Creating SNOMED CT codelists from scratch

A suggested process is:

- Browse the SNOMED CT terminology to find ancestor terms that may be relevant.
- Create a putative codelist using the ancestor terms and their descendants.
- Export the codelist to HTML for clinical review. Reviewers can export/save the results of their review using the functions on the HTML document.
- Import the reviewed codelist, and use the as.SNOMEDcodelist function to convert it into a parsimonious form for curation.

When using the data for querying, the process is:

- Convert the codelist to the ‘simple’ format (i.e. enumerating all terms).
- Add inactive terms using the Query table, as above.

## Converting Read codelists to SNOMED CT

A suggested process is:

- Map Read terms to SNOMED CT using the NHS Digital mapping.
- Export the codelist to HTML for clinical review. Reviewers can export/save the results of their review using the functions on the HTML document.
- Import the reviewed codelist, and use the as.SNOMEDcodelist function to convert it into a parsimonious form for curation.

Example code:

    oldReadCodelist <- fread('
    readcode|readterm
    G54z500|Valvular heart disease"
    G5yyC00|Diastolic dysfunction"
    G5y3100|Ventricular dilatation"
    ')

    # Get sample dictionaries
    data(READMAPS)
    SNOMED <- sampleSNOMED()

    # Create a mapping table for Read to SNOMED (from NHSD table in READMAPS)
    NHSD_READ_TO_SNOMED <- READMAPS[, list(readcode = unlist(read2_code)),
        by = conceptId]
    mapped <- SNOMEDcodelist(NHSD_READ_TO_SNOMED[oldReadCodelist, on = 'readcode']$conceptId,
        codelist_name = 'heart_dis_from_read', version = 0, author = 'Me', date = 'Feb 2022')

    ## Converting 3 concept(s) to a codelist

    # Export to HTML
    # htmlCodelistHierarchy(mapped, file = paste0(tempdir(), '/test.html'))

    # Command to open file in web browser (Linux only)
    # system(paste0('google-chrome ', tempdir(), '/test.html &'))

    # Reimport edited list
    importedlist <- fread('
    conceptId,term,include_desc,included,checked,comment
    368009,"Heart valve disorder (disorder)",FALSE,TRUE,FALSE,""
    3545003,"Diastolic dysfunction (finding)",FALSE,TRUE,FALSE,""
    6210001,"Dilatation of cardiac ventricle (disorder)",FALSE,TRUE,FALSE,""
    418304008,"Diastolic heart failure (disorder)",FALSE,FALSE,FALSE,""
    441530006,"Chronic diastolic heart failure (disorder)",FALSE,FALSE,FALSE,""
    443343001,"Acute diastolic heart failure (disorder)",FALSE,FALSE,FALSE,""
    443344007,"Acute on chronic diastolic heart failure (disorder)",FALSE,FALSE,FALSE,""
    153931000119109,"Acute combined systolic and diastolic heart failure (disorder)",FALSE,FALSE,FALSE,""
    153951000119103,"Acute on chronic combined systolic and diastolic heart failure (disorder)",FALSE,FALSE,FALSE,""
    153941000119100,"Chronic combined systolic and diastolic heart failure (disorder)",FALSE,FALSE,FALSE,""
    120891000119109,"Diastolic heart failure stage C (disorder)",FALSE,FALSE,FALSE,""
    120881000119106,"Diastolic heart failure stage D (disorder)",FALSE,FALSE,FALSE,""
    ')

    # Convert to parsimonious (tree format) codelist
    treecodelist <- as.SNOMEDcodelist(importedlist, format = 'tree',
        codelist_name = 'heart_dis_from_read', version = 1, author = 'Me', date = 'Feb 2022')

## HTML codelist for this example

This HTML document presents a hierarchy of SNOMED CT concepts. In SNOMED CT, each concept has a distinct meaning and can be linked to more general terms (ancestors) and more specific terms (descendants). The buttons allow you to explore the codelist at different levels of the hierarchy, and mark whether or not you agree with the inclusion of individual concepts or concept hierarchies. When you have finished your review, you can download your final selection as a .CSV file by clicking the Export button below.

#### Key to buttons for each concept

- Show descendants of this concept
- Hide descendants of this concept
- Mark as unchecked
- Add a concept
- Remove a concept
- Add a concept and all descendants
- Remove a concept and all descendants

#### Reviewing tools

to .csv

Expand | SNOMED CT concept | Comment | Checked | Included |
--- | --- | --- | --- | --- | ---
| Diastolic dysfunction (finding) | … |  | Y |
| ·Diastolic heart failure (disorder) | … |  | N |
| · ·Acute diastolic heart failure (disorder) | … |  | N |
| · · ·Acute combined systolic and diastolic heart failure (disorder) | … |  | N |
| · · · · Acute on chronic combined systolic and diastolic heart failure (disorder) | … |  | N |
| · · · Acute on chronic diastolic heart failure (disorder) | … |  | N |
| · ·Chronic diastolic heart failure (disorder) | … |  | N |
| · · · Chronic combined systolic and diastolic heart failure (disorder) | … |  | N |
| · · ·Acute on chronic diastolic heart failure (disorder) | … |  | N |
| · · · · Acute on chronic combined systolic and diastolic heart failure (disorder) | … |  | N |
| · · Diastolic heart failure stage C (disorder) | … |  | N |
| · · Diastolic heart failure stage D (disorder) | … |  | N |
| Dilatation of cardiac ventricle (disorder) | … |  | Y |
| Heart valve disorder (disorder) | … |  | Y |

## More information

For more information about SNOMED CT, visit the SNOMED CT international website: https://www.snomed.org/

SNOMED CT (UK edition) can be downloaded from the NHS Digital site: https://isd.digital.nhs.uk/trud/user/guest/group/0/home

The NHS Digital terminology browser can be used to search for terms interactively: https://termbrowser.nhs.uk/