Learn R Programming

DrugUtilisation

Package overview

DrugUtilisation contains functions to instantiate and characterise drug cohorts in data mapped to the OMOP Common Data Model. The package supports:

  • Creation of drug cohorts

  • Identification of indications for those in a drug cohort

  • Summarising drug utilisation among a cohort in terms of duration, quantity, and dose

  • Description of treatment adherence based on proportion of patients covered

  • Detailing treatment restart and switching after an initial treatment discontinuation

Example usage

First, we need to create a cdm reference for the data we´ll be using. Here we generate an example with simulated data, but to see how you would set this up for your database please consult the CDMConnector package connection examples.

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

cdm <- mockDrugUtilisation(numberIndividual = 100)

Create a cohort of acetaminophen users

To generate the cohort of acetaminophen users we will use generateIngredientCohortSet, concatenating any records with fewer than 7 days between them. We then filter our cohort records to only include the first record per person and require that they have at least 30 days observation in the database prior to their drug start date.

cdm <- generateIngredientCohortSet(
  cdm = cdm,
  name = "dus_cohort",
  ingredient = "acetaminophen",
  gapEra = 7
)
cdm$dus_cohort |>
  requireIsFirstDrugEntry() |>
  requireObservationBeforeDrug(days = 30)
#> # Source:   table<dus_cohort> [?? x 4]
#> # Database: DuckDB v1.2.0 [root@Darwin 24.4.0:R 4.4.1/:memory:]
#>    cohort_definition_id subject_id cohort_start_date cohort_end_date
#>                   <int>      <int> <date>            <date>         
#>  1                    1         19 2015-03-30        2015-08-24     
#>  2                    1         24 2004-05-12        2005-10-17     
#>  3                    1         27 2008-05-25        2010-11-30     
#>  4                    1          3 2011-10-10        2014-04-19     
#>  5                    1         47 2009-05-20        2013-10-09     
#>  6                    1         51 2022-07-23        2022-07-24     
#>  7                    1         73 2008-11-23        2012-08-16     
#>  8                    1         31 2003-11-05        2005-03-24     
#>  9                    1         17 2019-10-26        2020-12-19     
#> 10                    1         28 1966-11-26        1967-03-31     
#> # ℹ more rows

Indications of acetaminophen users

Now we´ve created our cohort we could first summarise the indications of the cohort. These indications will always be cohorts, so we first need to create them. Here we create two indication cohorts, one for headache and the other for influenza.

indications <- list(headache = 378253, influenza = 4266367)
cdm <- generateConceptCohortSet(cdm,
  conceptSet = indications,
  name = "indications_cohort"
)

We can summarise the indication results using the summariseIndication function:

indication_summary <- cdm$dus_cohort |>
  summariseIndication(
    indicationCohortName = "indications_cohort",
    unknownIndicationTable = "condition_occurrence",
    indicationWindow = list(c(-30, 0))
  )
#> ℹ Intersect with indications table (indications_cohort)
#> ℹ Summarising indications.
indication_summary |> glimpse()
#> Rows: 12
#> Columns: 13
#> $ result_id        <int> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1
#> $ cdm_name         <chr> "DUS MOCK", "DUS MOCK", "DUS MOCK", "DUS MOCK", "DUS …
#> $ group_name       <chr> "cohort_name", "cohort_name", "cohort_name", "cohort_…
#> $ group_level      <chr> "acetaminophen", "acetaminophen", "acetaminophen", "a…
#> $ strata_name      <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ strata_level     <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ variable_name    <chr> "Indication from 30 days before to the index date", "…
#> $ variable_level   <chr> "headache", "headache", "influenza", "influenza", "he…
#> $ estimate_name    <chr> "count", "percentage", "count", "percentage", "count"…
#> $ estimate_type    <chr> "integer", "percentage", "integer", "percentage", "in…
#> $ estimate_value   <chr> "9", "16.0714285714286", "7", "12.5", "6", "10.714285…
#> $ additional_name  <chr> "window_name", "window_name", "window_name", "window_…
#> $ additional_level <chr> "-30 to 0", "-30 to 0", "-30 to 0", "-30 to 0", "-30 …

Drug use

We can quickly obtain a summary of drug utilisation among our cohort, with various measures calculated for a provided ingredient concept (in this case the concept for acetaminophen).

