Using CDM attributes

Set up

Let’s again load required packages and connect to our Eunomia dataset in duckdb.

library(CDMConnector)
library(omopgenerics)
library(dplyr)

write_schema <- "main"
cdm_schema <- "main"

con <- DBI::dbConnect(duckdb::duckdb(), dbdir = eunomia_dir())
cdm <- cdm_from_con(con, cdm_name = "eunomia", cdm_schema = cdm_schema, write_schema = write_schema)

CDM reference attributes

Our cdm reference has various attributes associated with it. These can be useful both when programming and when developing analytic packages on top of CDMConnector.

CDM name

It’s a requirement that every cdm reference has name associated with it. This is particularly useful for network studies so that we can associate results with a particular cdm. We can access this attribute like so

#attr(cdm, "cdm_name")

Because it is so regularly used, to make getting the cdm name even easier, we can also use cdmName (or it’s snake case equivalent cdm_name)

cdmName(cdm)
#> [1] "eunomia"
cdm_name(cdm)
#> [1] "eunomia"

CDM version

The OMOP CDM has various versions. We also have an attribute giving the version of the cdm we have connected to.

#attr(cdm, "cdm_version")

Database connection

We also have an attribute identifying the database connection underlying the cdm reference.

#cdmCon(cdm)

This can be useful, for example, if we want to make use of DBI functions to work with the database. For example we could use dbListTables to list the names of remote tables accessible through the connection, dbListFields to list the field names of a specific remote table, and dbGetQuery to returns the result of a query

#DBI::dbListTables(cdmCon(cdm))
#DBI::dbListFields(cdmCon(cdm), "person")
#DBI::dbGetQuery(cdmCon(cdm), "SELECT * FROM person LIMIT 5")

Cohort attributes

Generated cohort set

When we generate a cohort in addition to the cohort table itself we also have various attributes that can be useful for subsequent analysis.

Here we create a cohort table with a single cohort.


# debugonce(generateConceptCohortSet)
cdm <- generateConceptCohortSet(cdm = cdm, 
                                conceptSet = list("gi_bleed" = 192671,
                                                  "celecoxib" = 1118084), 
                                name = "study_cohorts",
                                overwrite = TRUE)

cdm$study_cohorts %>% 
  glimpse()
#> Rows: ??
#> Columns: 4
#> Database: DuckDB v0.9.2 [root@Darwin 23.0.0:R 4.3.1//var/folders/xx/01v98b6546ldnm1rg1_bvk000000gn/T//RtmpVYlDWC/file16db19b6e603.duckdb]
#> $ cohort_definition_id <int> 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 1, 1, 1, 2, 2, 2…
#> $ subject_id           <int> 304, 651, 807, 2005, 2256, 2674, 648, 2116, 2654,…
#> $ cohort_start_date    <date> 1998-05-03, 2012-06-08, 1994-11-04, 2010-02-12, …
#> $ cohort_end_date      <date> 2019-06-17, 2018-12-06, 2019-03-19, 2019-05-25, …

We have a cohort set attribute that gives details on the settings associated with the cohorts (along with utility functions to make it easier to access this attribute).

attr(cdm$study_cohorts, "cohort_set")
#> # Source:   table<study_cohorts_set> [2 x 6]
#> # Database: DuckDB v0.9.2 [root@Darwin 23.0.0:R 4.3.1//var/folders/xx/01v98b6546ldnm1rg1_bvk000000gn/T//RtmpVYlDWC/file16db19b6e603.duckdb]
#>   cohort_definition_id cohort_name limit prior_observation future_observation
#>                  <int> <chr>       <chr>             <dbl>              <dbl>
#> 1                    1 gi_bleed    first                 0                  0
#> 2                    2 celecoxib   first                 0                  0
#> # ℹ 1 more variable: end <chr>
settings(cdm$study_cohorts)
cohort_set(cdm$study_cohorts) 

We have a cohort_count attribute with counts for each of the cohorts.

attr(cdm$study_cohorts, "cohort_count")
#> NULL
cohortCount(cdm$study_cohorts)
cohort_count(cdm$study_cohorts)

And we also have an attribute, cohort attrition, with a summary of attrition when creating the cohorts.

attr(cdm$study_cohorts, "cohort_attrition")
cohortAttrition(cdm$study_cohorts)
cohort_attrition(cdm$study_cohorts)

In addition, we also have the cdm reference itself as an attribute of the cohorts. This is particularly useful when developing analytic packages on top of CDMConnector.

