Create a drug users cohort
To create a basic drug users cohort we need two things:
- A conceptSet: will determine which concepts we will use.
- A gapEra: will determine how we will collapse those exposures.
Creating a conceptSet
There are three possible forms of a conceptSet:
- A named list of concept ids
- A
codelistobject, seevignette("codelists", package = "omopgenerics")
conceptSet <- list(acetaminophen = c(1, 2, 3)) |> omopgenerics::newCodelist()
#> Warning: ! `codelist` contains numeric values, they are casted to integers.
conceptSet
#>
#> ── 1 codelist ──────────────────────────────────────────────────────────────────
#>
#> - acetaminophen (3 codes)
conceptSet$acetaminophen
#> [1] 1 2 3- A
conceptSetExpressionobject, seevignette("codelists", package = "omopgenerics")
conceptSet <- list(acetaminophen = dplyr::tibble(
concept_id = 1125315,
excluded = FALSE,
descendants = TRUE,
mapped = FALSE
)) |>
omopgenerics::newConceptSetExpression()
conceptSet
#>
#> ── 1 conceptSetExpression ──────────────────────────────────────────────────────
#>
#> - acetaminophen (1 concept criteria)
conceptSet$acetaminophen
#> # A tibble: 1 × 4
#> concept_id excluded descendants mapped
#> <int> <lgl> <lgl> <lgl>
#> 1 1125315 FALSE TRUE FALSEThe package CodelistGenerator can be very useful to create conceptSet.
For example we can create a conceptSet based in an ingredient with
getDrugIngredientCodes():
codes <- getDrugIngredientCodes(cdm = cdm, name = "acetaminophen")
codes[["161_acetaminophen"]]
#> [1] 1125315 1125360 2905077 43135274We could also use the function codesFromConceptSet() to
read a concept set from a json file:
codes <- codesFromConceptSet(path = system.file("acetaminophen.json", package = "DrugUtilisation"), cdm = cdm)
#> Warning: ! `codelist` contains numeric values, they are casted to integers.
codes
#>
#> ── 1 codelist ──────────────────────────────────────────────────────────────────
#>
#> - acetaminophen (4 codes)The gapEra parameter
The gapEra parameter is used to join exposures into
episodes, let’s say for example we have an individual with 4 drug
exposures that we are interested in. The first two overlap each other,
then there is a gap of 29 days and two consecutive exposures:
If we would create the episode with gapEra = 0, we would have 3 resultant episodes, the first two that overlap would be joined in a single episode, but then the other two would be independent:
#> # A tibble: 3 × 4
#> cohort_definition_id subject_id cohort_start_date cohort_end_date
#> <int> <int> <date> <date>
#> 1 1 1 2020-01-01 2020-02-15
#> 2 1 1 2020-03-15 2020-04-19
#> 3 1 1 2020-04-20 2020-05-15
If, instead we would use a gapEra = 1, we would have 2 resultant episodes, the first two that overlap would be joined in a single episode (as before), now the two consecutive exposures would be joined in a single episode:
#> # A tibble: 2 × 4
#> cohort_definition_id subject_id cohort_start_date cohort_end_date
#> <int> <int> <date> <date>
#> 1 1 1 2020-01-01 2020-02-15
#> 2 1 1 2020-03-15 2020-05-15
The result would be the same for any value between 1 and 28 (gapEra \(\in\) [1, 28]).
Whereas, if we would use a gapEra = 29 all the records would be collapsed into a single episode:
#> # 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-05-15
Create your cohort
We will then create now a cohort with all the drug users of acetaminophen with a gapEra of 30 days.
codes <- getDrugIngredientCodes(cdm = cdm, name = "acetaminophen")
names(codes) <- "acetaminophen"
cdm <- generateDrugUtilisationCohortSet(cdm = cdm, name = "acetaminophen_cohort", conceptSet = codes, gapEra = 30)
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 30 days.
cdm
#>
#> ── # OMOP CDM reference (duckdb) of DUS MOCK ───────────────────────────────────
#> • omop tables: person, observation_period, concept, concept_ancestor,
#> drug_strength, concept_relationship, drug_exposure, condition_occurrence,
#> observation, visit_occurrence
#> • cohort tables: cohort1, cohort2, acetaminophen_cohort
#> • achilles tables: -
#> • other tables: -NOTE that the name argument is used to create the new
table in the cdm object. For database backends this is the name of the
table that will be created.
We can compare what we see with what we would expect; if we look at the individual with more records we can see how all of them are joined into a single exposure as the records overlap each other:
cdm$drug_exposure |>
dplyr::filter(drug_concept_id %in% !!codes$acetaminophen & person_id == 69)
#> # Source: SQL [4 x 23]
#> # Database: DuckDB v1.1.0 [root@Darwin 24.2.0:R 4.4.1/:memory:]
#> drug_exposure_id person_id drug_concept_id drug_exposure_start_date
#> <int> <int> <int> <date>
#> 1 201 69 2905077 2002-01-29
#> 2 203 69 2905077 2001-04-23
#> 3 205 69 2905077 2001-03-04
#> 4 204 69 43135274 2003-10-16
#> # ℹ 19 more variables: drug_exposure_end_date <date>,
#> # drug_type_concept_id <int>, quantity <dbl>,
#> # drug_exposure_start_datetime <date>, drug_exposure_end_datetime <date>,
#> # verbatim_end_date <date>, stop_reason <chr>, refills <int>,
#> # days_supply <int>, sig <chr>, route_concept_id <int>, lot_number <chr>,
#> # provider_id <int>, visit_occurrence_id <int>, visit_detail_id <int>,
#> # drug_source_value <chr>, drug_source_concept_id <int>, …cdm$acetaminophen_cohort |>
dplyr::filter(subject_id == 69)
#> # Source: SQL [1 x 4]
#> # Database: DuckDB v1.1.0 [root@Darwin 24.2.0:R 4.4.1/:memory:]
#> cohort_definition_id subject_id cohort_start_date cohort_end_date
#> <int> <int> <date> <date>
#> 1 1 69 2001-03-04 2004-06-02In this case gapEra did not have a big impact as we can see in the attrition:
attrition(cdm$acetaminophen_cohort)
#> # A tibble: 2 × 7
#> cohort_definition_id number_records number_subjects reason_id reason
#> <int> <int> <int> <int> <chr>
#> 1 1 71 62 1 Initial qualify…
#> 2 1 70 62 2 Collapse record…
#> # ℹ 2 more variables: excluded_records <int>, excluded_subjects <int>We can see this particular case of this individual:
cdm$drug_exposure |>
dplyr::filter(drug_concept_id %in% !!codes$acetaminophen & person_id == 50)
#> # Source: SQL [2 x 23]
#> # Database: DuckDB v1.1.0 [root@Darwin 24.2.0:R 4.4.1/:memory:]
#> drug_exposure_id person_id drug_concept_id drug_exposure_start_date
#> <int> <int> <int> <date>
#> 1 143 50 1125360 2017-04-14
#> 2 144 50 43135274 2017-04-01
#> # ℹ 19 more variables: drug_exposure_end_date <date>,
#> # drug_type_concept_id <int>, quantity <dbl>,
#> # drug_exposure_start_datetime <date>, drug_exposure_end_datetime <date>,
#> # verbatim_end_date <date>, stop_reason <chr>, refills <int>,
#> # days_supply <int>, sig <chr>, route_concept_id <int>, lot_number <chr>,
#> # provider_id <int>, visit_occurrence_id <int>, visit_detail_id <int>,
#> # drug_source_value <chr>, drug_source_concept_id <int>, …In this case we have 3 exposures separated by 3 days, so if we use the 30 days gap both exposures are joined into a single episode, whereas if we would use a gapEra smaller than 3 we would consider them as different episodes.
cdm$acetaminophen_cohort |>
dplyr::filter(subject_id == 50)
#> # Source: SQL [1 x 4]
#> # Database: DuckDB v1.1.0 [root@Darwin 24.2.0:R 4.4.1/:memory:]
#> cohort_definition_id subject_id cohort_start_date cohort_end_date
#> <int> <int> <date> <date>
#> 1 1 50 2017-04-01 2017-04-23We can access the other cohort attributes using the adequate functions. In settings we can see that the gapEra used is recorded or with cohortCodelist we can see which was the codelist used to create the cohort.
settings(cdm$acetaminophen_cohort)
#> # A tibble: 1 × 3
#> cohort_definition_id cohort_name gap_era
#> <int> <chr> <chr>
#> 1 1 acetaminophen 30
cohortCount(cdm$acetaminophen_cohort)
#> # A tibble: 1 × 3
#> cohort_definition_id number_records number_subjects
#> <int> <int> <int>
#> 1 1 70 62
cohortCodelist(cdm$acetaminophen_cohort, cohortId = 1)
#>
#> ── 1 codelist ──────────────────────────────────────────────────────────────────
#>
#> - acetaminophen (4 codes)