drug_utilisation_summary <- cdm$dus_cohort |>
  summariseDrugUtilisation(
    ingredientConceptId = 1125315,
    gapEra = 7
  )
drug_utilisation_summary |> glimpse()
#> Rows: 72
#> Columns: 13
#> $ result_id        <int> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,…
#> $ cdm_name         <chr> "DUS MOCK", "DUS MOCK", "DUS MOCK", "DUS MOCK", "DUS …
#> $ group_name       <chr> "cohort_name", "cohort_name", "cohort_name", "cohort_…
#> $ group_level      <chr> "acetaminophen", "acetaminophen", "acetaminophen", "a…
#> $ strata_name      <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ strata_level     <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ variable_name    <chr> "number records", "number subjects", "number exposure…
#> $ variable_level   <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N…
#> $ estimate_name    <chr> "count", "count", "q25", "median", "q75", "mean", "sd…
#> $ estimate_type    <chr> "integer", "integer", "integer", "integer", "integer"…
#> $ estimate_value   <chr> "56", "56", "1", "1", "1", "1.21428571428571", "0.494…
#> $ additional_name  <chr> "overall", "overall", "concept_set", "concept_set", "…
#> $ additional_level <chr> "overall", "overall", "ingredient_1125315_descendants…
table(drug_utilisation_summary$variable_name)
#> 
#>    cumulative dose milligram          cumulative quantity 
#>                            7                            7 
#>                 days exposed              days prescribed 
#>                            7                            7 
#> initial daily dose milligram    initial exposure duration 
#>                            7                            7 
#>             initial quantity                  number eras 
#>                            7                            7 
#>             number exposures               number records 
#>                            7                            1 
#>              number subjects             time to exposure 
#>                            1                            7

Combine and share results

Now we can combine our results and suppress any counts less than 5 so that they are ready to be shared.

results <- bind(
  indication_summary,
  drug_utilisation_summary
) |>
  suppress(minCellCount = 5)
results |> glimpse()
#> Rows: 84
#> Columns: 13
#> $ result_id        <int> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2,…
#> $ cdm_name         <chr> "DUS MOCK", "DUS MOCK", "DUS MOCK", "DUS MOCK", "DUS …
#> $ group_name       <chr> "cohort_name", "cohort_name", "cohort_name", "cohort_…
#> $ group_level      <chr> "acetaminophen", "acetaminophen", "acetaminophen", "a…
#> $ strata_name      <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ strata_level     <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ variable_name    <chr> "Indication from 30 days before to the index date", "…
#> $ variable_level   <chr> "headache", "headache", "influenza", "influenza", "he…
#> $ estimate_name    <chr> "count", "percentage", "count", "percentage", "count"…
#> $ estimate_type    <chr> "integer", "percentage", "integer", "percentage", "in…
#> $ estimate_value   <chr> "9", "16.0714285714286", "7", "12.5", "6", "10.714285…
#> $ additional_name  <chr> "window_name", "window_name", "window_name", "window_…
#> $ additional_level <chr> "-30 to 0", "-30 to 0", "-30 to 0", "-30 to 0", "-30 …

Further analyses

There are many more drug-related analyses that we could have done with this acetaminophen cohort using the DrugUtilisation package. Please see the package website for more details.

Copy Link

Version

Install

install.packages('DrugUtilisation')

Monthly Downloads

753

Version

1.0.2

License

Apache License (>= 2)

Maintainer

Marti Catala

Last Published

May 13th, 2025

Functions in DrugUtilisation (1.0.2)

conceptSetDoc

Helper for consistent documentation of conceptSet.
generateDrugUtilisationCohortSet

Generate a set of drug cohorts based on given concepts
compNameDoc

Helper for consistent documentation of name for computed tables.
cohortIdDoc

Helper for consistent documentation of cohortId.
generateIngredientCohortSet

Generate a set of drug cohorts based on drug ingredients
plotTreatment

Generate a custom ggplot2 from a summarised_result object generated with summariseTreatment function.
plotProportionOfPatientsCovered

Plot proportion of patients covered
numberExposuresDoc

Helper for consistent documentation of numberExposures.
newNameDoc

Helper for consistent documentation of name for new cohorts.
plotIndication

Generate a plot visualisation (ggplot2) from the output of summariseIndication
gapEraDoc

Helper for consistent documentation of gapEra.
plotDrugUtilisation

