Skip to contents

Introduction

The DrugUtilisation package includes a range of functions that add drug-related information of subjects in OMOP CDM tables and cohort tables. In this vignette, we will explore these functions and provide some examples for its usage.

Create mock data first

Create a drug utilisation cohort

We will use Acetaminophen as our example drug to construct our drug utilisation cohort. To begin, we will employ getDrugIngredientCodes() function from CodelistGenerator to generate a concept list associated with Acetaminophen.

conceptList <- getDrugIngredientCodes(cdm, c("acetaminophen"))
conceptList
#> 
#> - 161_acetaminophen (4 codes)

Next, we create a drug utilisation cohort by using the conceptList with the generateDrugUtilisationCohortSet() function. For a better understanding of the arguments and functionalities of generateDrugUtilisationCohortSet(), please refer to the Use DrugUtilisation to create a cohort vignette.

cdm <- generateDrugUtilisationCohortSet(
  cdm  = cdm,
  name = "acetaminophen_example1",
  conceptSet = conceptList
)

Adding routes with addRoute() function

addRoute() function utilises an internal CSV file containing all possible routes for various drug dose forms supported by the package. The function is designed to seamlessly incorporate route information into your drug table for the supported dose forms. See the example below to know how it works.

cdm[["drug_exposure"]] |>
  addRoute() 
#> # Source:   SQL [?? x 8]
#> # Database: DuckDB v1.0.0 [unknown@Linux 6.5.0-1024-azure:R 4.4.1/:memory:]
#>    drug_exposure_id person_id drug_concept_id drug_exposure_start_date
#>               <int>     <int>           <dbl> <date>                  
#>  1                1         1         1125360 2004-02-21              
#>  2                2         1         1125360 2002-12-25              
#>  3                3         2         1539463 2015-12-30              
#>  4                5         2         1516978 2016-03-28              
#>  5                6         3        43135274 2001-11-18              
#>  6                8         3        43135274 2002-01-20              
#>  7               11         4         1125360 2009-04-13              
#>  8               12         4         1516978 2007-12-26              
#>  9               14         4         1503328 2010-07-25              
#> 10               15         4        43135274 2009-07-17              
#> # ℹ more rows
#> # ℹ 4 more variables: drug_exposure_end_date <date>,
#> #   drug_type_concept_id <dbl>, quantity <dbl>, route <chr>

Generating patterns with patternTable() function

The patternTable() function in the DrugUtilisation package is a powerful tool for deriving patterns from a drug strength table. This function extracts distinct patterns, associating them with pattern_id and formula_id. The resulting tibble provides the following data:

  • number_concepts: the count of distinct concepts in the patterns.
  • number_ingredients: the count of distinct ingredients involved.
  • number_records: the overall count of records in the patterns.

Moreover, the tibble includes a column indicating potentially valid and invalid combinations.

patternTable(cdm)
#> # A tibble: 5 × 12
#>   pattern_id formula_name            validity number_concepts number_ingredients
#>        <dbl> <chr>                   <chr>              <dbl>              <dbl>
#> 1          9 fixed amount formulati… pattern…               7                  4
#> 2         18 concentration formulat… pattern…               1                  1
#> 3         24 concentration formulat… pattern…               1                  1
#> 4         40 concentration formulat… pattern…               1                  1
#> 5         NA NA                      no patt…               4                  4
#> # ℹ 7 more variables: number_records <dbl>, amount_numeric <dbl>,
#> #   amount_unit_concept_id <dbl>, numerator_numeric <dbl>,
#> #   numerator_unit_concept_id <dbl>, denominator_numeric <dbl>,
#> #   denominator_unit_concept_id <dbl>

For detailed information about the patterns, their associated formula, and combinations of amount_unit, numerator_unit, and denominator_unit, you can refer to the data:

patternsWithFormula

Get daily dose with addDailyDose() function

Now that we have all the patterns and formulas supported, the computation of daily doses can be performed using the addDailyDose() function. This function will add to the data with additional columns, including those for quantity, daily dose, unit, and route.

