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

607

Version

1.0.3

License

Apache License (>= 2)

Maintainer

Marti Catala

Last Published

June 3rd, 2025

Functions in DrugUtilisation (1.0.3)

addNumberEras

To add a new column with the number of eras. 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.
addTreatment

Add a variable indicating individuals medications
cdmDoc

Helper for consistent documentation of cdm.
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
censorDateDoc

Helper for consistent documentation of censorDate.
cohortDoc

Helper for consistent documentation of cohort.
conceptSetDoc

Helper for consistent documentation of conceptSet.
daysPrescribedDoc

Helper for consistent documentation of daysPrescribed.
compNameDoc

Helper for consistent documentation of name for computed tables.
cohortIdDoc

Helper for consistent documentation of cohortId.
requireIsFirstDrugEntry

Restrict cohort to only the first cohort record per subject
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.
generateIngredientCohortSet

Generate a set of drug cohorts based on drug ingredients
generateDrugUtilisationCohortSet

Generate a set of drug cohorts based on given concepts
mockDrugUtilisation

It creates a mock database for testing DrugUtilisation package
patternTable

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

Helper for consistent documentation of gapEra.
nameStyleDoc

Helper for consistent documentation of nameStyle.
plotDoc

Helper for consistent documentation of plot.
plotTreatment

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

Plot proportion of patients covered
generateAtcCohortSet

Generate a set of drug cohorts based on ATC classification
requireObservationBeforeDrug

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

Summarise proportion Of patients covered
patternsWithFormula

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

Helper for consistent documentation of indexDate.
ingredientConceptIdDoc

Helper for consistent documentation of ingredientConceptId.
drugUtilisationDoc

Helper for consistent documentation of add/summariseDrugUtilisation functions.
reexports

Objects exported from other packages
requireDrugInDateRange

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

Helper for consistent documentation of strata.
resultDoc

Helper for consistent documentation of result.
tableDoc

Helper for consistent documentation of table.
summariseDrugRestart

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

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

Format a drug_restart object into a visual table.
tableDrugUtilisation

Format a drug_utilisation object into a visual table.
plotDrugUtilisation

Plot the results of summariseDrugUtilisation
tableDoseCoverage

Format a dose_coverage object into a visual table.
newNameDoc

Helper for consistent documentation of name for new cohorts.
requirePriorDrugWashout

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

Summarise the indications of individuals in a drug cohort
summariseDrugUtilisation

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

Helper for consistent documentation of numberExposures.
restrictIncidentDoc

Helper for consistent documentation of restrictIncident.
tableIndication

Create a table showing indication results
tableTreatment

Format a summarised_treatment result into a visual table.
plotIndication

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

Create a table with proportion of patients covered results
summariseTreatment

This function is used to summarise treatments received
addInitialDailyDose

To add a new column with the initial daily dose. To add multiple columns use addDrugUtilisation() for efficiency.
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
addDaysExposed

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

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

Add new columns with drug use related information
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
addNumberExposures

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

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

Run benchmark of drug utilisation cohort generation
addDrugRestart

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