Skip to contents

SNOMED CT codes can become inactive and be replaced by new codes. GP records may still use the old codes, so a codelist that selects only one code of a pair may not count some usage. check_codelists() finds these pairs for review and shows their usage in English general practice.

Set up your codelists

The check uses the same layout as OpenSAFELY studies. List your codelists in codelists/codelists.txt, one OpenCodelists ID per line:

user/Lola_O/proms-dep/62e34278
user/Lola_O/proms-anx/0314a9a9

Then download the CSV files with the OpenSAFELY CLI:

opensafely codelists update

Only codelists with the SNOMED CT coding system are checked. Others, such as dm+d codelists, are skipped.

If a codelist has moved to a new owner on OpenCodelists, it is skipped and listed as not found. Update its ID in codelists.txt to the new one.

Read the codelists in R with read_codelists():

library(opencodecounts)

codelists <- read_codelists("codelists")

Where the code pairs come from

The old and new code pairs come from the SNOMED CT History Substitution Table on NHS TRUD (Technology Reference data Update Distribution), item 276. The package downloads a copy that keeps only pairs where the old or new code has GP usage. It is downloaded once and cached. Clear it with cache_clear().

Run the check in R

check <- check_codelists("codelists", start_date = "2020-08-01")
check

The report counts the codelists that select all linked codes with usage and lists those that do not:

── Codelist check ──────────────────────────────────────────────────────────────
SNOMED CT history version 0.1.0 (TRUD release uk_sctqths_43.1.0_20261021000001)
OpenCodeCounts SNOMED CT data version 0.2.0 from 01 Aug 2020 to 31 Jul 2026
ℹ 2 codelists do not select some linked codes with usage:

  Codelist               Selected codes             Linked codes not selected
  user-Lola_O-proms-anx  68 codes,  9,217,600 uses  2 codes,    13,220 uses,  0.1%
  user-Lola_O-proms-dep  50 codes, 16,400,990 uses  5 codes, 2,584,100 uses, 13.6%

Linked codes not selected and their share of each old and new pair:

  user-Lola_O-proms-anx
    836551000000102   old      7,180 uses   99.4% of pair  Generalised anxiety disorder 2 scale (assessment scale)
    836561000000104   old      6,040 uses   85.8% of pair  Assessment using generalised anxiety disorder 2 scale (procedure)

  user-Lola_O-proms-dep
    836541000000100   old  2,444,600 uses   87.0% of pair  Patient health questionnaire 2 score (observable entity)
    1104961000000104  old    114,220 uses  100.0% of pair  Patient Health Questionnaire-4 score (observable entity)
    1104941000000100  old     21,160 uses   99.6% of pair  Patient Health Questionnaire-4 (assessment scale)
    836521000000107   old      2,190 uses   99.5% of pair  Patient health questionnaire 2 (assessment scale)
    836531000000109   old      1,930 uses   82.8% of pair  Assessment using patient health questionnaire 2 (procedure)

The percentages show the share of usage that the linked codes not selected may account for, per codelist and per old and new pair. Pairs that TRUD flags as ambiguous, often a broad parent code such as “Ethnic group”, are left out of the report but kept in check@results. Review each code before adding it to a codelist.

Write all pairs to CSV:

readr::write_csv(check@results, "codelist-check.csv", na = "")

To check codelists on OpenCodelists without a codelists folder, use check_codelists_url():

check_codelists_url("https://www.opencodelists.org/codelist/user/example/phq-9/abc12345/")

Set data_version and history_version to make the results reproducible. The first two lines of the report show the versions used.

Run the check in the terminal

Install the opencodecounts command once with Rapp:

install.packages("Rapp")
Rapp::install_pkg_cli_apps("opencodecounts")

Then run the check from your study folder:

opencodecounts codelists check
opencodecounts codelists check --start-date 2020-08-01 --output codelist-check.csv

Use --output to save all old and new code pairs to a CSV file. It exits with status 1 when a codelist does not select a linked code with recorded usage, so you can use it in continuous integration. The command uses your installed package, so reinstall the package to update it. Run opencodecounts codelists check --help for all options.