addDailyDose(
  cdm$drug_exposure,
  ingredientConceptId = 1125315
)
#> Warning: `addDailyDose()` was deprecated in DrugUtilisation 0.7.0.
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.
#> # Source:   table<og_009_1722100802> [?? x 9]
#> # Database: DuckDB v1.0.0 [unknown@Linux 6.5.0-1024-azure:R 4.4.1/:memory:]
#>    drug_exposure_id person_id drug_concept_id drug_exposure_start_date
#>               <int>     <int>           <dbl> <date>                  
#>  1                2         1         1125360 2002-12-25              
#>  2                6         3        43135274 2001-11-18              
#>  3                8         3        43135274 2002-01-20              
#>  4               11         4         1125360 2009-04-13              
#>  5               15         4        43135274 2009-07-17              
#>  6               18         5        43135274 2022-11-05              
#>  7               22         6         2905077 2013-09-22              
#>  8               26         8         1125360 1999-12-06              
#>  9               27         8        43135274 1998-09-26              
#> 10               28         8         2905077 1992-02-17              
#> # ℹ more rows
#> # ℹ 5 more variables: drug_exposure_end_date <date>,
#> #   drug_type_concept_id <dbl>, quantity <dbl>, daily_dose <dbl>, unit <chr>

There is also a function, summariseDoseCoverage(), to check the coverage of daily dose computation for chosen concept sets and ingredients.

summariseDoseCoverage(cdm, 1125315)
#>  The following estimates will be computed:
#>  daily_dose: count_missing, percentage_missing, mean, sd, q25, median, q75
#> ! Table is collected to memory as not all requested estimates are supported on
#>   the database side
#> → Start summary of data, at 2024-07-27 17:20:03.060474
#> 
#>  Summary finished, at 2024-07-27 17:20:03.324915
#> # A tibble: 56 × 13
#>    result_id cdm_name group_name      group_level   strata_name strata_level
#>        <int> <chr>    <chr>           <chr>         <chr>       <chr>       
#>  1         1 DUS MOCK ingredient_name acetaminophen overall     overall     
#>  2         1 DUS MOCK ingredient_name acetaminophen overall     overall     
#>  3         1 DUS MOCK ingredient_name acetaminophen overall     overall     
#>  4         1 DUS MOCK ingredient_name acetaminophen overall     overall     
#>  5         1 DUS MOCK ingredient_name acetaminophen overall     overall     
#>  6         1 DUS MOCK ingredient_name acetaminophen overall     overall     
#>  7         1 DUS MOCK ingredient_name acetaminophen overall     overall     
#>  8         1 DUS MOCK ingredient_name acetaminophen overall     overall     
#>  9         1 DUS MOCK ingredient_name acetaminophen unit        milligram   
#> 10         1 DUS MOCK ingredient_name acetaminophen unit        milligram   
#> # ℹ 46 more rows
#> # ℹ 7 more variables: variable_name <chr>, variable_level <chr>,
#> #   estimate_name <chr>, estimate_type <chr>, estimate_value <chr>,
#> #   additional_name <chr>, additional_level <chr>

Adding Drug Usage Details to a Cohort with addDrugUse() function

Additional drug usage details, including duration, initial dose, cumulative dose, etc., can be incorporated into a cohort using the addDrugUse() function.

cdm$acetaminophen_example1 |>
  addDrugUse(ingredientConceptId = 1125315)
#> # Source:   table<og_016_1722100813> [?? x 13]
#> # Database: DuckDB v1.0.0 [unknown@Linux 6.5.0-1024-azure:R 4.4.1/:memory:]
#>    cohort_definition_id subject_id cohort_start_date cohort_end_date duration
#>                   <int>      <int> <date>            <date>             <dbl>
#>  1                    1         90 1987-04-12        1992-08-14          1952
#>  2                    1         64 2013-02-16        2014-11-05           628
#>  3                    1        124 2022-06-28        2022-09-27            92
#>  4                    1         76 2018-01-28        2020-06-16           871
#>  5                    1         45 2020-04-28        2020-12-27           244
#>  6                    1        157 2000-03-11        2008-08-22          3087
#>  7                    1         57 2012-01-23        2013-04-05           439
#>  8                    1        144 2014-04-22        2014-04-22             1
#>  9                    1        188 2021-08-11        2021-10-29            80
#> 10                    1        189 2018-07-01        2018-10-21           113
#> # ℹ more rows
#> # ℹ 8 more variables: number_exposures <dbl>, cumulative_quantity <dbl>,
#> #   initial_quantity <dbl>, impute_duration_percentage <dbl>,
#> #   number_eras <dbl>, impute_daily_dose_percentage <dbl>,
#> #   initial_daily_dose_milligram <dbl>, cumulative_dose_milligram <dbl>

duration parameter

The duration parameter is a boolean variable (TRUE/FALSE) determining whether to include duration related columns, which correspond to:

  1. duration: duration is calculated as cohort_end_date - cohort_start_date + 1.
  2. impute_duration_percentage: if a drug exposure record does not have the duration of the exposure, or falls outside the specified duration range, duration will be imputed. The number of records that have been imputed or that would have been imputed (if we choose not to impute the duration) is recorded in this column.

