Learn R Programming
⚠️There's a newer version (1.0.1) of this package.Take me there.

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
)
#> Warning: ! `codelist` contains numeric values, they are casted to integers.
cdm$dus_cohort |>
  requireIsFirstDrugEntry() |>
  requireObservationBeforeDrug(days = 30)
#> # Source:   table<main.dus_cohort> [?? x 4]
#> # Database: DuckDB v1.1.0 [root@Darwin 24.0.0:R 4.4.1/:memory:]
#>    cohort_definition_id subject_id cohort_start_date cohort_end_date
#>                   <int>      <int> <date>            <date>         
#>  1                    1          1 2021-08-22        2022-01-20     
#>  2                    1          2 2003-04-08        2006-03-14     
#>  3                    1          4 1971-04-20        1971-08-01     
#>  4                    1          5 2010-10-12        2017-10-23     
#>  5                    1          6 2019-06-04        2019-11-06     
#>  6                    1          7 2011-11-30        2012-03-22     
#>  7                    1          8 1993-03-18        1996-08-09     
#>  8                    1         10 2009-08-21        2010-02-21     
#>  9                    1         11 2022-03-27        2022-07-13     
#> 10                    1         14 2010-12-27        2012-10-26     
#> # ℹ 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"
)
#> Warning: ! 3 casted column in indications_cohort (cohort_attrition) as do not match
#>   expected column type:
#> • `reason_id` from numeric to integer
#> • `excluded_records` from numeric to integer
#> • `excluded_subjects` from numeric to integer
#> Warning: ! 1 casted column in indications_cohort (cohort_codelist) as do not match
#>   expected column type:
#> • `concept_id` from numeric to integer

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))
  )
#> Getting specified indications
#> Creating indication summary variables
#> Getting unknown indications
#> Summarising indication results
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> "161_acetaminophen", "161_acetaminophen", "161_acetam…
#> $ strata_name      <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ strata_level     <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ variable_name    <chr> "number records", "number subjects", "Indication from…
#> $ variable_level   <chr> NA, NA, "headache", "headache", "influenza", "influen…
#> $ estimate_name    <chr> "count", "count", "count", "percentage", "count", "pe…
#> $ estimate_type    <chr> "integer", "integer", "integer", "percentage", "integ…
#> $ estimate_value   <chr> "61", "61", "1", "1.63934426229508", "0", "0", "0", "…
#> $ additional_name  <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ additional_level <chr> "overall", "overall", "overall", "overall", "overall"…

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
  )
#> Warning: ! `codelist` contains numeric values, they are casted to integers.
drug_utilisation_summary |> glimpse()
#> Rows: 58
#> 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> "161_acetaminophen", "161_acetaminophen", "161_acetam…
#> $ 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> "61", "61", "1", "1", "1", "1.22950819672131", "0.528…
#> $ 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 cumulative quantity        exposed time  initial daily dose 
#>                   7                   7                   7                   7 
#>    initial quantity         number eras    number exposures      number records 
#>                   7                   7                   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: 70
#> 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> "161_acetaminophen", "161_acetaminophen", "161_acetam…
#> $ strata_name      <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ strata_level     <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ variable_name    <chr> "number records", "number subjects", "Indication from…
#> $ variable_level   <chr> NA, NA, "headache", "headache", "influenza", "influen…
#> $ estimate_name    <chr> "count", "count", "count", "percentage", "count", "pe…
#> $ estimate_type    <chr> "integer", "integer", "integer", "percentage", "integ…
#> $ estimate_value   <chr> "61", "61", NA, NA, "0", "0", "0", "0", NA, NA, "57",…
#> $ additional_name  <chr> "overall", "overall", "overall", "overall", "overall"…
#> $ additional_level <chr> "overall", "overall", "overall", "overall", "overall"…

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

0.8.3

License

Apache License (>= 2)

Maintainer

Marti Catala

Last Published

March 20th, 2025

Functions in DrugUtilisation (0.8.3)

addNumberEras

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

Add a variable indicating individuals indications
addInitialExposureDuration

To add a new column with the duratio of the first exposure. 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.
daysPrescribedDoc

Helper for consistent documentation of daysPrescribed.
cdmDoc

Helper for consistent documentation of cdm.
cohortDoc

Helper for consistent documentation of cohort.
cohortGapEra

Get the gapEra used to create a cohort
nameStyleDoc

Helper for consistent documentation of nameStyle.
dailyDoseCoverage

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

It creates a mock database for testing DrugUtilisation package
addInitialDailyDose

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

Generate a set of drug cohorts based on ATC classification
generateDrugUtilisationCohortSet

Generate a set of drug cohorts based on given concepts
generateIngredientCohortSet

Generate a set of drug cohorts based on drug ingredients
newNameDoc

Helper for consistent documentation of name for new cohorts.
conceptSetDoc

Helper for consistent documentation of conceptSet.
ingredientConceptIdDoc

Helper for consistent documentation of ingredientConceptId.
erafyCohort

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

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

Helper for consistent documentation of censorDate.
drugUtilisationDoc

Helper for consistent documentation of add/summariseDrugUtilisation functions.
indexDateDoc

Helper for consistent documentation of indexDate.
plotDrugRestart

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

Helper for consistent documentation of gapEra.
plotDoc

Helper for consistent documentation of plot.
compNameDoc

Helper for consistent documentation of name for computed tables.
numberExposuresDoc

Helper for consistent documentation of numberExposures.
cohortIdDoc

Helper for consistent documentation of cohortId.
requireDrugInDateRange

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

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

Objects exported from other packages
stratifyByUnit

Function to stratify a conceptSet by unit
plotDrugUtilisation

Plot the results of summariseDrugUtilisation
tableDrugRestart

Format a drug_restart object into a visual table.
plotProportionOfPatientsCovered

Plot proportion of patients covered
requirePriorDrugWashout

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

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

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

Helper for consistent documentation of result.
tableDoseCoverage

Format a dose_coverage object into a visual table.
tableDrugUtilisation

Format a drug_utilisation object into a visual table.
summariseIndication

Summarise the indications of individuals in a drug cohort
tableIndication

Create a table showing indication results
strataDoc

Helper for consistent documentation of strata.
summariseDrugUtilisation

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

Get concept ids from a provided path to json files
tableTreatment

Format a summarised_treatment result into a visual table.
plotTreatment

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

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

Create a table with proportion of patients covered results
tableDoc

Helper for consistent documentation of table.
summariseDrugRestart

Summarise the drug restart per window.
restrictIncidentDoc

Helper for consistent documentation of restrictIncident.
summariseDrugUse

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

Summarise proportion Of patients covered
summariseTreatment

This function is used to summarise treatments received
requireIsFirstDrugEntry

Restrict cohort to only the first cohort record per subject
addDrugRestart

Summarise the drug restart per window.
addDrugUse

Add new columns with drug use related information
DrugUtilisation-package

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

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

Run benchmark of drug utilisation cohort generation
addTreatment

Add a variable indicating individuals medications
addInitialQuantity

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

Add new columns with drug use related information
addDailyDose

add daily dose information to a drug_exposure table
addCumulativeQuantity

To add a new column with the cumulative quantity. 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.
addDaysPrescribed

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

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

add route column to a table containing drug_exposure information
addTimeToExposure

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