attr(cdm$study_cohorts, "cdm_reference")
#> 
#> ── # OMOP CDM reference (duckdb) of eunomia ────────────────────────────────────
#> • omop tables: person, observation_period, visit_occurrence, visit_detail,
#> condition_occurrence, drug_exposure, procedure_occurrence, device_exposure,
#> measurement, observation, death, note, note_nlp, specimen, fact_relationship,
#> location, care_site, provider, payer_plan_period, cost, drug_era, dose_era,
#> condition_era, metadata, cdm_source, concept, vocabulary, domain,
#> concept_class, concept_relationship, relationship, concept_synonym,
#> concept_ancestor, source_to_concept_map, drug_strength
#> • cohort tables: study_cohorts
#> • achilles tables: -
#> • other tables: -

Creating a bespoke cohort

Say we create a custom GI bleed cohort with the standard cohort structure

cdm$gi_bleed <- cdm$condition_occurrence %>% 
  filter(condition_concept_id == 192671) %>% 
  mutate(cohort_definition_id = 1) %>% 
  select(
    cohort_definition_id, 
    subject_id = person_id, 
    cohort_start_date = condition_start_date, 
    cohort_end_date = condition_start_date
  ) %>% 
  compute(name = "gi_bleed", temporary = FALSE, overwrite = TRUE)

cdm$gi_bleed %>% 
  glimpse()
#> Rows: ??
#> Columns: 4
#> Database: DuckDB v0.9.2 [root@Darwin 23.0.0:R 4.3.1//var/folders/xx/01v98b6546ldnm1rg1_bvk000000gn/T//RtmpVYlDWC/file16db19b6e603.duckdb]
#> $ cohort_definition_id <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1…
#> $ subject_id           <int> 273, 61, 351, 579, 549, 116, 163, 304, 326, 285, …
#> $ cohort_start_date    <date> 2011-10-10, 2005-09-15, 2018-06-28, 1999-11-06, …
#> $ cohort_end_date      <date> 2011-10-10, 2005-09-15, 2018-06-28, 1999-11-06, …

We can add the required attributes using the newGeneratedCohortSet function. The minimum requirement for this is that we also define the cohort set to associate with our set of custom cohorts.

GI_bleed_cohort_ref <- tibble(cohort_definition_id = 1, cohort_name = "custom_gi_bleed")

cdm$gi_bleed <- omopgenerics::newCohortTable(
  table = cdm$gi_bleed, cohortSetRef = GI_bleed_cohort_ref
)

Now our custom cohort GI_bleed has the same attributes associated with it as if it had been created by generateConceptCohortSet. This will mean that it can be used by analytic packages designed to work with cdm cohorts.

settings(cdm$gi_bleed)
#> # A tibble: 1 × 2
#>   cohort_definition_id cohort_name    
#>                  <dbl> <chr>          
#> 1                    1 custom_gi_bleed
cohortCount(cdm$gi_bleed)
#> # A tibble: 1 × 3
#>   cohort_definition_id number_records number_subjects
#>                  <int>          <int>           <int>
#> 1                    1            479             479
cohortAttrition(cdm$gi_bleed)
#> Warning: `cohortAttrition()` was deprecated in CDMConnector 1.3.
#> ℹ Please use `attrition()` instead.
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.
#> # A tibble: 1 × 7
#>   cohort_definition_id number_records number_subjects reason_id reason          
#>                  <int>          <int>           <int>     <int> <chr>           
#> 1                    1            479             479         1 Initial qualify…
#> # ℹ 2 more variables: excluded_records <int>, excluded_subjects <int>
attr(cdm$gi_bleed, "cdm_reference")
#> 
#> ── # OMOP CDM reference (duckdb) of eunomia ────────────────────────────────────
#> • omop tables: person, observation_period, visit_occurrence, visit_detail,
#> condition_occurrence, drug_exposure, procedure_occurrence, device_exposure,
#> measurement, observation, death, note, note_nlp, specimen, fact_relationship,
#> location, care_site, provider, payer_plan_period, cost, drug_era, dose_era,
#> condition_era, metadata, cdm_source, concept, vocabulary, domain,
#> concept_class, concept_relationship, relationship, concept_synonym,
#> concept_ancestor, source_to_concept_map, drug_strength
#> • cohort tables: study_cohorts, gi_bleed
#> • achilles tables: -
#> • other tables: -