To set the imputation method for duration, use the imputeDuration input, which can take values such as none (default), median, mode or a numerical value. Define the durationRange parameter as a numeric vector of length two, where the first value should be equal or smaller than the second one. If set to NULL, no restrictions are applied.

quantity parameter

The quantity parameter, another boolean variable (TRUE/FALSE), controls the inclusion of quantity-related columns. If set to TRUE (default), the following columns are added:

  1. cumulative_quantity: cumulative sum of the column quantity of the drug_exposure table during the drug exposure period.
  2. initial_quantity: quantity at drug_exposure_start_date.

dose parameter

The dose parameter, also a boolean variable (TRUE/FALSE), governs the addition of daily dose-related columns. When set to TRUE, the following columns are added:

  1. initial_daily_dose_milligram: dose at drug_exposure_start_date.
  2. cumulative_dose_milligram: cumulative sum of the column dose of drug_exposure table during the drug exposure period.
  3. impute_daily_dose_percentage: If daily dose is missing, or falls outside the imputation range, records will be imputed. This column shows the number of records that have been imputed or that would have been imputed (if we choose not to impute the daily dose).

Similar to duration imputation, use the imputeDose parameter to set the method for imputing daily dose, with options like none (default), median, mean, mode. Define the imputation range with the dailyDoseRange parameter, a numeric vector of length two, where the first value should be equal or smaller than the second one. If set to NULL, no restrictions are applied.

These parameters offer flexibility in customizing the drug usage details added to the cohort. See the next example, where we use the cohort created at the beginning of this vignette acetaminophen_example1.

addDrugUse(
  cohort = cdm[["acetaminophen_example1"]],
  cdm    = cdm,
  ingredientConceptId = 1125315,
  duration = TRUE,
  quantity = TRUE,
  dose     = TRUE
)
#> # Source:   table<og_021_1722100824> [?? x 13]
#> # Database: DuckDB v1.0.0 [unknown@Linux 6.5.0-1024-azure:R 4.4.1/:memory:]
#>    cohort_definition_id subject_id cohort_start_date cohort_end_date duration
#>                   <int>      <int> <date>            <date>             <dbl>
#>  1                    1        112 2022-08-14        2022-08-17             4
#>  2                    1        163 1978-09-21        1978-11-10            51
#>  3                    1        185 2000-12-10        2007-07-09          2403
#>  4                    1         56 2017-04-06        2018-02-19           320
#>  5                    1          5 2022-11-05        2022-11-05             1
#>  6                    1         74 2008-04-12        2017-12-05          3525
#>  7                    1         68 2001-07-14        2003-10-23           832
#>  8                    1         29 2022-12-15        2022-12-15             1
#>  9                    1        158 2015-05-02        2019-09-14          1597
#> 10                    1        192 1983-10-31        1984-04-22           175
#> # ℹ more rows
#> # ℹ 8 more variables: number_exposures <dbl>, cumulative_quantity <dbl>,
#> #   initial_quantity <dbl>, impute_duration_percentage <dbl>,
#> #   number_eras <dbl>, impute_daily_dose_percentage <dbl>,
#> #   initial_daily_dose_milligram <dbl>, cumulative_dose_milligram <dbl>

If all these parameters are set to false, only number_exposures and number_eras will be added.

Parameters for Joining Exposures

The way continuous exposures are joined can be configured by using different parameters. Let’s have a look to all the options we have.

gapEra parameter

This parameter sets the number of days between two continuous exposures to be considered in the same era. If the previous exposure’s end date minus the next exposure’s start date is less than or equal to the specified gapEra, these two exposures will be joined. Let’s see an illustrative example.

First, let’s create a cohort with gapEra = 0. For a better understanding, we will observe only subject number 56.

cdm <- generateDrugUtilisationCohortSet(
  cdm = cdm,
  name = "acetaminophen_example2",
  conceptSet = conceptList,
  gapEra = 0
)
 
cdm$drug_exposure |>
  filter(drug_concept_id %in% !!conceptList$acetaminophen) |>
  filter(person_id == 56)
#> # Source:   SQL [0 x 7]
#> # Database: DuckDB v1.0.0 [unknown@Linux 6.5.0-1024-azure:R 4.4.1/:memory:]
#> # ℹ 7 variables: drug_exposure_id <int>, person_id <int>,
#> #   drug_concept_id <dbl>, drug_exposure_start_date <date>,
#> #   drug_exposure_end_date <date>, drug_type_concept_id <dbl>, quantity <dbl>

This subject has two different drug exposure periods separated by less than 6 months. Hence, it has two different cohort periods:

