Learn R Programming

omopgenerics

Package overview

The omopgenerics package provides definitions of core classes and methods used by analytic pipelines that query the OMOP common data model.

#> Warning in citation("omopgenerics"): could not determine year for
#> 'omopgenerics' from package DESCRIPTION file
#> To cite package 'omopgenerics' in publications use:
#> 
#>   Català M, Burn E (????). _omopgenerics: Methods and Classes for the
#>   OMOP Common Data Model_. R package version 1.3.7,
#>   <https://darwin-eu.github.io/omopgenerics/>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {omopgenerics: Methods and Classes for the OMOP Common Data Model},
#>     author = {Martí Català and Edward Burn},
#>     note = {R package version 1.3.7},
#>     url = {https://darwin-eu.github.io/omopgenerics/},
#>   }

If you find the package useful in supporting your research study, please consider citing this package.

Installation

You can install the development version of OMOPGenerics from GitHub with:

install.packages("pak")
pak::pkg_install("darwin-eu/omopgenerics")

And load it using the library command:

library(omopgenerics)
library(dplyr)

Core classes and methods

CDM Reference

A cdm reference is a single R object that represents OMOP CDM data. The tables in the cdm reference may be in a database, but a cdm reference may also contain OMOP CDM tables that are in data frames/tibbles or in Arrow. In the latter case, the cdm reference would typically be a subset of an original cdm reference that has been derived as part of a particular analysis.

