Use DrugUtilisation to create a cohort

Introduction

In this vignette we will introduce different ways to create a drug utilisation cohort using DrugUtilisation.

Create a cdm object

To create a cdm_reference object you will need to use the package CDMConnector. For this vignette we will use mock data contained in the DrugUtilisation package.

library(DrugUtilisation)
library(CodelistGenerator)
library(dplyr)
library(CDMConnector)

cdm <- mockDrugUtilisation(numberIndividual = 200)

Get the concept code

The first thing that we need is a concept list. The concept list can be obtained through different ways:

Read from .json file
Use concept code directly
Use CodelistGenerator

Concept list from a .json file

To create a cohort with a concept list from a .json file, use codesFromConceptSet() from CodelistGenerator package. Let’s see an example:

conceptSet_json <- codesFromConceptSet(here::here("inst/Concept"), cdm)
conceptSet_json
#> $asthma
#> [1] 317009

Concept list listed directly

The concept list can also be created manually:

#get concept using code directly
conceptSet_code <- list(asthma = 317009)
conceptSet_code
#> $asthma
#> [1] 317009

Concept list of an ingredient

In case there is a certain ingredient of interest, the code can also be obtained by getDrugIngredientCodes() from the package CodelistGenerator.

#get concept by ingredient
conceptSet_ingredient <- getDrugIngredientCodes(cdm, name = "simvastatin")
conceptSet_ingredient
#> 
#> - simvastatin (3 codes)

Concept list from an ATC code

We can also obtain the ATC code by using getATCCodes() from CodelistGenerator package.

#get concept from ATC codes
conceptSet_ATC <- getATCCodes(cdm, 
                              level = "ATC 1st", 
                              name = "ALIMENTARY TRACT AND METABOLISM")
conceptSet_ATC
#> 
#> - alimentary_tract_and_metabolism (1 codes)

Create a cohort

Once we have the conceptSet, we can proceed to generate a cohort. There are two functions in this package to do that:

generateConceptCohortSet(): to generate a cohort for a certain list of concepts (they do not have to be a drug). This function is exported from CDMConnector package.
generateDrugUtilisationCohortSet(): to generate a cohort of the drug use.

Use generateConceptCohortSet() to create a cohort

Let’s try to use generateConceptCohortSet() to get the asthma cohort using the conceptSet_code created before. We could also use conceptSet_json_1 or conceptSet_json_2 to obtain the same result.

cdm <- generateConceptCohortSet(cdm,
  conceptSet = conceptSet_code,
  name = "asthma_1",
  overwrite = TRUE
)
cdm$asthma_1
#> # Source:   table<asthma_1> [?? x 4]
#> # Database: DuckDB v0.10.2 [unknown@Linux 6.5.0-1018-azure:R 4.4.0/:memory:]
#>    cohort_definition_id subject_id cohort_start_date cohort_end_date
#>                   <int>      <int> <date>            <date>         
#>  1                    1         13 2021-10-06        2022-01-05     
#>  2                    1         19 2019-07-19        2022-07-04     
#>  3                    1         93 1980-05-27        1994-10-08     
#>  4                    1        131 2022-08-24        2022-08-25     
#>  5                    1         35 2006-10-26        2019-06-27     
#>  6                    1         54 1993-04-25        2010-12-15     
#>  7                    1          2 2013-08-11        2013-08-18     
#>  8                    1         41 2001-02-25        2010-04-09     
#>  9                    1         58 2016-03-28        2020-07-23     
#> 10                    1        197 2021-02-09        2021-02-25     
#> # ℹ more rows

The count of the cohort can be assessed using cohortCount() from CDMConnector.

cohortCount(cdm$asthma_1)
#> # A tibble: 1 × 3
#>   cohort_definition_id number_records number_subjects
#>                  <int>          <int>           <int>
#> 1                    1            100             100

Cohort attrition can be assessed using attrition() from CDMConnector.

attrition(cdm$asthma_1)
#> # A tibble: 1 × 7
#>   cohort_definition_id number_records number_subjects reason_id reason          
#>                  <int>          <int>           <int>     <int> <chr>           
#> 1                    1            100             100         1 Initial qualify…
#> # ℹ 2 more variables: excluded_records <int>, excluded_subjects <int>

end parameter

You can use the end parameter to set how the cohort end date will be defined. By default, end = observation_period_end_date, but it can also be defined as event_end_date or by defining a numeric scalar. See an example below:

cdm <- generateConceptCohortSet(cdm,
  conceptSet = conceptSet_code,
  name = "asthma_2",
  end = "event_end_date",
  overwrite = TRUE
)
cdm$asthma_2
#> # Source:   table<asthma_2> [?? x 4]
#> # Database: DuckDB v0.10.2 [unknown@Linux 6.5.0-1018-azure:R 4.4.0/:memory:]
#>    cohort_definition_id subject_id cohort_start_date cohort_end_date
#>                   <int>      <int> <date>            <date>         
#>  1                    1         10 2004-03-15        2014-08-29     
#>  2                    1        156 2017-12-01        2020-01-02     
#>  3                    1        158 2020-09-03        2020-09-06     
#>  4                    1         21 1982-04-22        1991-04-15     
#>  5                    1         25 2001-06-29        2015-02-20     
#>  6                    1         99 1989-03-11        1989-11-22     
#>  7                    1        148 2011-05-24        2017-02-01     
#>  8                    1          6 2021-11-24        2022-01-17     
#>  9                    1        143 2017-12-15        2018-01-08     
#> 10                    1        184 2012-04-11        2012-06-24     
#> # ℹ more rows

requiredObservation parameter

The requiredObservation parameter is a numeric vector of length 2, that defines the number of days of required observation time prior to index and post index for an event to be included in the cohort. The default value is c(0,0). Let’s check how the difference between asthma_3 and asthma_2 when changing this parameter.

cdm <- generateConceptCohortSet(cdm,
  conceptSet = conceptSet_code,
  name = "asthma_3",
  end = "observation_period_end_date",
  requiredObservation = c(10, 10),
  overwrite = TRUE
)
cdm$asthma_3
#> # Source:   table<asthma_3> [?? x 4]
#> # Database: DuckDB v0.10.2 [unknown@Linux 6.5.0-1018-azure:R 4.4.0/:memory:]
#>    cohort_definition_id subject_id cohort_start_date cohort_end_date
#>                   <int>      <int> <date>            <date>         
#>  1                    1         41 2001-02-25        2010-04-09     
#>  2                    1        147 2010-01-11        2010-08-11     
#>  3                    1        152 2020-09-17        2021-07-21     
#>  4                    1         72 2008-09-30        2008-11-21     
#>  5                    1         11 2016-03-09        2019-07-02     
#>  6                    1         83 2017-07-07        2019-11-14     
#>  7                    1        122 2018-10-16        2020-08-01     
#>  8                    1         63 2009-12-22        2014-08-29     
#>  9                    1        117 1991-11-16        2017-05-25     
#> 10                    1         66 2018-06-21        2019-01-13     
#> # ℹ more rows

cohortCount(cdm$asthma_3)
#> # A tibble: 1 × 3
#>   cohort_definition_id number_records number_subjects
#>                  <int>          <int>           <int>
#> 1                    1             94              94

attrition(cdm$asthma_3)
#> # A tibble: 1 × 7
#>   cohort_definition_id number_records number_subjects reason_id reason          
#>                  <int>          <int>           <int>     <int> <chr>           
#> 1                    1             94              94         1 Initial qualify…
#> # ℹ 2 more variables: excluded_records <int>, excluded_subjects <int>

Use generateDrugUtilisationCohortSet() to generate a cohort

Now let’s try the function generateDrugUtilisationCohortSet() to get the drug cohort for the ingredient simvastatin. See an example below:

cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_1",
  conceptSet = conceptSet_ingredient
)
cdm$simvastin_1
#> # Source:   SQL [?? x 4]
#> # Database: DuckDB v0.10.2 [unknown@Linux 6.5.0-1018-azure:R 4.4.0/:memory:]
#>    cohort_definition_id subject_id cohort_start_date cohort_end_date
#>                   <int>      <int> <date>            <date>         
#>  1                    1         19 2018-12-25        2022-04-12     
#>  2                    1         61 2013-01-11        2013-01-11     
#>  3                    1         73 2021-03-10        2021-04-21     
#>  4                    1          5 1985-11-12        1988-11-17     
#>  5                    1         29 2004-02-04        2011-11-30     
#>  6                    1         87 2003-06-18        2012-03-25     
#>  7                    1         95 2012-04-22        2015-05-12     
#>  8                    1        123 1989-09-03        1989-11-28     
#>  9                    1         20 1999-01-09        2010-07-15     
#> 10                    1         98 2017-05-27        2018-08-10     
#> # ℹ more rows

cohortCount(cdm$simvastin_1)
#> # A tibble: 1 × 3
#>   cohort_definition_id number_records number_subjects
#>                  <int>          <int>           <int>
#> 1                    1            109              99

attrition(cdm$simvastin_1)
#> # A tibble: 1 × 7
#>   cohort_definition_id number_records number_subjects reason_id reason          
#>                  <int>          <int>           <int>     <int> <chr>           
#> 1                    1            109              99         1 Initial qualify…
#> # ℹ 2 more variables: excluded_records <int>, excluded_subjects <int>

imputeDuration and durationRange parameters

The parameter durationRange specifies the range within which the duration must fall, where duration will be calculated as:

duration = cohort_end_date - cohort_start_date + 1

The default value is c(1, Inf). See that this parameter must be a numeric vector of length two, with no NAs and with the first value equal or bigger than the second one. Duration values outside of durationRange will be imputed using imputeDuration. imputeDuration can be set as: none(default), median, mean, mode or an integer (count).

cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_2",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf) # default as c(1, Inf)
)

