Types of Codelist

In this vignette we will introduce the three different types of codelist that CodelistGenerator uses: codelist, codelist with details, and concept set. First of all, we will upload the packages required for the demonstration.

library(omopgenerics, warn.conflicts = FALSE)
library(dplyr, warn.conflicts = FALSE)
library(CodelistGenerator)

Codelist

Codelist format is the simplest of the three formats. To create one, we just need a named list where each element contains a vector of concept IDs. You can see an example below on how to create one:

codelist <- list("codes1" = c(1L, 2L, 3L),
                 "codes2" = c(4L, 5L, 10L))
codelist <- newCodelist(codelist)

codelist

Notice that the codelist has two specific attributes, the name of the codelists that contains and the class:

attributes(codelist)

Create an empty codelist

We can create an empty codelist using omopGenerics package:

empty_codelist  <- emptyCodelist()

empty_codelist

Codelist with details

Codelist with details contains a tibble in each element. To create one, we need a named list where each element contains a tibble with at least the column concept_id.

codelist_with_details <- list("codes1" = tibble("concept_id" = c(1L, 2L, 3L)),
                              "codes2" = tibble("concept_id" = c(4L, 5L, 10L)))
codelist_with_details <- newCodelistWithDetails(codelist_with_details)

codelist_with_details

Notice that this allows us to add more information of each one of the codes:

codelist_with_details <- list(
  "codes1" = tibble("concept_id" = c(1L, 2L, 3L),
                    "concept_name" = c("Musculoskeletal disorder", "Osteoarthrosis", "Arthritis"),
                    "domain_id" = c("Condition", "Condition", "Condition"),
                    "vocabulary_id" = c("SNOMED","SNOMED","SNOMED"),
                    "standard_concept" = c("S","S","S")),
  "codes2" = tibble("concept_id" = c(4L, 5L, 10L),
                    "concept_name" = c("Osteoarthritis of knee", "Osteoarthritis of hip", "Adalimumab"),
                    "domain_id" = c("Condition", "Condition", "Drug"),
                    "vocabulary_id" = c("SNOMED","SNOMED","RxNorm"),
                    "standard_concept" = c("S","S","S")))
codelist_with_details <- newCodelistWithDetails(codelist_with_details)

codelist_with_details

The codelist with details also has two specific attributes:

attributes(codelist_with_details)

Create an empty codelist with details

omopGenerics package also has a function to create an empty codelist with details.

empty_codelist_with_details <- emptyCodelistWithDetails()

empty_codelist_with_details

Concept set expression

A concept set expression contains a tibble with the logic describing how this concepts will be included or excluded. It usually follows the JSON file structure. To create one, we need a named list with a tibble containing the columns: concept_id, excluded, descendants, and mapped:

concept_set_expression <- list(
  "codes1" = tibble("concept_id" = c(1L, 2L, 3L),
                    "excluded" = c(FALSE, FALSE, FALSE),
                    "descendants" = c(TRUE, FALSE, FALSE),
                    "mapped" = c(TRUE, TRUE, TRUE)),
  "codes2" = tibble("concept_id" = c(4L, 5L, 10L),
                    "excluded" = c(FALSE, FALSE, FALSE),
                    "descendants" = c(FALSE, FALSE, FALSE),
                    "mapped" = c(TRUE, TRUE, TRUE))
)

concept_set_expression <- newConceptSetExpression(concept_set_expression)

concept_set_expression

You can also see the attributes:

attributes(concept_set_expression)

Create an empty concept set expression

We can also use omopGenerics package to create an empty concept set expression:

empty_concept_set_expression <- emptyConceptSetExpression()

empty_concept_set_expression

Concept set expression from a JSON file

CodelistGenerator contains a function that allows us to read a JSON file and transform it to a concept set expression (or other types of codelists). See the vignette Extract codelists from JSON files for further information.

Change to different codelist types

There are several functions in CodelistGenerator that will allow us to go from a codelist to a codelist with details.

Codelist/Concept set expression to codelist with details

Notice that to go from a codelist or concept_set_expression to a codelist_with_details, we will need to provide the cdm, as the details of the concepts will be extracted from the concept table.

cdm <- mockVocabRef()
codelist_to_codelist_with_details <- asCodelistWithDetails(codelist, cdm)
codelist_to_codelist_with_details

codelist_to_concept_set_expression <- asCodelistWithDetails(codelist, cdm)
codelist_to_concept_set_expression

Codelist/Codelist with details to concept set expression


codelist_to_concept_set_expression <- asConceptSetExpression(codelist)
codelist_to_concept_set_expression

codelist_with_details_to_concept_set_expression <- asConceptSetExpression(codelist_with_details)
codelist_with_details_to_concept_set_expression

Codelist with details/Concept set expression to codelist

codelist_with_details_to_codelist <- asCodelist(codelist_with_details)
codelist_with_details_to_codelist