Learn R Programming

CodelistGenerator

Installation

You can install CodelistGenerator from CRAN

install.packages("CodelistGenerator")

Or you can also install the development version of CodelistGenerator

install.packages("remotes")
remotes::install_github("darwin-eu/CodelistGenerator")

Example usage

library(dplyr)
library(CDMConnector)
library(CodelistGenerator)

For this example we’ll use the Eunomia dataset (which only contains a subset of the OMOP CDM vocabularies)

requireEunomia()
db <- DBI::dbConnect(duckdb::duckdb(), dbdir = eunomiaDir())
cdm <- cdmFromCon(db, 
                  cdmSchema = "main", 
                  writeSchema = "main", 
                  writePrefix = "cg_")

Exploring the OMOP CDM Vocabulary tables

OMOP CDM vocabularies are frequently updated, and we can identify the version of the vocabulary of our Eunomia data

getVocabVersion(cdm = cdm)
#> [1] "v5.0 18-JAN-19"

Vocabulary based codelists using CodelistGenerator

CodelistGenerator provides functions to extract code lists based on vocabulary hierarchies. One example is `getDrugIngredientCodes, which we can use, for example, to get the concept IDs used to represent aspirin and diclofenac.

ing <- getDrugIngredientCodes(cdm = cdm, 
                       name = c("aspirin", "diclofenac"),
                       nameStyle = "{concept_name}")
ing
#> 
#> - aspirin (2 codes)
#> - diclofenac (1 codes)
ing$aspirin
#> [1] 19059056  1112807
ing$diclofenac
#> [1] 1124300

Systematic search using CodelistGenerator

CodelistGenerator can also support systematic searches of the vocabulary tables to support codelist development. A little like the process for a systematic review, the idea is that for a specified search strategy, CodelistGenerator will identify a set of concepts that may be relevant, with these then being screened to remove any irrelevant codes by clinical experts.

We can do a simple search for asthma

asthma_codes1 <- getCandidateCodes(
  cdm = cdm,
  keywords = "asthma",
  domains = "Condition"
) 
asthma_codes1 |> 
  glimpse()
#> Rows: 2
#> Columns: 6
#> $ concept_id       <int> 4051466, 317009
#> $ found_from       <chr> "From initial search", "From initial search"
#> $ concept_name     <chr> "Childhood asthma", "Asthma"
#> $ domain_id        <chr> "Condition", "Condition"
#> $ vocabulary_id    <chr> "SNOMED", "SNOMED"
#> $ standard_concept <chr> "S", "S"

But perhaps we want to exclude certain concepts as part of the search strategy, in this case we can add these like so

asthma_codes2 <- getCandidateCodes(
  cdm = cdm,
  keywords = "asthma",
  exclude = "childhood",
  domains = "Condition"
) 
asthma_codes2 |> 
  glimpse()
#> Rows: 1
#> Columns: 6
#> $ concept_id       <int> 317009
#> $ found_from       <chr> "From initial search"
#> $ concept_name     <chr> "Asthma"
#> $ domain_id        <chr> "Condition"
#> $ vocabulary_id    <chr> "SNOMED"
#> $ standard_concept <chr> "S"

Summarising code use

As well as functions for finding codes, we also have functions to summarise their use. Here for

library(flextable)
asthma_code_use <- summariseCodeUse(list("asthma" = asthma_codes1$concept_id),
  cdm = cdm
)
tableCodeUse(asthma_code_use, type = "flextable")

Copy Link

Version

Install

install.packages('CodelistGenerator')

Monthly Downloads

1,774

Version

3.5.0

License

Apache License (>= 2)

Maintainer

Edward Burn

Last Published

April 10th, 2025

Functions in CodelistGenerator (3.5.0)

doseFormDoc

Helper for consistent documentation of doseForm.
getATCCodes

Get the descendant codes of Anatomical Therapeutic Chemical (ATC) classification codes
codesFromConceptSet

Get concept ids from JSON files containing concept sets
codesFromCohort

Get concept ids from JSON files containing cohort definitions
.optionsDoc

Helper for consistent documentation of .options.
getMappings

Show mappings from non-standard vocabularies to standard.
getRelationshipId

Get available relationships between concepts
minimumCountDoc

Helper for consistent documentation of minimumCount.
getDomains

Get the domains available in the cdm
getDescendants

Get descendant codes for a given concept
getVocabularies

Get the vocabularies available in the cdm
mockVocabRef

Generate example vocabulary database
getDoseUnit

Get available dose units
keepOriginalDoc

Helper for consistent documentation of keepOriginal.
ingredientRangeDoc

Helper for consistent documentation of ingredientRange.
groupColumnDoc

Helper for consistent documentation of groupColumn.
subsetOnDomain

Subset a codelist to only those codes from a particular domain.
getDrugIngredientCodes

Get descendant codes of drug ingredients
getRouteCategories

Get available drug routes
getVocabVersion

Get the version of the vocabulary used in the cdm
getICD10StandardCodes

Get corresponding standard codes for International Classification of Diseases (ICD) 10 codes
summariseAchillesCodeUse

Summarise code use from achilles counts.
subsetOnRouteCategory

Subset a codelist to only those with a particular route category
subsetToCodesInUse

Filter a codelist to keep only the codes being used in patient records
subsetOnDoseUnit

Subset a codelist to only those with a particular dose unit.
headerStrataDoc

Helper for consistent documentation of header.
hideDoc

Helper for consistent documentation of hide.
levelICD10Doc

Helper for consistent documentation of level.
levelATCDoc

Helper for consistent documentation of level.
tableUnmappedCodes

Format the result of summariseUnmappedCodeUse into a table
typeBroadDoc

Helper for consistent documentation of type.
tableOrphanCodes

Format the result of summariseOrphanCodes into a table
tableDoc

Helper for consistent documentation of table.
summariseUnmappedCodes

Find unmapped concepts related to codelist
summariseCodeUse

Summarise code use in patient-level data.
tableAchillesCodeUse

Format the result of summariseAchillesCodeUse into a table
compareCodelists

Compare overlap between two sets of codes
getCandidateCodes

Generate a candidate codelist
typeNarrowDoc

Helper for consistent documentation of type.
codesInUse

Get the concepts being used in patient records
getConceptClassId

Get the concept classes used in a given set of domains
nameStyleDoc

Helper for consistent documentation of nameStyle.
typeTableDoc

Helper for consistent documentation of type.
hideStrataDoc

Helper for consistent documentation of hide.
summariseOrphanCodes

Find orphan codes related to a codelist using achilles counts and, if available, PHOEBE concept recommendations
stratifyByConcept

Stratify a codelist by the concepts included within it.
summariseCohortCodeUse

Summarise code use among a cohort in the cdm reference
reexports

Objects exported from other packages
stratifyByDoseUnit

Stratify a codelist by dose unit.
sourceCodesInUse

Get the source codes being used in patient records
standardConceptDoc

Helper for consistent documentation of standardConcept.
routeCategoryDoc

Helper for consistent documentation of routeCategory.
headerDoc

Helper for consistent documentation of header.
groupColumnStrataDoc

Helper for consistent documentation of groupColumn.
stratifyByRouteCategory

Stratify a codelist by route category.
tableCohortCodeUse

Format the result of summariseCohortCodeUse into a table.
tableCodeUse

Format the result of summariseCodeUse into a table.
xDoc

Helper for consistent documentation of x.
includeDescendantsDoc

Helper for consistent documentation of includeDescendants.
byConceptDoc

Helper for consistent documentation of byConcept.
availableATC

Get the names of all available Anatomical Therapeutic Chemical (ATC) classification codes
availableIngredients

Get the names of all available drug ingredients
availableICD10

Get the names of all International Classification of Diseases (ICD) 10 codes
buildAchillesTables

Add the achilles tables with specified analyses
byYearDoc

Helper for consistent documentation of byYear.
ageGroupDoc

Helper for consistent documentation of ageGroup.
bySexDoc

Helper for consistent documentation of bySex.
CodelistGenerator-package

CodelistGenerator: Identify Relevant Clinical Codes and Evaluate Their Use
cdmDoc

Helper for consistent documentation of cdm.
domainDoc

Helper for consistent documentation of domain.
countByDoc

Helper for consistent documentation of countBy.
doseUnitDoc

Helper for consistent documentation of doseUnit.
getDoseForm

Get the dose forms available for drug concepts