### Connect to Mock Data for DrugUtilisation Package

Source: https://darwin-eu.github.io/DrugUtilisation/articles/drug_restart.html

Loads necessary libraries and connects to mock data using the DrugUtilisation package. This setup is required for running examples and testing functionalities.

```r
library(DrugUtilisation)
library(CodelistGenerator)
library(dplyr, warn.conflicts = FALSE)
library(PatientProfiles)

cdm <- mockDrugUtilisation(numberIndividual = 200, source = "duckdb")
```

--------------------------------

### Example: Summarise and Display Dose Coverage

Source: https://darwin-eu.github.io/DrugUtilisation/reference/tableDoseCoverage.html

This example demonstrates how to create mock data, summarise dose coverage using summariseDoseCoverage, and then format the results into a table using tableDoseCoverage.

```r
# \donttest{
library(DrugUtilisation)

cdm <- mockDrugUtilisation()

result <- summariseDoseCoverage(cdm, 1125315)
#> ℹ The following estimates will be calculated:
#> • 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 2026-06-18 08:50:35.657692
#> ✔ Summary finished, at 2026-06-18 08:50:36.073828

tableDoseCoverage(result)
#> cdm_name, ingredient_name, variable_name, variable_level, estimate_name, and
#> sample_size are missing in `columnOrder`, will be added last.



  
      |
        Variable name
      
      
---
|
      
        number records
      
      |
        Missing dose
      
      |
        daily_dose
      
      
Unit
      | Route
      | Pattern id
      |
        Estimate name
      
      
N
      | N (%)
      | Mean (SD)
      | Median (Q25 - Q75)
      
DUS MOCK; acetaminophen
      
overall
| overall
| overall
| 11
| 0 (0.00 %)
| 76,333.15 (182,552.72)
| 45.45 (24.97 - 3,444.44)  
milligram
| overall
| overall
| 11
| 0 (0.00 %)
| 76,333.15 (182,552.72)
| 45.45 (24.97 - 3,444.44)  

| oral
| overall
| 7
| 0 (0.00 %)
| 110.82 (233.77)
| 25.00 (17.04 - 37.52)  

| topical
| overall
| 4
| 0 (0.00 %)
| 209,722.22 (271,670.85)
| 131,000.00 (4,722.22 - 336,000.00)  

| oral
| 9
| 7
| 0 (0.00 %)
| 110.82 (233.77)
| 25.00 (17.04 - 37.52)  

| topical
| 18
| 4
| 0 (0.00 %)
| 209,722.22 (271,670.85)
| 131,000.00 (4,722.22 - 336,000.00)  
# }
```

--------------------------------

### Example: Generate Acetaminophen Cohort

Source: https://darwin-eu.github.io/DrugUtilisation/reference/generateIngredientCohortSet.html

This example demonstrates how to generate a cohort table for individuals exposed to acetaminophen. It uses mock data and then inspects the resulting cohort table.

```r
# \donttest{
library(DrugUtilisation)
library(dplyr, warn.conflicts = FALSE)

cdm <- mockDrugUtilisation()

cdm <- generateIngredientCohortSet(cdm = cdm,
                                   ingredient = "acetaminophen",
                                   name = "acetaminophen")
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 1 days.

cdm$acetaminophen |>
  glimpse()
#> Rows: 9
#> Columns: 4
#> $ cohort_definition_id <int> 1, 1, 1, 1, 1, 1, 1, 1, 1
#> $ subject_id           <int> 1, 2, 3, 4, 5, 6, 7, 9, 10
#> $ cohort_start_date    <date> 2020-08-27, 2020-06-13, 2022-11-17, 2008-10-15, 2…
#> $ cohort_end_date      <date> 2021-10-03, 2020-06-28, 2022-12-19, 2012-11-12, 2…
# }
```

--------------------------------

### Setup CDM Reference with Mock Data

Source: https://darwin-eu.github.io/DrugUtilisation/tutorial

Load necessary libraries and create a reference to a CDM object using mock data. This setup is required before performing any drug utilization analysis.

```r
library(omock)
library(duckdb)
library(CDMConnector)
library(dplyr)
library(CodelistGenerator)
library(DrugUtilisation)
library(CohortConstructor)
library(PatientProfiles)
library(ggplot2)
library(clock)
library(omopgenerics)
library(CohortSurvival)

cdm <- mockCdmFromDataset(datasetName = "GiBleed", source = "duckdb")
cdm$drug_exposure <- cdm$drug_exposure |
  mutate(quantity = sql("floor(random() * 6) + 1")) |
  mutate(quantity = case_when(
    quantity == 1 ~ 0,
    quantity == 2 ~ 1,
    quantity == 3 ~ 5,
    quantity == 4 ~ 10,
    quantity == 5 ~ 30,
    quantity == 6 ~ 100
  )) |
  compute(name = "drug_exposure")
```