omopgenerics contains the class definition of a cdm reference and a data frame implementation. For creating a cdm reference using a database, see the CDMConnector package (https://darwin-eu.github.io/CDMConnector/).

A cdm object can contain four types of tables:

  • Standard tables:
omopTables()
#>  [1] "person"                "observation_period"    "visit_occurrence"     
#>  [4] "visit_detail"          "condition_occurrence"  "drug_exposure"        
#>  [7] "procedure_occurrence"  "device_exposure"       "measurement"          
#> [10] "observation"           "death"                 "note"                 
#> [13] "note_nlp"              "specimen"              "fact_relationship"    
#> [16] "location"              "care_site"             "provider"             
#> [19] "payer_plan_period"     "cost"                  "drug_era"             
#> [22] "dose_era"              "condition_era"         "metadata"             
#> [25] "cdm_source"            "concept"               "vocabulary"           
#> [28] "domain"                "concept_class"         "concept_relationship" 
#> [31] "relationship"          "concept_synonym"       "concept_ancestor"     
#> [34] "source_to_concept_map" "drug_strength"         "cohort_definition"    
#> [37] "attribute_definition"  "concept_recommended"

Each table has required columns. For example, these are the required columns for the person table:

omopColumns(table = "person")
#>  [1] "person_id"                   "gender_concept_id"          
#>  [3] "year_of_birth"               "month_of_birth"             
#>  [5] "day_of_birth"                "birth_datetime"             
#>  [7] "race_concept_id"             "ethnicity_concept_id"       
#>  [9] "location_id"                 "provider_id"                
#> [11] "care_site_id"                "person_source_value"        
#> [13] "gender_source_value"         "gender_source_concept_id"   
#> [15] "race_source_value"           "race_source_concept_id"     
#> [17] "ethnicity_source_value"      "ethnicity_source_concept_id"
  • Cohort tables We can see the cohort-related tables and their required columns.
cohortTables()
#> [1] "cohort"           "cohort_set"       "cohort_attrition" "cohort_codelist"
cohortColumns(table = "cohort")
#> [1] "cohort_definition_id" "subject_id"           "cohort_start_date"   
#> [4] "cohort_end_date"

In addition, cohorts are defined in terms of a generatedCohortSet class. For more details on this class definition see the corresponding vignette.

  • Achilles tables The Achilles R package generates descriptive statistics about the data contained in the OMOP CDM. Again, we can see the tables created and their required columns.
achillesTables()
#> [1] "achilles_analysis"     "achilles_results"      "achilles_results_dist"
achillesColumns(table = "achilles_results")
#> [1] "analysis_id" "stratum_1"   "stratum_2"   "stratum_3"   "stratum_4"  
#> [6] "stratum_5"   "count_value"
  • Other tables, which can have any format.

Any table that is part of a cdm object has to satisfy four conditions:

  • All must share a common source.

  • Table names must be lowercase.

  • Column names in each table must be lowercase.

  • person and observation_period must be present.

Concept set

A concept set can be represented as either a codelist or a concept set expression. A codelist is a named list, with each item of the list containing specific concept IDs.

condition_codes <- list(
  "diabetes" = c(201820L, 4087682L, 3655269L),
  "asthma" = 317009L
)
condition_codes <- newCodelist(condition_codes)

condition_codes
#> 
#> ── 2 codelists ─────────────────────────────────────────────────────────────────
#> 
#> - asthma (1 codes)
#> - diabetes (3 codes)

Meanwhile, a concept set expression provides a high-level definition of concepts that, when applied to a specific OMOP CDM vocabulary version (by making use of the concept hierarchies and relationships), will result in a codelist.

condition_cs <- list(
  "diabetes" = dplyr::tibble(
    "concept_id" = c(201820L, 4087682L),
    "excluded" = c(FALSE, FALSE),
    "descendants" = c(TRUE, FALSE),
    "mapped" = c(FALSE, FALSE)
  ),
  "asthma" = dplyr::tibble(
    "concept_id" = 317009L,
    "excluded" = FALSE,
    "descendants" = FALSE,
    "mapped" = FALSE
  )
)
condition_cs <- newConceptSetExpression(condition_cs)

condition_cs
#> 
#> ── 2 concept set expressions ───────────────────────────────────────────────────
#> 
#> - asthma (1 concept criteria)
#> - diabetes (2 concept criteria)

A cohort table

A cohort is a set of people who satisfy one or more inclusion criteria for a period of time. When represented in a cdm reference, this table has the cohort table class. Cohort tables are then associated with attributes such as settings and attrition.

person <- tibble(
  person_id = 1L,
  gender_concept_id = 0L,
  year_of_birth = 1990L,
  race_concept_id = 0L, 
  ethnicity_concept_id = 0L
)
observation_period <- dplyr::tibble(
  observation_period_id = 1L, 
  person_id = 1L,
  observation_period_start_date = as.Date("2000-01-01"),
  observation_period_end_date = as.Date("2023-12-31"),
  period_type_concept_id = 0L
)
diabetes <- tibble(
  cohort_definition_id = 1L, 
  subject_id = 1L,
  cohort_start_date = as.Date("2020-01-01"),
  cohort_end_date = as.Date("2020-01-10")
)

cdm <- cdmFromTables(
  tables = list(
    "person" = person,
    "observation_period" = observation_period,
    "diabetes" = diabetes
  ),
  cdmName = "example_cdm"
)
cdm$diabetes <- newCohortTable(cdm$diabetes)

cdm$diabetes
#> # A tibble: 1 × 4
#>   cohort_definition_id subject_id cohort_start_date cohort_end_date
#>                  <int>      <int> <date>            <date>         
#> 1                    1          1 2020-01-01        2020-01-10
settings(cdm$diabetes)
#> # A tibble: 1 × 2
#>   cohort_definition_id cohort_name
#>                  <int> <chr>      
#> 1                    1 cohort_1
attrition(cdm$diabetes)
#> # A tibble: 1 × 8
#>   cohort_definition_id cohort_name number_records number_subjects reason_id
#>                  <int> <chr>                <int>           <int>     <int>
#> 1                    1 cohort_1                 1               1         1
#> # ℹ 3 more variables: reason <chr>, excluded_records <int>,
#> #   excluded_subjects <int>
cohortCount(cdm$diabetes)
#> # A tibble: 1 × 4
#>   cohort_definition_id cohort_name number_records number_subjects
#>                  <int> <chr>                <int>           <int>
#> 1                    1 cohort_1                 1               1

Summarised result

A summarised result provides a standard format for the results of an analysis performed against data mapped to the OMOP CDM.

For example, this format is used when we get a summary of the cdm as a whole:

summary(cdm) |>
  glimpse()
#> Rows: 13
#> Columns: 13
#> $ result_id        <int> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1
#> $ cdm_name         <chr> "example_cdm", "example_cdm", "example_cdm", "example…
#> $ group_name       <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ group_level      <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ strata_name      <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ strata_level     <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ variable_name    <chr> "snapshot_date", "person_count", "observation_period_…
#> $ variable_level   <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA
#> $ estimate_name    <chr> "value", "count", "count", "source_name", "version", …
#> $ estimate_type    <chr> "date", "integer", "integer", "character", "character…
#> $ estimate_value   <chr> "2026-06-02", "1", "1", "", NA, "5.3", "", "", "", ""…
#> $ additional_name  <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ additional_level <chr> "overall", "overall", "overall", "overall", "overall"…

It is also used when we summarise a cohort:

summary(cdm$diabetes) |>
  glimpse()
#> `cohort_definition_id` cast to character.
#> `cohort_definition_id` cast to character.
#> Rows: 6
#> Columns: 13
#> $ result_id        <int> 1, 1, 2, 2, 2, 2
#> $ cdm_name         <chr> "example_cdm", "example_cdm", "example_cdm", "example…
#> $ group_name       <chr> "cohort_name", "cohort_name", "cohort_name", "cohort_…
#> $ group_level      <chr> "cohort_1", "cohort_1", "cohort_1", "cohort_1", "coho…
#> $ strata_name      <chr> "overall", "overall", "reason", "reason", "reason", "…
#> $ strata_level     <chr> "overall", "overall", "Initial qualifying events", "I…
#> $ variable_name    <chr> "number_records", "number_subjects", "number_records"…
#> $ variable_level   <chr> NA, NA, NA, NA, NA, NA
#> $ estimate_name    <chr> "count", "count", "count", "count", "count", "count"
#> $ estimate_type    <chr> "integer", "integer", "integer", "integer", "integer"…
#> $ estimate_value   <chr> "1", "1", "1", "1", "0", "0"
#> $ additional_name  <chr> "overall", "overall", "reason_id", "reason_id", "reas…
#> $ additional_level <chr> "overall", "overall", "1", "1", "1", "1"

Copy Link

Version

Install

install.packages('omopgenerics')

Monthly Downloads

1,661

Version

1.4.2

License

Apache License (>= 2)

Maintainer

Marti Catala

Last Published

September 8th, 2026

Functions in omopgenerics (1.4.2)

cdmDisconnect

Disconnect from a cdm object.
cdmName

Get or set the name of a cdm_reference associated object
cdmFromTables

Create a cdm object from local tables
$<-.cdm_reference

Assign a table to a cdm reference.
cdmAssignTableDoc

Helper for consistent documentation of assigning tables to a CDM reference.
cdmDoc

Helper for consistent documentation of cdm.
castDoc

Helper for consistent documentation of cast arguments.
cdmNameDoc

Helper for consistent documentation of CDM names.
cdmIndexDoc

Helper for consistent documentation of CDM index functions.
cdmSourceType

Get the source type of a cdm_reference object.
cdmSelect

Restrict the cdm object to a subset of tables.
cdmSource

Get the cdmSource of an object.
cdmReference

Get the cdm_reference of a cdm_table.
cdmTableDoc

Helper for consistent documentation of cdm_table objects.
cdmOrTableDoc

Helper for consistent documentation of cdm reference or table arguments.
cdmClasses

Separate the cdm tables in classes
checkCohortRequirements

Check whether a cohort table satisfies requirements
cdmVersion

Get the version of an object.
cohortColumns

Required columns for a generated cohort set.
cdmTableFromSource

This is an internal developer focused function that creates a cdm_table from a table that shares the source but it is not a cdm_table. Please use insertTable if you want to insert a table to a cdm_reference object.
cohortValidationChecksDoc

Helper for consistent documentation of cohort validation checks.
cdmVersionArgumentDoc

Helper for consistent documentation of CDM version arguments.
collect.cdm_reference

Retrieve the cdm reference into a local cdm.
cohortCount

Get cohort counts from a cohort_table object.
cohortCodelist

Get codelist from a cohort_table object.
cohortTables

Cohort tables that a cdm reference can contain in the OMOP Common Data Model.
codelistDoc

Helper for consistent documentation of codelist objects.
cliCallDoc

Helper for consistent documentation of call arguments.
cohortDoc

Helper for consistent documentation of cohort_table objects.
codelistWithDetailsDoc

Helper for consistent documentation of codelist_with_details objects.
createLogFile

Create a log file
combineStrata

Provide all combinations of strata levels.
conceptCdmDoc

Helper for consistent documentation of cdm concept validation.
createIndexes

Create the missing indexes
collect.cohort_table

To collect a cohort_table object.
compareOmopTableFields

Compare the fields of two different OMOP CDM versions
dropSourceTable

Drop a table from a cdm object.
compute.cdm_table

Store results in a table.
createTableIndex

Create a table index
emptyCohortTable

Create an empty cohort_table object
conceptSetExpressionDoc

Helper for consistent documentation of concept_set_expression objects.
emptyAchillesTable

Create an empty achilles table
emptyCdmReference

Create an empty cdm_reference
emptyCodeSearch

Empty code search object
dropTable

Drop a table from a cdm object. [Deprecated]
emptyCodelist

Empty codelist object.
emptyOmopTable

Create an empty omop table
emptyDoc

Helper for consistent documentation of empty arguments.
emptyCodelistWithDetails

Empty codelist object.
existingIndexes

Existing indexes in a cdm object
estimateTypeChoices

Choices that can be present in estimate_type column.
exportConceptSetExpression

Export a concept set expression.
exportCodeSearch

Export a code_search object into an Excel spreadsheet
expectedIndexes

Expected indexes in a cdm object
exportFileDoc

Helper for consistent documentation of exported files.
exportCodelistWithDetails

Export a codelist with details object.
exportCodelist

Export a codelist object.
emptySummarisedResult

Empty summarised_result object.
emptyConceptSetExpression

Empty concept_set_expression object.
emptyTableNameDoc

Helper for consistent documentation of empty table names.
exportSummarisedResult

Export a summarised_result object to a CSV file.
getPersonIdentifier

Get the column name with the person identifier from a table (either subject_id or person_id), it will throw an error if it contains both or neither.
filterResult

Filter a <summarised_result> automatically
getCohortId

Get the cohort definition id of a certain name
getCohortName

Get the cohort name of a certain cohort definition id
filterStrata

Filter the strata_name-strata_level pair in a summarised_result
groupColumns

Identify variables in group_name column
filterGroup

Filter the group_name-group_level pair in a summarised_result
filterAdditional

Filter the additional_name-additional_level pair in a summarised_result
filterSettings

Filter a <summarised_result> using the settings
insertTable

Insert a table into a cdm object.
importSummarisedResult

Import a set of summarised results.
insertFromSource

Convert a table that is not a cdm_table but have the same original source to a cdm_table. This Table is not meant to be used to insert tables in the cdm, please use insertTable instead.
insertCdmTo

Insert a cdm_reference object to a different source.
importCodelist

Import a codelist.
importCodelistWithDetails

Import a codelist with details.
importConceptSetExpression

Import a concept set expression.
importFileDoc

Helper for consistent documentation of imported files.
guessCdmVersion

Guess the OMOP CDM version
importCodeSearch

Import a code_search object from an Excel spreadsheet
newCdmTable

Create an cdm table.
logMessage

Log a message to a logFile
isResultSuppressed

To check whether an object is already suppressed to a certain min cell count.
newCodeSearch

Create a new code_search object
newCdmSource

Create a cdm source object.
newCdmReference

cdm_reference objects constructor
newAchillesTable

Create an achilles table from a cdm_table.
listSourceTables

List tables that can be accessed through a cdm object.
newCodelist

'codelist' object constructor
isTableEmpty

Check if a table is empty or not
numberRecords

Count the number of records that a cdm_table has.
omopCdmVersionDoc

Helper for consistent documentation of OMOP CDM versions.
newCohortTable

cohort_table objects constructor.
numberSubjects

Count the number of subjects that a cdm_table has.
newConceptSetExpression

'concept_set_expression' object constructor
newSummarisedResult

summarised_result object constructor
newOmopTable

Create an omop table from a cdm table.
newLocalSource

A new local source for the cdm
newCodelistWithDetails

'codelist' object constructor
newReadOnlySource

A new read-only source for the cdm
omopColumns

Required columns that the standard tables in the OMOP Common Data Model must have.
omopgenerics-package

omopgenerics: Methods and Classes for the OMOP Common Data Model
omopDataFolder

Check or set the OMOP_DATA_FOLDER where the OMOP related data is stored.
omopTables

Standard tables that a cdm reference can contain in the OMOP Common Data Model.
print.cdm_reference

Print a CDM reference object
omopTableFields

Return a table of omop cdm field information
pivotEstimates

Set estimates as columns
print.code_search

Print a code search
print.codelist

Print a codelist
overwriteDoc

Helper for consistent documentation of overwrite arguments.
recursiveDoc

Helper for consistent documentation of recursive file imports.
searchStrategy

Get the search strategy used to create a code_search
resultType

Get the result_type(s) defined in a certain package
print.concept_set_expression

Print a concept set expression
resultPackageVersion

Check if different package versions are used for a summarised_result object
recordCohortAttrition

Update cohort attrition.
readSourceTable

Read a table from the cdm_source and add it to the cdm.
reexports

Objects exported from other packages
print.codelist_with_details

Print a codelist with details
resultColumns

Required columns that the result tables must have.
settings.cohort_table

Get cohort settings from a cohort_table object.
splitAdditional

Split additional_name and additional_level columns
settings.summarised_result

Get settings from a summarised_result object.
splitAll

Split all pairs name-level into columns.
statusIndexes

Status of the indexes
settings

Get settings from an object.
sourceType

Get the source type of an object.
settingsColumns

Identify settings columns of a <summarised_result>
splitStrata

Split strata_name and strata_level columns
splitGroup

Split group_name and group_level columns
summary.cohort_table

Summarise a generated cohort set
[[<-.cdm_reference

Assign a table to a cdm reference.
summary.cdm_source

Summarise a cdm_source object
strataColumns

Identify variables in strata_name column
summariseLogFile

Summarise and extract the information of a log file into a summarised_result object.
summarisedResultDoc

Helper for consistent documentation of summarised_result objects.
[[.cdm_reference

Subset a cdm reference object.
summary.summarised_result

Summarise a summarised_result
summary.cdm_reference

Summarise a cdm reference
supportedCdmVersions

Supported OMOP CDM versions
toSnakeCase

Convert a character vector to snake case
suppress

Function to suppress counts in result objects
tmpPrefix

Create a temporary prefix for tables that contains a unique prefix that starts with tmp.
tableName

Get the table name of a cdm_table.
tidyColumns

Identify tidy columns of a <summarised_result>
transformToSummarisedResult

Create a <summarised_result> object from a data.frame, given a set of specifications.
tidy.summarised_result

Turn a <summarised_result> object into a tidy tibble
uniqueId

Get a unique Identifier with a certain number of characters and a prefix.
suppress.summarised_result

Function to suppress counts in result objects
tableSource

Get the table source of a cdm_table.
validateCdmTable

Validate if a table is a valid cdm_table object.
uniqueTableName

Create a unique table name
unusedDotsDoc

Helper for consistent documentation of unused dots.
validateAchillesTable

Validate if a cdm_table is a valid achilles table.
uniteAdditional

Unite one or more columns in additional_name-additional_level format
uniteGroup

Unite one or more columns in group_name-group_level format
uniteStrata

Unite one or more columns in strata_name-strata_level format
validateCohortArgument

Validate a cohort table input.
validateNameStyle

Validate nameStyle argument. If any of the element in ... has length greater than 1 it must be contained in nameStyle. Note that snake case notation is used.
validateStrataArgument

To validate a strata list. It makes sure that elements are unique and point to columns in table.
validateNameLevel

Validate if two columns are valid Name-Level pair.
validateNameArgument

Validate name argument. It must be a snake_case character vector. You can add a cdm object to check that name is not already used in that cdm.
validateAgeGroupArgument

Validate the ageGroup argument. It must be a list of two integerish numbers lower age and upper age, both of the must be greater or equal to 0 and lower age must be lower or equal to the upper age. If not named automatic names will be given in the output list.
validateConceptSetArgument

Validate conceptSet argument. It can either be a list, a codelist, a concept set expression or a codelist with details. The output will always be a codelist.
validateCdmArgument

Validate if an object in a valid cdm_reference.
validateNewColumn

Validate a new column of a table
validateOmopTable

Validate an omop_table
validateCohortIdArgument

Validate cohortId argument. CohortId can either be a cohort_definition_id value, a cohort_name or a tidyselect expression referring to cohort_names. If you want to support tidyselect expressions please use the function as: validateCohortIdArgument({{cohortId}}, cohort).
validateColumn

Validate whether a variable points to a certain existing column in a table.
validateResultArgument

Validate whether an object is a valid 'summarised_result' object.
validateWindowArgument

Validate a window argument. It must be a list of two elements (window start and window end), both must be numeric, integerish by default, and window start must be lower or equal than window end.
validationDoc

Helper for consistent documentation of validation mode.
assertClass

Assert that an object has a certain class.
achillesTables

Names of the tables that contain the results of achilles analyses
achillesColumns

Required columns for each of the achilles result tables
assertDate

Assert Date
addSettings

Add settings columns to a <summarised_result> object
assertDoc

Helper for consistent documentation of assertion functions.
assertList

Assert that an object is a list.
assertCharacter

Assert that an object is a character and satisfies certain conditions.
additionalColumns

Identify variables in additional_name column
assertChoice

Assert that an object is one of a set of options.
bind.cohort_table

Bind two or more cohort tables
bind

Bind two or more objects of the same class.
$.cdm_reference

Subset a cdm reference object.
assertTable

Assert that an object is a table.
assertTrue

Assert that an expression is TRUE.
bind.summarised_result

Bind two or summarised_result objects
assertLogical

Assert that an object is a logical.
assertNumeric

Assert that an object is a numeric.
attrition.cohort_table

Get cohort attrition from a cohort_table object.
attrition

Get attrition from an object.