Available concept sets

Available concept sets

The package OmopConcepts is used to download concept sets from its GitHub repository. The following concept sets are available:

ConceptSet name	Description	Author(s)	Reference
heart_failure	This concept set was used for bla bla…	@catalamarti
arthritis	This concept set was used for bla bla…	@catalamarti

You can easily check which are the available concept sets to download programatically using: availableConceptSets():

library(OmopConcepts)
availableConceptSets()
#> [1] "heart_failure" "arthritis"

Download concept sets

To download a concept set you can just type:

downloadConceptSet(conceptSetName = "heart_failure")
#> 
#> ── 1 concept set expression ────────────────────────────────────────────────────
#> 
#> - heart_failure (1 concept criteria)

Note that although it has a “fancy” print, it is just a named list of tibbles with the following columns: concept_id, excluded, descendants and mapped. This object is created by the omopgenerics R package, see the concept sets vignette. New ceoncept sets can be created with the newConceptSetExpression() function.

cs <- downloadConceptSet(conceptSetName = "heart_failure")
class(cs)
#> [1] "concept_set_expression" "conceptSetExpression"   "list"
cs
#> 
#> ── 1 concept set expression ────────────────────────────────────────────────────
#> 
#> - heart_failure (1 concept criteria)
cs$heart_failure
#> # A tibble: 1 × 4
#>   concept_id excluded descendants mapped
#>        <int> <lgl>    <lgl>       <lgl> 
#> 1     316139 FALSE    TRUE        FALSE

You can easily download multiple concept sets by providing multiple names:

downloadConceptSet(conceptSetName = c("heart_failure", "arthritis"))
#> 
#> ── 2 concept set expressions ───────────────────────────────────────────────────
#> 
#> - arthritis (1 concept criteria)
#> - heart_failure (1 concept criteria)

Use tags

Concepts are grouped into tags. Each concept can be part of multiple tags (or none) and each tag contains usually multiple concepts. You can for example download all the concepts sets assigned table1 tag as:

cs <- downloadConceptSet(conceptSetName = "@table1")
cs
#> 
#> ── 2 concept set expressions ───────────────────────────────────────────────────
#> 
#> - arthritis (1 concept criteria)
#> - heart_failure (1 concept criteria)

Here you can see all the tags and their description:

• table1: This set of concepts is usually used to describle the general characteristics of a population. Concepts: heart_failure, arthritis.

Import and export concept sets

The concept_set_expression object can be easily exported and imported in two formats: json and csv.

cs <- downloadConceptSet(conceptSetName = "@table1")
td <- file.path(tempdir(), "concepts")
dir.create(path = td)
exportConceptSetExpression(x = cs, path = td, type = "csv")

Each concept set will be exported in a separate .csv file:

list.files(path = td, pattern = ".csv$")
#> [1] "arthritis.csv"     "heart_failure.csv"

Later those files can be used to import the concept set back:

new_cs <- importConceptSetExpression(path = td, type = "csv")
#> 2 concept set expressions imported.
new_cs
#> 
#> ── 2 concept set expressions ───────────────────────────────────────────────────
#> 
#> - arthritis (1 concept criteria)
#> - heart_failure (1 concept criteria)

We can easily check that the imported and exported concept set are the same:

identical(cs, new_cs)
#> [1] TRUE

The same can be done using a the .json file extension (the JSON file format is widely supported by other OHDSI tools such as ATLAS).

exportConceptSetExpression(x = cs, path = td, type = "json")
list.files(path = td, pattern = ".json$")
#> [1] "arthritis.json"     "heart_failure.json"
importConceptSetExpression(path = td, type = "json")
#> 2 concept set expressions imported.
#> 
#> 
#> ── 2 concept set expressions ───────────────────────────────────────────────────
#> 
#> - arthritis (1 concept criteria)
#> - heart_failure (1 concept criteria)

From concept set to codelist

The concept set expression is a compact way to define a codelist, that relies on the vocabularies to solve the descendants. Note vocabularies hierarchy can slightly vary release to release so a concept set expression can lead to a slightly different list of concepts. These new concepts might be desired or undesired in some cases you want to resolve the concept set at a vocabulary that you control, in this case you can create easily a codelist from a concept set expression using the validateConceptSetArgument() function. Note you will need to use a cdm object with links to the vocabulary tables, in this case we will use the empty_cdm that contains vocabularies from: v5.0 22-JUN-22.

library(omock)
cdm <- mockCdmFromDataset(datasetName = "empty_cdm")

codelist <- validateConceptSetArgument(conceptSet = cs, cdm = cdm)
class(codelist)
#> [1] "codelist" "list"
codelist
#> 
#> ── 2 codelists ─────────────────────────────────────────────────────────────────
#> 
#> - arthritis (836 codes)
#> - heart_failure (116 codes)

Note the codelist contains a list of the included concepts and does not rely on hierarchy:

head(codelist$heart_failure, 10)
#>  [1]  4108244 43021840 43021736  4193236   764872 40480603  4233224 45766166
#>  [9] 36716182  4327205

Import and export codelist

Similarly to concept_set_expression object the codelist object can also be exported and imported in two formats: json and csv.

See example for csv files:

td <- file.path(tempdir(), "concepts")
dir.create(path = td)
exportCodelist(x = codelist, path = td, type = "csv")
list.files(path = td, pattern = ".csv$")
#> [1] "arthritis.csv"     "heart_failure.csv"
new_codelist <- importCodelist(path = td, type = "csv")
#> 2 codelists imported.
new_codelist
#> 
#> ── 2 codelists ─────────────────────────────────────────────────────────────────
#> 
#> - arthritis (836 codes)
#> - heart_failure (116 codes)
identical(codelist, new_codelist)
#> [1] TRUE

And in json files:

exportCodelist(x = codelist, path = td, type = "json")
list.files(path = td, pattern = ".json$")
#> [1] "arthritis.json"     "heart_failure.json"
importCodelist(path = td, type = "json")
#> 2 codelists imported.
#> 
#> 
#> ── 2 codelists ─────────────────────────────────────────────────────────────────
#> 
#> - arthritis (836 codes)
#> - heart_failure (116 codes)

Source codes

The source codes of the concept set expressions can be found in: https://github.com/OHDSI/OmopConcepts/tree/main/resources/concept_sets and metadata in: https://github.com/OHDSI/OmopConcepts/blob/main/resources/metadata.csv. If you want to see how to contribute to the repo adding and documenting more concept set expressions see vignette ‘How to contribute’.

Cite

Please if you use this concept sets in your research cite the corresponding article for each concept set (see reference column in above table). Also if useful feel free to cite our package :).

#> To cite package 'OmopConcepts' in publications use:
#> 
#>   Català M (2025). _OmopConcepts: Concepts Set Expressions for the OMOP
#>   Common Data Model_. R package version 0.1.0,
#>   <https://OHDSI.github.io/OmopConcepts/>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {OmopConcepts: Concepts Set Expressions for the OMOP Common Data Model},
#>     author = {Martí Català},
#>     year = {2025},
#>     note = {R package version 0.1.0},
#>     url = {https://OHDSI.github.io/OmopConcepts/},
#>   }