--------------------------------

### Example Usage of summariseDrugRestart

Source: https://darwin-eu.github.io/DrugUtilisation/reference/summariseDrugRestart.html

This example demonstrates how to use the `summariseDrugRestart` function with mock data. It first generates a cohort set and then applies the function to summarise drug restart information.

```r
# \donttest{
library(DrugUtilisation)

cdm <- mockDrugUtilisation()

conceptlist <- list(acetaminophen = 1125360, metformin = c(1503297, 1503327))
cdm <- generateDrugUtilisationCohortSet(cdm = cdm,
                                        name = "switch_cohort",
                                        conceptSet = conceptlist)
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 1 days.

result <- cdm$cohort1 |
  summariseDrugRestart(switchCohortTable = "switch_cohort")
#> Warning: There was 1 warning in `dplyr::summarise()`. 
#> ℹ In argument: `cohort_start_date = min(.data$cohort_start_date, na.rm = 
#>   TRUE)`. 
#> Caused by warning in `min.default()`: 
#> ! no non-missing arguments to min; returning Inf 
#> Warning: There was 1 warning in `dplyr::summarise()`. 
#> ℹ In argument: `switch_start = min(.data$switch_start, na.rm = TRUE)`. 
#> Caused by warning in `min.default()`: 
#> ! no non-missing arguments to min; returning Inf

tableDrugRestart(result)
#> cdm_name, cohort_name, variable_name, follow_up_days, censor_date,
#> cohort_table_name, incident, restrict_to_first_discontinuation, and
#> switch_cohort_table are missing in `columnOrder`, will be added last.



  
      |
        Data source
      
      
---|

      |
        DUS MOCK
      
      
Treatment
      | Estimate name
      |
        Cohort name
      
      
cohort_1
      | cohort_2
      | cohort_3
      
Drug restart till end of observation
      
restart
| N (%)
| 0 (0.00 %)
| 0 (0.00 %)
| 0 (0.00 %)
switch
| N (%)
| 0 (0.00 %)
| 0 (0.00 %)
| 0 (0.00 %)
restart and switch
| N (%)
| 0 (0.00 %)
| 0 (0.00 %)
| 0 (0.00 %)
untreated
| N (%)
| 6 (100.00 %)
| 0 (0.00 %)
| 4 (100.00 %)
# }
```

--------------------------------

### Example: Plotting Proportion of Patients Covered

Source: https://darwin-eu.github.io/DrugUtilisation/reference/plotProportionOfPatientsCovered.html

Demonstrates how to create mock data, generate a drug utilization cohort, summarize the proportion of patients covered, and then plot the results. This example requires the `DrugUtilisation` package and sets up a basic workflow for analyzing drug coverage.

```r
# \donttest{
library(DrugUtilisation)

cdm <- mockDrugUtilisation()

cdm <- generateDrugUtilisationCohortSet(cdm = cdm,
                                        name = "my_cohort",
                                        conceptSet = list(drug_of_interest = c(1503297, 1503327)))
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 1 days.

result <- cdm$my_cohort |
  summariseProportionOfPatientsCovered(followUpDays = 365)
#> Getting PPC for cohort drug_of_interest
#> Collecting cohort into memory
#> Geting PPC over 365 days following first cohort entry
#>  -- getting PPC for ■■■■■■■■■■■■                     129 of 365 days
#>  -- getting PPC for ■■■■■■■■■■■■■■■■■■■■■■■■         284 of 365 days
#>  -- getting PPC for ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  365 of 365 days

plotProportionOfPatientsCovered(result)

# }
```

--------------------------------

### Install DrugUtilisation Package

Source: https://darwin-eu.github.io/DrugUtilisation/tutorial

Install the DrugUtilisation package from CRAN. This is the first step to using the package's functionalities.

```r
install.packages("DrugUtilisation")
```

--------------------------------

### Example: Plotting Median Days Prescribed

Source: https://darwin-eu.github.io/DrugUtilisation/reference/plotDrugUtilisation.html

Demonstrates plotting the median 'days prescribed' as a bar plot. This example requires setting up mock data, generating a cohort, summarising drug utilisation, and then plotting the median estimate.

```r
# \donttest{
library(DrugUtilisation)
library(PatientProfiles)
library(dplyr, warn.conflicts = FALSE)

cdm <- mockDrugUtilisation(numberIndividuals = 100)
codes <- list(aceta = c(1125315, 1125360, 2905077, 43135274))
cdm <- generateDrugUtilisationCohortSet(cdm = cdm,
                                        name = "cohort",
                                        conceptSet = codes)
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 1 days.

result <- cdm$cohort |
  addSex() |
  summariseDrugUtilisation(
    strata = "sex",
    ingredientConceptId = 1125315,
    estimates = c("min", "q25", "median", "q75", "max", "density")
  )

result |
  filter(estimate_name == "median") |
  plotDrugUtilisation(
    variable = "days prescribed",
    plotType = "barplot"
  )


result |
  plotDrugUtilisation(
    variable = "days exposed",
    facet = cohort_name ~ cdm_name,
    colour = "sex",
    plotType = "boxplot"
  )


result |
  plotDrugUtilisation(
    variable = "cumulative dose milligram",
    plotType = "densityplot",
    facet = "cohort_name",
    colour = "sex"
  )


# }
```

--------------------------------

### Example Usage of addTreatment

Source: https://darwin-eu.github.io/DrugUtilisation/reference/addTreatment.html

Demonstrates how to use the addTreatment function to add medication information to a drug cohort. Requires mock data and cohort generation.

```R
# \donttest{
library(DrugUtilisation)
library(dplyr, warn.conflicts = FALSE)

cdm <- mockDrugUtilisation(numberIndividuals = 50)

cdm <- generateIngredientCohortSet(cdm = cdm,
                                   name = "drug_cohort",
                                   ingredient = "acetaminophen")
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 1 days.

cdm <- generateIngredientCohortSet(cdm = cdm,
                                   name = "treatments",
                                   ingredient = c("metformin", "simvastatin"))
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 1 days.

cdm$drug_cohort |
  addTreatment("treatments", window = list(c(0, 0), c(1, 30), c(31, 60))) |
  glimpse()
#> ℹ Intersect with medications table (treatments).
#> ℹ Collapse medications to mutually exclusive categories
#> Rows: 36
#> Columns: 7
#> $ cohort_definition_id <int> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1…
#> $ subject_id           <int> 2, 3, 5, 6, 7, 8, 10, 11, 12, 13, 14, 15, 15, 16,…
#> $ cohort_start_date    <date> 2013-04-15, 2021-09-19, 2009-04-27, 2018-01-21, …
#> $ cohort_end_date      <date> 2018-07-25, 2022-11-28, 2013-09-12, 2020-03-12, …
#> $ medication_0_to_0    <chr> "simvastatin", "untreated", "untreated", "untreat…
#> $ medication_1_to_30   <chr> "simvastatin", "untreated", "untreated", "untreat…
#> $ medication_31_to_60  <chr> "simvastatin", "untreated", "untreated", "untreat…
# }
```

--------------------------------

### Example: Calculate PPC with Mock Data

Source: https://darwin-eu.github.io/DrugUtilisation/reference/summariseProportionOfPatientsCovered.html

Demonstrates how to create mock data and use `summariseProportionOfPatientsCovered` to calculate the proportion of patients covered over 365 days. The output is then tidied for easier analysis.

```r
# \donttest{
library(DrugUtilisation)

cdm <- mockDrugUtilisation(numberIndividuals = 100)

result <- cdm$cohort1 |>
  summariseProportionOfPatientsCovered(followUpDays = 365)
#> Getting PPC for cohort cohort_1
#> Collecting cohort into memory
#> Geting PPC over 365 days following first cohort entry
#>  -- getting PPC for ■■■■■■■■                         89 of 365 days
#>  -- getting PPC for ■■■■■■■■■■■■■■■■■■■■■■■■■■■■     326 of 365 days
#>  -- getting PPC for ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  365 of 365 days
#> Getting PPC for cohort cohort_2
#> Collecting cohort into memory
#> Geting PPC over 365 days following first cohort entry
#> Getting PPC for cohort cohort_3
#> Collecting cohort into memory
#> Geting PPC over 365 days following first cohort entry
#>  -- getting PPC for ■■■■■■■■■■■■                     132 of 365 days
#>  -- getting PPC for ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  365 of 365 days

tidy(result)
#> # A tibble: 1,098 × 11
#>    cdm_name cohort_name variable_name variable_level time  outcome_count
#>    <chr>    <chr>       <chr>         <chr>          <chr>         <int>
#>  1 DUS MOCK cohort_1    overall       overall        0                38
#>  2 DUS MOCK cohort_1    overall       overall        1                38
#>  3 DUS MOCK cohort_1    overall       overall        2                38
#>  4 DUS MOCK cohort_1    overall       overall        3                36
#>  5 DUS MOCK cohort_1    overall       overall        4                36
#>  6 DUS MOCK cohort_1    overall       overall        5                36
#>  7 DUS MOCK cohort_1    overall       overall        6                36
#>  8 DUS MOCK cohort_1    overall       overall        7                36
#>  9 DUS MOCK cohort_1    overall       overall        8                36
#> 10 DUS MOCK cohort_1    overall       overall        9                35
#> # ℹ 1,088 more rows
#> # ℹ 5 more variables: denominator_count <int>, ppc <dbl>, ppc_lower <dbl>,
#> #   ppc_upper <dbl>, cohort_table_name <chr>
# }
```

--------------------------------

### Example: Using addCumulativeQuantity with Mock Data

Source: https://darwin-eu.github.io/DrugUtilisation/reference/addCumulativeQuantity.html

This example demonstrates how to use the addCumulativeQuantity function with mock data. It involves setting up a CDM object, generating a drug cohort, and then adding the cumulative quantity of a specific drug ingredient (acetaminophen) to the cohort.

```r
# \donttest{
library(DrugUtilisation)
library(CodelistGenerator)
library(dplyr, warn.conflicts = FALSE)

cdm <- mockDrugUtilisation()
codeloist <- getDrugIngredientCodes(cdm = cdm, name = "acetaminophen")
cdm <- generateDrugUtilisationCohortSet(cdm = cdm,
                                        name = "dus_cohort",
                                        conceptSet = codelist)
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 1 days.

cdm$dus_cohort |>
  addCumulativeQuantity(conceptSet = codelist) |>
  glimpse()
#> Rows: 8
#> Columns: 5
#> $ cohort_definition_id                  <int> 1, 1, 1, 1, 1, 1, 1, 1
#> $ subject_id                            <int> 2, 2, 3, 6, 6, 7, 8, 9
#> $ cohort_start_date                     <date> 2022-02-13, 2022-01-05, 1991-10-…
#> $ cohort_end_date                       <date> 2022-02-13, 2022-02-07, 1999-08-…
#> $ cumulative_quantity_161_acetaminophen <dbl> 50, 20, 90, 90, 1, 30, 30, 50
# }
```

--------------------------------

### Example: Generate and Plot Discontinuation Survival

Source: https://darwin-eu.github.io/DrugUtilisation/reference/plotDiscontinuationAsSurvival.html

Demonstrates how to create mock data, calculate discontinuation as survival, and then plot the results using plotDiscontinuationAsSurvival. Ensure the DrugUtilisation package is loaded.

```r
# \donttest{
library(DrugUtilisation)

cdm <- mockDrugUtilisation()

result <- cdm$cohort1 |>
  summariseDiscontinuationAsSurvival(followUpDays = 365)
#> ℹ Calculating discontinuation for cohort_1.
#> ℹ Subsetting table to cohort of interest.
#> ℹ Preparing discontinuation (outcome) cohort.
#> ℹ Estimate single event survival for cohort: cohort_1 and outcome:
#>   discontinuation_of_cohort_1.
#> - Getting survival for target cohort 'cohort_1' and outcome cohort
#> 'discontinuation_of_cohort_1'
#> Getting overall estimates
#> `eventgap`, `outcome_washout`, `censor_on_cohort_exit`, `follow_up_days`, and
#> `minimum_survival_days` casted to character.
#> ✔ Discontinuation analysis for cohort_1 completed in 2s.
#> ℹ Calculating discontinuation for cohort_2.
#> ℹ Subsetting table to cohort of interest.
#> ℹ Preparing discontinuation (outcome) cohort.
#> ℹ Estimate single event survival for cohort: cohort_2 and outcome:
#>   discontinuation_of_cohort_2.
#> - Getting survival for target cohort 'cohort_2' and outcome cohort
#> 'discontinuation_of_cohort_2'
#> Getting overall estimates
#> `eventgap`, `outcome_washout`, `censor_on_cohort_exit`, `follow_up_days`, and
#> `minimum_survival_days` casted to character.
#> ✔ Discontinuation analysis for cohort_2 completed in 1s.
#> ℹ Calculating discontinuation for cohort_3.
#> ℹ Subsetting table to cohort of interest.
#> ℹ Preparing discontinuation (outcome) cohort.
#> ℹ Estimate single event survival for cohort: cohort_3 and outcome:
#>   discontinuation_of_cohort_3.
#> - Getting survival for target cohort 'cohort_3' and outcome cohort
#> 'discontinuation_of_cohort_3'
#> Getting overall estimates
#> `eventgap`, `outcome_washout`, `censor_on_cohort_exit`, `follow_up_days`, and
#> `minimum_survival_days` casted to character.
#> ✔ Discontinuation analysis for cohort_3 completed in 1s.

plotDiscontinuationAsSurvival(result)

# }
```

--------------------------------

### Create and Modify Mock Cohort Tables

Source: https://darwin-eu.github.io/DrugUtilisation/articles/summarise_treatments.html

Initialises mock CDM data and renames cohort tables to represent specific health conditions and treatments. Ensure 'dplyr', 'omopgenerics', and 'PatientProfiles' are installed and loaded.

```r
library(DrugUtilisation)
library(dplyr, warn.conflicts = FALSE)
library(omopgenerics)
library(PatientProfiles)

cdm <- mockDrugUtilisation(numberIndividual = 200, source = "duckdb")

new_cohort_set <- settings(cdm$cohort1) |
  arrange(cohort_definition_id) |
  mutate(cohort_name = c("asthma", "bronchitis", "pneumonia"))

cdm$cohort1 <- cdm$cohort1 |
  newCohortTable(cohortSetRef = new_cohort_set)

new_cohort_set <- settings(cdm$cohort2) |
  arrange(cohort_definition_id) |
  mutate(cohort_name = c("albuterol", "fluticasone", "montelukast"))

cdm$cohort2 <- cdm$cohort2 |
  newCohortTable(cohortSetRef = new_cohort_set)
```

--------------------------------

### Generate Plot from Summarised Indications

Source: https://darwin-eu.github.io/DrugUtilisation/reference/plotIndication.html

This example demonstrates how to generate a default plot from the results of summariseIndication. It requires the DrugUtilisation and CDMConnector packages and a mock CDM database.

```R
library(DrugUtilisation)
library(CDMConnector)

cdm <- mockDrugUtilisation(source = "duckdb")

indications <- list(headache = 378253, asthma = 317009)
cdm <- generateConceptCohortSet(cdm = cdm,
                                conceptSet = indications,
                                name = "indication_cohorts")

cdm <- generateIngredientCohortSet(cdm = cdm,
                                   name = "drug_cohort",
                                   ingredient = "acetaminophen")
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 1 days.

result <- cdm$drug_cohort |
  summariseIndication(
    indicationCohortName = "indication_cohorts",
    unknownIndicationTable = "condition_occurrence",
    indicationWindow = list(c(-Inf, 0), c(-365, 0))
  )
#> ℹ Intersect with indications table (indication_cohorts)
#> ℹ Summarising indications.

plotIndication(result)
```

--------------------------------

### Summarize Indications with Time Windows

Source: https://darwin-eu.github.io/DrugUtilisation/tutorial

Summarizes indications within specified time windows relative to a cohort's start date. Requires a CDM object and pre-instantiated cohorts. Unknown indications are handled by referencing a specified table.

```r
result <- cdm$dus_cohort |
  summariseIndication(
    indicationCohortName = "indications", 
    indicationWindow = list(c(0, 0), c(-30, 7)), 
    unknownIndicationTable = "condition_occurrence"
  )
result |
  glimpse()
```

--------------------------------

### Summarise Indications for Drug Cohort

Source: https://darwin-eu.github.io/DrugUtilisation/reference/summariseIndication.html

Use this snippet to summarise indications for individuals in a drug cohort. It requires a cohort table, an indication cohort name, and optionally specifies tables for unknown indications and the time window for identification. The example uses a mock CDM and generates concept and ingredient cohorts before summarising indications.

```R
library(DrugUtilisation)
library(dplyr, warn.conflicts = FALSE)
library(CDMConnector)

cdm <- mockDrugUtilisation(source = "duckdb")

indications <- list(headache = 378253, asthma = 317009)
cdm <- generateConceptCohortSet(cdm = cdm,
                                conceptSet = indications,
                                name = "indication_cohorts")

cdm <- generateIngredientCohortSet(cdm = cdm,
                                   name = "drug_cohort",
                                   ingredient = "acetaminophen")
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 1 days.

cdm$drug_cohort |
  summariseIndication(
    indicationCohortName = "indication_cohorts",
    unknownIndicationTable = "condition_occurrence",
    indicationWindow = list(c(-Inf, 0))
  ) |
  glimpse()
#> ℹ Intersect with indications table (indication_cohorts)
#> ℹ Summarising indications.
#> 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 any time before or on index date", "Indic…
#> $ variable_level   <chr> "asthma", "asthma", "headache", "headache", "asthma a…
#> $ estimate_name    <chr> "count", "percentage", "count", "percentage", "count"…
#> $ estimate_type    <chr> "integer", "percentage", "integer", "percentage", "in…
#> $ estimate_value   <chr> "1", "25.00000", "1", "25.00000", "0", "0", "2", "50.…
#> $ additional_name  <chr> "window_name", "window_name", "window_name", "window_…
#> $ additional_level <chr> "-inf to 0", "-inf to 0", "-inf to 0", "-inf to 0", 
```

--------------------------------

### Customize Plot Axes and Faceting

Source: https://darwin-eu.github.io/DrugUtilisation/reference/plotIndication.html

This example shows how to customize the plot by changing the x-axis variable and removing faceting. It uses the same 'result' object generated in the previous example.

```R
plotIndication(result, x = "window_name", facet = NULL)
```

--------------------------------

### Create Mock CDM Reference

Source: https://darwin-eu.github.io/DrugUtilisation/index.html

Initializes a mock CDM reference using duckdb for testing purposes. Ensure the CDMConnector and dplyr packages are loaded.

```r
library(DrugUtilisation)
library(dplyr)
library(CDMConnector)

cdm <- mockDrugUtilisation(numberIndividual = 100, source = "duckdb")
```

--------------------------------

### Generate Mock CDM Data and Insert into DuckDB

Source: https://darwin-eu.github.io/DrugUtilisation/articles/mock_data.html

Generate mock OMOP CDM data and directly insert it into a DuckDB database. The resulting CDM reference will point to the DuckDB instance.

```r
cdm <- mockDrugUtilisation(source = "duckdb")
cdm
#> 
#> ── # OMOP CDM reference (duckdb) of DUS MOCK ───────────────────────────────────
#> • omop tables: concept, concept_ancestor, concept_relationship,
#> condition_occurrence, drug_exposure, drug_strength, observation,
#> observation_period, person, visit_occurrence
#> • cohort tables: cohort1, cohort2
#> • achilles tables: -
#> • other tables: -
```

--------------------------------

### generateIngredientCohortSet

Source: https://darwin-eu.github.io/DrugUtilisation/reference/generateIngredientCohortSet.html

Adds a new cohort table to the cdm reference with individuals who have drug exposure records with the specified drug ingredient. Cohort start and end dates will be based on drug record start and end dates, respectively. Records that overlap or have fewer days between them than the specified gap era will be concatenated into a single cohort entry.

```APIDOC
## generateIngredientCohortSet

### Description
Adds a new cohort table to the cdm reference with individuals who have drug exposure records with the specified drug ingredient. Cohort start and end dates will be based on drug record start and end dates, respectively. Records that overlap or have fewer days between them than the specified gap era will be concatenated into a single cohort entry.

### Method
`generateIngredientCohortSet(
  cdm,
  name,
  ingredient = NULL,
  gapEra = 1,
  subsetCohort = NULL,
  subsetCohortId = NULL,
  numberExposures = FALSE,
  daysPrescribed = FALSE,
  ...
)`

### Arguments 

* **cdm** (A `cdm_reference` object.) - A `cdm_reference` object.
* **name** (character vector of length 1) - Name of the new cohort table, it must be a length 1 character vector.
* **ingredient** (vector or named list) - Accepts both vectors and named lists of ingredient names. For a vector input, e.g., c("acetaminophen", "codeine"), it generates a cohort table with descendant concept codes for each ingredient, assigning unique cohort_definition_id. For a named list input, e.g., list( "test_1" = c("simvastatin", "acetaminophen"), "test_2" = "metformin"), it produces a cohort table based on the structure of the input, where each name leads to a combined set of descendant concept codes for the specified ingredients, creating distinct cohort_definition_id for each named group.
* **gapEra** (numeric) - Number of days between two continuous exposures to be considered in the same era.
* **subsetCohort** (Cohort table) - Cohort table to subset.
* **subsetCohortId** (integer) - Cohort id to subset.
* **numberExposures** (boolean) - Whether to include 'number_exposures' (number of drug exposure records between indexDate and censorDate).
* **daysPrescribed** (boolean) - Whether to include 'days_prescribed' (number of days prescribed used to create each era).
* **...** - Arguments to be passed to `CodelistGenerator::getDrugIngredientCodes()`.

### Value
The function returns the cdm reference provided with the addition of the new cohort table.

### Examples
```R
# \donttest{
library(DrugUtilisation)
library(dplyr, warn.conflicts = FALSE)

cdm <- mockDrugUtilisation()

cdm <- generateIngredientCohortSet(cdm = cdm,
                                   ingredient = "acetaminophen",
                                   name = "acetaminophen")
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 1 days.

cdm$acetaminophen |>
  glimpse()
#> Rows: 9
#> Columns: 4
#> $ cohort_definition_id <int> 1, 1, 1, 1, 1, 1, 1, 1, 1
#> $ subject_id           <int> 1, 2, 3, 4, 5, 6, 7, 9, 10
#> $ cohort_start_date    <date> 2020-08-27, 2020-06-13, 2022-11-17, 2008-10-15, 2…
#> $ cohort_end_date      <date> 2021-10-03, 2020-06-28, 2022-12-19, 2012-11-12, 2…
# }
```
```

--------------------------------

### Accessing Cohort Settings and Counts

Source: https://darwin-eu.github.io/DrugUtilisation/articles/create_cohorts.html

Demonstrates how to retrieve settings, counts, and codelists for a created cohort. Use settings() to view cohort attributes like gapEra, cohortCount() for record and subject counts, and cohortCodelist() to see the codelist used.

```r
settings(cdm$acetaminophen_cohort)
#> # A tibble: 1 × 3
#>   cohort_definition_id cohort_name   gap_era
#>                  <int> <chr>         <chr>  
#> 1                    1 acetaminophen 30
covariateCount(cdm$acetaminophen_cohort)
#> # A tibble: 1 × 3
#>   cohort_definition_id number_records number_subjects
#>                  <int>          <int>           <int>
#> 1                    1             63              53
covariateCodelist(cdm$acetaminophen_cohort, cohortId = 1)
#> 
#> ── 1 codelist ──────────────────────────────────────────────────────────────────
#> 
#> - acetaminophen (4 codes)
```

--------------------------------

### Count Cohort Records

Source: https://darwin-eu.github.io/DrugUtilisation/articles/create_cohorts.html

Use `cohortCount()` to get the number of records and subjects in a cohort. This is useful for initial data validation.

```r
cohortCount(cdm$acetaminophen_cohort)
#> # A tibble: 1 × 3
#>   cohort_definition_id number_records number_subjects
#>                  <int>          <int>           <int>
#> 1                    1             61              53
```

--------------------------------

### Create Mock OMOP CDM Data

Source: https://darwin-eu.github.io/DrugUtilisation/articles/indication.html

Initializes a mock OMOP CDM database connection using DBI and CDMConnector. This is a prerequisite for using the DrugUtilisation package functionalities.

```R
library(DrugUtilisation)
library(omock)
library(CDMConnector)
library(dplyr)
library(PatientProfiles)

cdm <- mockCdmFromDataset(datasetName = "GiBleed", source = "duckdb")
```

--------------------------------

### Retrieve Cohort Codelist

Source: https://darwin-eu.github.io/DrugUtilisation/tutorial

Use `cohortCodelist()` to get the codes associated with a specific cohort. Specify the `cohortId` to retrieve the codelist for a particular cohort definition.

```R
cohortCodelist(cdm$dus_cohort, cohortId = 1)
```

--------------------------------

### Summarise Comedications

Source: https://darwin-eu.github.io/DrugUtilisation/tutorial

Summarizes comedications over a specified time window relative to a treatment's start and end dates. Useful for understanding concurrent medication use.

```r
comedications <- cdm$dus_cohort |
  summariseTreatment(
    window = c(0, Inf), 
    treatmentCohortName = "treatments", 
    indexDate = "cohort_start_date", 
    censorDate = "cohort_end_date"
  )
```

--------------------------------

### Cohort creation with gapEra = 0

Source: https://darwin-eu.github.io/DrugUtilisation/articles/create_cohorts.html

Illustrates cohort creation where overlapping exposures are merged, but a gap of 29 days results in separate episodes.

```text
#> # A tibble: 3 × 4
#>   cohort_definition_id subject_id cohort_start_date cohort_end_date
#>                  <int>      <int> <date>            <date>         
#> 1                    1          1 2020-01-01        2020-02-15     
#> 2                    1          1 2020-03-15        2020-04-19     
#> 3                    1          1 2020-04-20        2020-05-15
```

--------------------------------

### Inspect the Mock CDM Reference Object

Source: https://darwin-eu.github.io/DrugUtilisation/articles/mock_data.html

Display the structure of the created mock CDM reference object. This shows the populated OMOP tables and cohort tables available in the in-memory database.

```r
cdm
```

--------------------------------

### View Created Cohort

Source: https://darwin-eu.github.io/DrugUtilisation/articles/create_cohorts.html

Displays the structure and content of the created cohort, showing cohort definition ID, subject ID, start date, and end date.

```r
cdm2$dus_cohort
#> # Source:   table<dus_cohort> [?? x 4]
#> # Database: DuckDB 1.5.2 [unknown@Linux 6.17.0-1018-azure:R 4.6.0/:memory:]
#>   cohort_definition_id subject_id cohort_start_date cohort_end_date
#>                  <int>      <int> <date>            <date>         
#> 1                    1          1 2020-01-01        2020-02-15
```

--------------------------------

### Cohort creation with gapEra = 1

Source: https://darwin-eu.github.io/DrugUtilisation/articles/create_cohorts.html

Demonstrates cohort creation where overlapping exposures are merged, and a gap of 29 days is bridged, resulting in fewer episodes.

```text
#> # A tibble: 2 × 4
#>   cohort_definition_id subject_id cohort_start_date cohort_end_date
#>                  <int>      <int> <date>            <date>         
#> 1                    1          1 2020-01-01        2020-02-15     
#> 2                    1          1 2020-03-15        2020-05-15
```

--------------------------------

### requireObservationBeforeDrug

Source: https://darwin-eu.github.io/DrugUtilisation/reference/requireObservationBeforeDrug.html

Filters cohort records to include only those with a specified number of prior observation days before the cohort start date. Optionally filters by a specific cohort definition ID.

```APIDOC
## requireObservationBeforeDrug

### Description
Filter the cohort table keeping only the cohort records for which the individual has the required observation time in the database prior to their cohort start date.

### Usage
```R
requireObservationBeforeDrug(
  cohort,
  days,
  cohortId = NULL,
  name = omopgenerics::tableName(cohort)
)
```

### Arguments

* `cohort` (cohort_table): A cohort_table object.
* `days` (numeric): Number of days of prior observation required before cohort start date. Any records with fewer days will be dropped.
* `cohortId` (numeric, optional): A cohort definition id to restrict by. If NULL, all cohorts will be included.
* `name` (character): Name of the new cohort table, it must be a length 1 character vector.

### Value
The cohort table having applied the prior observation requirement.

### Examples

```R
# \donttest{
library(DrugUtilisation)
library(dplyr, warn.conflicts = FALSE)

cdm <- mockDrugUtilisation()

cdm$cohort1 <- cdm$cohort1 |>
  requireObservationBeforeDrug(days = 365)

attrition(cdm$cohort1) |>
  glimpse()
# > Rows: 6
# > Columns: 7
# > $ cohort_definition_id <int> 1, 1, 2, 2, 3, 3
# > $ number_records       <int> 2, 1, 2, 1, 6, 2
# > $ number_subjects      <int> 2, 1, 2, 1, 6, 2
# > $ reason_id            <int> 1, 2, 1, 2, 1, 2
# > $ reason               <chr> "Initial qualifying events", "require prior obser…
# > $ excluded_records     <int> 0, 1, 0, 1, 0, 4
# > $ excluded_subjects    <int> 0, 1, 0, 1, 0, 4
# > # }
```
```

--------------------------------

### View Cohort Settings

Source: https://darwin-eu.github.io/DrugUtilisation/articles/create_cohorts.html

Shows the configuration settings for a cohort, including parameters like gap era and prior use.

```R
settings(cdm$acetaminophen_cohort)
```

--------------------------------

### Get Drug Ingredient Codes

Source: https://darwin-eu.github.io/DrugUtilisation/articles/drug_utilisation.html

Retrieves a codelist of drug ingredient concepts for specified drug names using the CodelistGenerator package. This is a prerequisite for analyzing drug usage.

```R
drugConcepts <- getDrugIngredientCodes(cdm = cdm, name = c("acetaminophen", "simvastatin"))
```

--------------------------------

### Get drug ingredient codes using CodelistGenerator

Source: https://darwin-eu.github.io/DrugUtilisation/articles/create_cohorts.html

Use `getDrugIngredientCodes` from the CodelistGenerator package to retrieve concept IDs for a specific drug ingredient. Requires a CDM object.

```r
codes <- getDrugIngredientCodes(cdm = cdm, name = "acetaminophen", nameStyle = "{concept_name}")
codes[["acetaminophen"]]
#> [1]  1125315  1125360  2905077 43135274
```

--------------------------------

### View Initial Cohort Data

Source: https://darwin-eu.github.io/DrugUtilisation/articles/create_cohorts.html

Displays the initial structure and a sample of records for a created cohort.

```R
cdm$acetaminophen_cohort
```

--------------------------------

### Get Gap Era from Cohort - R

Source: https://darwin-eu.github.io/DrugUtilisation/reference/cohortGapEra.html

Retrieves the gapEra value used to create a cohort. This is useful for understanding the treatment gap criteria applied during cohort generation.

```r
library(DrugUtilisation)
library(CodelistGenerator)

cdm <- mockDrugUtilisation()

druglist <- getDrugIngredientCodes(cdm = cdm,
                                   name = c("acetaminophen", "metformin"))

cdm <- generateDrugUtilisationCohortSet(cdm = cdm,
                                        name = "drug_cohorts",
                                        conceptSet = druglist,
                                        gapEra = 100)
#> ℹ Subsetting drug_exposure table
#> ℹ Checking whether any record needs to be dropped.
#> ℹ Collapsing overlaping records.
#> ℹ Collapsing records with gapEra = 100 days.

covariateGapEra(cdm$drug_cohorts)
#> [1] 100 100
```

--------------------------------

### Create a conceptSet as a codelist object

Source: https://darwin-eu.github.io/DrugUtilisation/articles/create_cohorts.html

Create a concept set by converting a list of concept IDs into a `codelist` object. This may involve casting IDs to integers.

```r
conceptSet <- list(acetaminophen = c(1, 2, 3)) |> 
  newCodelist()
#> Warning: ! `codelist` casted to integers.
conceptSet
#> 
#> ── 1 codelist ──────────────────────────────────────────────────────────────────
#> 
#> - acetaminophen (3 codes)
conceptSet$acetaminophen
#> [1] 1 2 3
```

--------------------------------

### Create Mock CDM Data

Source: https://darwin-eu.github.io/DrugUtilisation/reference/mockDrugUtilisation.html

Generates a mock OMOP CDM reference with default settings. This is useful for initial testing of the DrugUtilisation package.

```r
# \donttest{
library(DrugUtilisation)

cdm <- mockDrugUtilisation()

cdm
# }
```