Add drug related information to a Drug Utilisation cohort
TBR_add_drug_use.RmdIntroduction
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
library(DrugUtilisation)
library(CDMConnector)
library(dplyr)
library(PatientProfiles)
cdm <- mockDrugUtilisation(numberIndividual = 200)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:
patternsWithFormulaGet 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:
-
duration: duration is calculated ascohort_end_date - cohort_start_date + 1. -
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:
-
cumulative_quantity: cumulative sum of the columnquantityof thedrug_exposuretable during the drug exposure period. -
initial_quantity: quantity atdrug_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:
-
initial_daily_dose_milligram: dose atdrug_exposure_start_date. -
cumulative_dose_milligram: cumulative sum of the columndoseofdrug_exposuretable during the drug exposure period. -
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:
-
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. -
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. -
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. -
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:
-
overlapMode* = "sum"(default): The considered daily dose is the sum of all the exposures present in the subexposure. -
overlapMode = minimum: The considered daily dose is the minimum of all the exposures in the subexposure. -
overlapMode = maximum: The considered daily dose is the maximum of all the exposures in the subexposure. -
overlapMode = previous: The considered daily dose is that of the earliest exposure. -
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().