cdm[["acetaminophen_example2"]] |>
  addDrugUse(
    ingredientConceptId = 1125315,
    gapEra = 0
  ) |>
  filter(subject_id == 56)
#> # Source:   SQL [2 x 13]
#> # Database: DuckDB v1.0.0 [unknown@Linux 6.5.0-1024-azure:R 4.4.1/:memory:]
#>   cohort_definition_id subject_id cohort_start_date cohort_end_date duration
#>                  <int>      <int> <date>            <date>             <dbl>
#> 1                    1         56 2017-04-06        2018-02-19           320
#> 2                    1         56 2019-08-11        2019-09-26            47
#> # ℹ 8 more variables: number_exposures <dbl>, cumulative_quantity <dbl>,
#> #   initial_quantity <dbl>, impute_duration_percentage <dbl>,
#> #   number_eras <dbl>, impute_daily_dose_percentage <dbl>,
#> #   initial_daily_dose_milligram <dbl>, cumulative_dose_milligram <dbl>

Now, we merge this two periods by modifying the gapEra input when creating the cohort. For a better understanding of gapEra arguments and functionalities, please see Use DrugUtilisation to create a cohort vignette.

cdm <- generateDrugUtilisationCohortSet(
  cdm = cdm,
  name = "acetaminophen_example3",
  conceptSet = conceptList,
  gapEra = 180
)

cdm$acetaminophen_example3 |>
  addDrugUse(
    ingredientConceptId = 1125315,
    gapEra = 180,
    duration = TRUE,
    quantity = FALSE,
    dose = FALSE
  ) |>
  filter(subject_id == 56) 
#> # Source:   SQL [2 x 8]
#> # Database: DuckDB v1.0.0 [unknown@Linux 6.5.0-1024-azure:R 4.4.1/:memory:]
#>   cohort_definition_id subject_id cohort_start_date cohort_end_date duration
#>                  <int>      <int> <date>            <date>             <dbl>
#> 1                    1         56 2017-04-06        2018-02-19           320
#> 2                    1         56 2019-08-11        2019-09-26            47
#> # ℹ 3 more variables: number_exposures <dbl>, impute_duration_percentage <dbl>,
#> #   number_eras <dbl>

See that we only have one record with two exposures for subject number 56. Note that the number of eras is still 1, as we have defined the same gapEra as when the cohort was created. However, it is possible to specify a different gapEra than the one defined when the cohort was created.

cdm$acetaminophen_example3 |>
  addDrugUse(
    ingredientConceptId = 1125315,
    gapEra = 0
  ) |>
  filter(subject_id == 56) 
#> # Source:   SQL [2 x 13]
#> # Database: DuckDB v1.0.0 [unknown@Linux 6.5.0-1024-azure:R 4.4.1/:memory:]
#>   cohort_definition_id subject_id cohort_start_date cohort_end_date duration
#>                  <int>      <int> <date>            <date>             <dbl>
#> 1                    1         56 2017-04-06        2018-02-19           320
#> 2                    1         56 2019-08-11        2019-09-26            47
#> # ℹ 8 more variables: number_exposures <dbl>, cumulative_quantity <dbl>,
#> #   initial_quantity <dbl>, impute_duration_percentage <dbl>,
#> #   number_eras <dbl>, impute_daily_dose_percentage <dbl>,
#> #   initial_daily_dose_milligram <dbl>, cumulative_dose_milligram <dbl>

Notice that number_eras now indicates that we have two eras within the same record.

eraJoinMode parameter

This parameter defines how two different continuous exposures are joined in an era. There are four options:

  1. eraJoinMode = "zero" (default option): Exposures are joined considering that the period between both continuous exposures means the subject is treated with a daily dose of zero. The time between both exposures contributes to the total exposed time.
  2. eraJoinMode = "join": Exposures are joined, considering that the period between both continuous exposures means the subject is treated with a daily dose of zero. The time between both exposures does not contribute to the total exposed time.
  3. eraJoinMode = "previous": Exposures are joined, considering that the period between both continuous exposures means the subject is treated with the daily dose of the previous subexposure. The time between both exposures contributes to the total exposed time.
  4. eraJoinMode = "subsequent": Exposures are joined, considering that the period between both continuous exposures means the subject is treated with the daily dose of the subsequent subexposure. The time between both exposures contributes to the total exposed time.

overlapMode parameter

This parameter defines how the overlapping between two exposures that do not start on the same day is resolved inside a subexposure. There are five possible options:

  1. overlapMode* = "sum" (default): The considered daily dose is the sum of all the exposures present in the subexposure.
  2. overlapMode = minimum: The considered daily dose is the minimum of all the exposures in the subexposure.
  3. overlapMode = maximum: The considered daily dose is the maximum of all the exposures in the subexposure.
  4. overlapMode = previous: The considered daily dose is that of the earliest exposure.
  5. overlapMode = subsequent: The considered daily dose is that of the latest exposure.

