By Maxim Moinat and the Themis Working Group

The Themis Working Group convened on October 6th and December 7th 2023 to discuss the creation this convention for creating custom concepts.


While the OMOP vocabularies are very comprehensive, it is not always possible to use concepts existing in the OMOP vocabularies. For example, when using a vocabulary that is only used in your institution or having custom defined variables. In these cases, custom concepts can be used. Custom concepts are concepts that are not part of the OMOP vocabularies, and are only used in your institution. There are two main reasons to define custom concepts in your local OMOP CDM vocabulary. The first is that they are available in your local Atlas instance, which has several use cases:

The second reason is using the custom concepts in your ETL. By creating both the custom concept, and the ‘Maps to’ relationship (example below), we can use this in the same way as mapping other source vocabularies.

Custom concepts are only defined locally. These cannot be used for network research. Therefore it remains very important to map to standard concepts.


It is important to follow a set of conventions when creating custom concepts, to avoid negatively impacting network studies. The conventions are as follows:

In addition, it is recommended to follow these suggestions:


In this example, we will add one custom concept for the ‘DHD Diagnose Thesaurus’. This is a Dutch vocabulary, which is not part of the OMOP vocabularies. We will add the concept ‘diabetes mellitus type 1’. This concept has a mapping to the standard concept ‘Diabetes mellitus type 1 (disorder)’, concept_id 3341872.

After creating these records, we can use the custom concept in our ETL to populate the condition_source_concept_id field.

Custom vocabulary

Field Value
vocabulary_id DHD Diagnose Thesaurus
vocabulary_name Dutch Hospital Data Diagnosethesaurus
vocabulary_version 2023-04-20
vocabulary_concept_id 0

Custom concept

Field Value
concept_id 2 000 000 001
concept_name diabetes mellitus type 1
domain_id Condition
vocabulary_id DHD Diagnose Thesaurus
concept_class_id Undefined
standard_concept NULL
concept_code 0000002630
valid_start_date 2017-08-01
valid_end_date 2099-12-31
invalid_reason NULL

Mapping relationship

Field Value
concept_id_1 2 000 000 001
concept_id_2 3341872
relationship_id Maps to
valid_start_date 2017-08-01
valid_end_date 2099-12-31
invalid_reason NULL
Field Value
——- ——-
concept_id_1 3341872
concept_id_2 2 000 000 001
relationship_id Mapped from
valid_start_date 2017-08-01
valid_end_date 2099-12-31
invalid_reason NULL

See the Source To Standard query to map a code in the source data to a standard concept.

Getting your vocabulary into the OMOP vocabularies

If you think your custom concepts are useful for others, you can submit them to the OMOP vocabularies. This could be as a supported source vocabulary (like ICD) or a new vocabulary with standard concepts (like LOINC). This is a separate process from the conventions described above. Please see the this support page.


1Melanie Philofsky; Implementing & adopting a customized OMOP Common Data Model; OHDSI Symposium 2021

2Melanie Philofsky; Mapping Custom Source Codes to Standard Concepts: A Comparison of Two Approaches; OHDSI Symposium 2020
this is why custom concepts are sometimes referred to as “2B+” or “2billionaires”.