Plot the results of summariseDrugUtilisation
generateAtcCohortSet

Generate a set of drug cohorts based on ATC classification
mockDrugUtilisation

It creates a mock database for testing DrugUtilisation package
erafyCohort

Erafy a cohort_table collapsing records separated gapEra days or less.
plotDrugRestart

Generate a custom ggplot2 from a summarised_result object generated with summariseDrugRestart() function.
requirePriorDrugWashout

Restrict cohort to only cohort records with a given amount of time since the last cohort record ended
daysPrescribedDoc

Helper for consistent documentation of daysPrescribed.
plotDoc

Helper for consistent documentation of plot.
restrictIncidentDoc

Helper for consistent documentation of restrictIncident.
reexports

Objects exported from other packages
nameStyleDoc

Helper for consistent documentation of nameStyle.
drugUtilisationDoc

Helper for consistent documentation of add/summariseDrugUtilisation functions.
summariseIndication

Summarise the indications of individuals in a drug cohort
summariseDrugUtilisation

This function is used to summarise the dose utilisation table over multiple cohorts.
tableDrugRestart

Format a drug_restart object into a visual table.
indexDateDoc

Helper for consistent documentation of indexDate.
strataDoc

Helper for consistent documentation of strata.
resultDoc

Helper for consistent documentation of result.
patternTable

Function to create a tibble with the patterns from current drug strength table
benchmarkDrugUtilisation

Run benchmark of drug utilisation cohort generation
summariseTreatment

This function is used to summarise treatments received
summariseProportionOfPatientsCovered

Summarise proportion Of patients covered
patternsWithFormula

Patterns valid to compute daily dose with the associated formula.
tableDrugUtilisation

Format a drug_utilisation object into a visual table.
requireIsFirstDrugEntry

Restrict cohort to only the first cohort record per subject
requireObservationBeforeDrug

Restrict cohort to only cohort records with the given amount of prior observation time in the database
requireDrugInDateRange

Restrict cohort to only cohort records within a certain date range
tableTreatment

Format a summarised_treatment result into a visual table.
summariseDoseCoverage

Check coverage of daily dose computation in a sample of the cdm for selected concept sets and ingredient
ingredientConceptIdDoc

Helper for consistent documentation of ingredientConceptId.
tableDoc

Helper for consistent documentation of table.
tableProportionOfPatientsCovered

Create a table with proportion of patients covered results
summariseDrugRestart

Summarise the drug restart for each follow-up period of interest.
tableIndication

Create a table showing indication results
tableDoseCoverage

Format a dose_coverage object into a visual table.
addDrugUtilisation

Add new columns with drug use related information
addInitialDailyDose

To add a new column with the initial daily dose. To add multiple columns use addDrugUtilisation() for efficiency.
addDaysExposed

To add a new column with the days exposed. To add multiple columns use addDrugUtilisation() for efficiency.
addDrugRestart

Add drug restart information as a column per follow-up period of interest.
addDaysPrescribed

To add a new column with the days prescribed. To add multiple columns use addDrugUtilisation() for efficiency.
addCumulativeDose

To add a new column with the cumulative dose. To add multiple columns use addDrugUtilisation() for efficiency.
DrugUtilisation-package

DrugUtilisation: Summarise Patient-Level Drug Utilisation in Data Mapped to the OMOP Common Data Model
addInitialExposureDuration

To add a new column with the duration of the first exposure. To add multiple columns use addDrugUtilisation() for efficiency.
addIndication

Add a variable indicating individuals indications
addCumulativeQuantity

To add a new column with the cumulative quantity. To add multiple columns use addDrugUtilisation() for efficiency.
addNumberExposures

To add a new column with the number of exposures. To add multiple columns use addDrugUtilisation() for efficiency.
addInitialQuantity

To add a new column with the initial quantity. To add multiple columns use addDrugUtilisation() for efficiency.
addTimeToExposure

To add a new column with the time to exposure. To add multiple columns use addDrugUtilisation() for efficiency.
cohortGapEra

Get the gapEra used to create a cohort
addTreatment

Add a variable indicating individuals medications
cohortDoc

Helper for consistent documentation of cohort.
cdmDoc

Helper for consistent documentation of cdm.
addNumberEras

To add a new column with the number of eras. To add multiple columns use addDrugUtilisation() for efficiency.
censorDateDoc

Helper for consistent documentation of censorDate.