sameIndexMode parameter

This parameter works similarly to overlapMode, but it customizes the overlapping between two exposures starting on the same date. It includes the options sum (default), minimum, and maximum described in overlapMode.

For example, the following example sets a maximum gap of 30 days for exposures to be joined. It uses the daily dose of the previous subexposure when joining exposures, employs the minimum daily dose for exposures starting on the same day, and considers the minimum daily dose for exposures that overlap.

cdm[["acetaminophen_example1"]] |>
  addDrugUse(ingredientConceptId = 1125315,
             gapEra = 30,
             eraJoinMode = "previous",
             overlapMode = "minimum",
             sameIndexMode = "minimum")
#> # Source:   table<og_040_1722100870> [?? x 13]
#> # Database: DuckDB v1.0.0 [unknown@Linux 6.5.0-1024-azure:R 4.4.1/:memory:]
#>    cohort_definition_id subject_id cohort_start_date cohort_end_date duration
#>                   <int>      <int> <date>            <date>             <dbl>
#>  1                    1         57 2012-01-23        2013-04-05           439
#>  2                    1        144 2014-04-22        2014-04-22             1
#>  3                    1        189 2018-07-01        2018-10-21           113
#>  4                    1        175 2022-09-27        2022-09-29             3
#>  5                    1        188 2021-08-11        2021-10-29            80
#>  6                    1        154 2018-07-11        2019-05-04           298
#>  7                    1          8 1992-02-17        2002-07-18          3805
#>  8                    1        197 2022-05-27        2022-06-15            20
#>  9                    1        180 2013-01-18        2014-09-05           596
#> 10                    1        107 2021-07-14        2021-07-14             1
#> # ℹ more rows
#> # ℹ 8 more variables: number_exposures <dbl>, cumulative_quantity <dbl>,
#> #   initial_quantity <dbl>, impute_duration_percentage <dbl>,
#> #   number_eras <dbl>, impute_daily_dose_percentage <dbl>,
#> #   initial_daily_dose_milligram <dbl>, cumulative_dose_milligram <dbl>

Summarise drug usage information with summariseDrugUse() function

This functions creates a tibble summarising the dose table across multiple cohorts. See an example below:

cdm[["acetaminophen_example1"]] <- cdm[["acetaminophen_example1"]] |> 
  addDrugUse(
    cdm = cdm,
    ingredientConceptId = 1125315
  )

summariseDrugUse(cdm[["acetaminophen_example1"]])
#> # A tibble: 101 × 13
#>    result_id cdm_name group_name  group_level       strata_name strata_level
#>        <int> <chr>    <chr>       <chr>             <chr>       <chr>       
#>  1         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  2         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  3         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  4         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  5         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  6         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  7         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  8         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  9         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#> 10         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#> # ℹ 91 more rows
#> # ℹ 7 more variables: variable_name <chr>, variable_level <chr>,
#> #   estimate_name <chr>, estimate_type <chr>, estimate_value <chr>,
#> #   additional_name <chr>, additional_level <chr>

strata parameter

We can also stratify our cohort and calculate the estimates within each strata group by using the strata parameter.

cdm[["acetaminophen_example1"]] <- cdm[["acetaminophen_example1"]] |>
  addSex() # Function from PatientProfiles

summariseDrugUse(cdm[["acetaminophen_example1"]],
                 strata = list("sex")) 
#> # A tibble: 303 × 13
#>    result_id cdm_name group_name  group_level       strata_name strata_level
#>        <int> <chr>    <chr>       <chr>             <chr>       <chr>       
#>  1         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  2         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  3         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  4         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  5         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  6         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  7         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  8         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#>  9         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#> 10         1 DUS MOCK cohort_name 161_acetaminophen overall     overall     
#> # ℹ 293 more rows
#> # ℹ 7 more variables: variable_name <chr>, variable_level <chr>,
#> #   estimate_name <chr>, estimate_type <chr>, estimate_value <chr>,
#> #   additional_name <chr>, additional_level <chr>

drugEstimates parameter

Customize the estimates to be calculated by using the drugEstimates parameter. By default, it will compute the minimum value, quartiles (5%, 25%, 50% - median, 75% and 95%), the maximum value, the mean, the standard deviation, and the number of missings values for each column added with addDrugUse().

minCellCount parameter

Specify the minimum number of individuals that a strata group must have in order to appear in the table.