attrition(cdm$simvastin_2)
#> # A tibble: 1 × 7
#>   cohort_definition_id number_records number_subjects reason_id reason          
#>                  <int>          <int>           <int>     <int> <chr>           
#> 1                    1            109              99         1 Initial qualify…
#> # ℹ 2 more variables: excluded_records <int>, excluded_subjects <int>

gapEra paratemer

The gapEra parameter defines the number of days between two continuous drug exposures to be considered as a same era. Now let’s change it from 0 to a larger number to see what happens.

cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_3",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 30 # default as 0
)

attrition(cdm$simvastin_3) %>% select(number_records, reason, excluded_records, excluded_subjects)
#> # A tibble: 2 × 4
#>   number_records reason                       excluded_records excluded_subjects
#>            <int> <chr>                                   <int>             <int>
#> 1            109 Initial qualifying events                   0                 0
#> 2            107 join exposures separated by…                2                 0

From the simvastin_3 cohort attrition, we can see that when joining eras, it resulted in less records, compared to the simvastin_2 cohort, as exposures with less than 30 days gaps are joined.

priorUseWashout parameter

The priorUseWashout parameter specifies the number of prior days without exposure (often termed as ‘washout’) that are required. By default, it is set to NULL, meaning no washout period is necessary. See that when increasing this value, the number of records decrease.

cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_4",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 30,
  priorUseWashout = 30
)

attrition(cdm$simvastin_4) %>% select(number_records, reason, excluded_records, excluded_subjects)
#> # A tibble: 3 × 4
#>   number_records reason                       excluded_records excluded_subjects
#>            <int> <chr>                                   <int>             <int>
#> 1            109 Initial qualifying events                   0                 0
#> 2            107 join exposures separated by…                2                 0
#> 3            107 require prior use washout o…                0                 0

priorObservation parameter

The parameter priorObservation defines the minimum number of days of prior observation necessary for drug eras to be taken into account. If set to NULL, the drug eras are not required to fall within the observation_period.

cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_5",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 30,
  priorUseWashout = 30,
  priorObservation = 30
)

attrition(cdm$simvastin_5) %>% select(number_records, reason, excluded_records, excluded_subjects)
#> # A tibble: 4 × 4
#>   number_records reason                       excluded_records excluded_subjects
#>            <int> <chr>                                   <int>             <int>
#> 1            109 Initial qualifying events                   0                 0
#> 2            107 join exposures separated by…                2                 0
#> 3            107 require prior use washout o…                0                 0
#> 4             99 require at least 30 prior o…                8                 8

cohortDateRange parameter

The cohortDateRange parameter defines the range for the cohort_start_date and cohort_end_date.

cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_6",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 30,
  priorUseWashout = 30,
  priorObservation = 30,
  cohortDateRange = as.Date(c("2010-01-01", "2011-01-01"))
)

attrition(cdm$simvastin_6) %>% select(number_records, reason, excluded_records, excluded_subjects)
#> # A tibble: 6 × 4
#>   number_records reason                       excluded_records excluded_subjects
#>            <int> <chr>                                   <int>             <int>
#> 1            109 Initial qualifying events                   0                 0
#> 2            107 join exposures separated by…                2                 0
#> 3            107 require prior use washout o…                0                 0
#> 4             99 require at least 30 prior o…                8                 8
#> 5             66 restrict cohort_start_date …               33                30
#> 6             13 restrict cohort_end_date on…               53                48

limit parameter

The input limit allows all (default) and first options. If we set it to first, we will only obtain the first record that fulfills all the criteria. Observe how it impacts the attrition of the simvastin_7 in comparison to the simvastin_6 cohort. The number of records has decreased because of the First limit.

cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_7",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 30,
  priorUseWashout = 30,
  priorObservation = 30,
  cohortDateRange = as.Date(c("2010-01-01", "2011-01-01")),
  limit = "First"
)

attrition(cdm$simvastin_7) %>% select(number_records, reason, excluded_records, excluded_subjects)
#> # A tibble: 7 × 4
#>   number_records reason                       excluded_records excluded_subjects
#>            <int> <chr>                                   <int>             <int>
#> 1            109 Initial qualifying events                   0                 0
#> 2            107 join exposures separated by…                2                 0
#> 3            107 require prior use washout o…                0                 0
#> 4             99 require at least 30 prior o…                8                 8
#> 5             66 restrict cohort_start_date …               33                30
#> 6             13 restrict cohort_end_date on…               53                48
#> 7             13 restric to first record                     0                 0

If we just wanted to get the first-ever era, we can also use this parameter. To achieve that, try the following setting:

cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_8",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 0,
  priorUseWashout = Inf,
  priorObservation = 0,
  cohortDateRange = as.Date(c(NA, NA)),
  limit = "First"
)

Constructing concept sets and generating various cohorts are the initial steps in conducting a drug utilisation study. For further guidance on using getting more information like characteristics from these cohorts, please refer to the other vignettes.

Marti Catala, Mike Du, Yuchen Guo, Kim Lopez-Guell, Edward Burn, Xintong Li

2024-05-14