---
title: "Use DrugUtilisation to create a cohort"
author: "Marti Catala, Mike Du, Yuchen Guo, Kim Lopez-Guell, Edward Burn, Xintong Li"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Use DrugUtilisation to create a cohort}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
  markdown: 
    wrap: 72
---

```{r , include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# Introduction

In this vignette we will introduce different ways to create a drug utilisation
cohort using DrugUtilisation.

## Create a cdm object

To create a cdm_reference object you will need to use the package CDMConnector. 
For this vignette we will use mock data contained in the DrugUtilisation 
package.

```{r setup, message = FALSE, warning = FALSE}
library(DrugUtilisation)
library(CodelistGenerator)
library(dplyr)
library(CDMConnector)

cdm <- mockDrugUtilisation(numberIndividual = 200)
```

# Get the concept code

The first thing that we need is a concept list. The concept list can be obtained
through different ways:

1.  Read from .json file
2.  Use concept code directly
3.  Use CodelistGenerator

## Concept list from a .json file

To create a cohort with a concept list from a .json file, use 
`codesFromConceptSet()` from CodelistGenerator package. Let's see an example:

```{r}
conceptSet_json <- codesFromConceptSet(here::here("inst/Concept"), cdm)
conceptSet_json
```

## Concept list listed directly

The concept list can also be created manually:

```{r}
#get concept using code directly
conceptSet_code <- list(asthma = 317009)
conceptSet_code
```

## Concept list of an ingredient

In case there is a certain ingredient of interest, the code can also be
obtained by `getDrugIngredientCodes()` from the package
CodelistGenerator.

```{r, message=FALSE, warning=FALSE}
#get concept by ingredient
conceptSet_ingredient <- getDrugIngredientCodes(cdm, name = "simvastatin")
conceptSet_ingredient
```

## Concept list from an ATC code

We can also obtain the ATC code by using `getATCCodes()` from
CodelistGenerator package.

```{r, message=FALSE, warning=FALSE}
#get concept from ATC codes
conceptSet_ATC <- getATCCodes(cdm, 
                              level = "ATC 1st", 
                              name = "ALIMENTARY TRACT AND METABOLISM")
conceptSet_ATC
```

# Create a cohort

Once we have the `conceptSet`, we can proceed to generate a cohort.
There are two functions in this package to do that:

1.  `generateConceptCohortSet()`: to generate a cohort for a certain
    list of concepts (they do not have to be a drug). This function is
    exported from CDMConnector package.

2.  `generateDrugUtilisationCohortSet()`: to generate a cohort of the
    drug use.

## Use generateConceptCohortSet() to create a cohort

Let's try to use `generateConceptCohortSet()` to get the asthma cohort
using the `conceptSet_code` created before. We could also use `conceptSet_json_1` or
`conceptSet_json_2` to obtain the same result.

```{r, message=FALSE, warning=FALSE}
cdm <- generateConceptCohortSet(cdm,
  conceptSet = conceptSet_code,
  name = "asthma_1",
  overwrite = TRUE
)
cdm$asthma_1
```

The count of the cohort can be assessed using `cohortCount()` from
CDMConnector.

```{r, message=FALSE, warning=FALSE}
cohortCount(cdm$asthma_1)
```

Cohort attrition can be assessed using `attrition()` from
CDMConnector.

```{r, message=FALSE, warning=FALSE}
attrition(cdm$asthma_1)
```

### end parameter
You can use the `end` parameter to set how the cohort end date will be defined. By default, `end = observation_period_end_date`, but it can also be defined as `event_end_date` or by defining a numeric scalar. 
See an example below:

```{r, message=FALSE, warning=FALSE}
cdm <- generateConceptCohortSet(cdm,
  conceptSet = conceptSet_code,
  name = "asthma_2",
  end = "event_end_date",
  overwrite = TRUE
)
cdm$asthma_2
```

### requiredObservation parameter

The `requiredObservation` parameter is a numeric vector of length 2, that defines the number of days of required observation time prior to index and post index for an event to be included in the cohort. The default value is `c(0,0)`. Let's check how the difference between **asthma_3** and **asthma_2** when changing this parameter.

```{r, message=FALSE, warning=FALSE}
cdm <- generateConceptCohortSet(cdm,
  conceptSet = conceptSet_code,
  name = "asthma_3",
  end = "observation_period_end_date",
  requiredObservation = c(10, 10),
  overwrite = TRUE
)
cdm$asthma_3

cohortCount(cdm$asthma_3)

attrition(cdm$asthma_3)
```

## Use generateDrugUtilisationCohortSet() to generate a cohort

Now let's try the function `generateDrugUtilisationCohortSet()` to get the
drug cohort for the ingredient *simvastatin*. See an example below:

```{r, message=FALSE, warning=FALSE}
cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_1",
  conceptSet = conceptSet_ingredient
)
cdm$simvastin_1

cohortCount(cdm$simvastin_1)

attrition(cdm$simvastin_1)
```

### imputeDuration and durationRange parameters

The parameter `durationRange` specifies the range within which the
duration must fall, where duration will be calculated as:
<p style="text-align:center;">`duration = cohort_end_date - cohort_start_date + 1`</p>

The default value is `c(1, Inf)`. See that this parameter must be a
numeric vector of length two, with no NAs and with the first value equal
or bigger than the second one. Duration values outside of `durationRange` will be imputed
using `imputeDuration`. `imputeDuration` can be set as: `none`(default),
`median`, `mean`, `mode` or an integer (count).

```{r, message=FALSE, warning=FALSE}
cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_2",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf) # default as c(1, Inf)
)

attrition(cdm$simvastin_2)
```

### gapEra paratemer

The `gapEra` parameter defines the number of days between two continuous
drug exposures to be considered as a same era. Now let's change it from
0 to a larger number to see what happens.

```{r, message=FALSE, warning=FALSE}
cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_3",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 30 # default as 0
)

attrition(cdm$simvastin_3) %>% select(number_records, reason, excluded_records, excluded_subjects)
```

From the **simvastin_3** cohort attrition, we can see that when
joining eras, it resulted in less records, compared to the
**simvastin_2** cohort, as exposures with less than 30 days gaps are
joined.

### priorUseWashout parameter

The `priorUseWashout` parameter specifies the number of prior days
without exposure (often termed as 'washout') that are required. By
default, it is set to NULL, meaning no washout period is necessary. See that when increasing this value, the number of records decrease.

```{r, message=FALSE, warning=FALSE}
cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_4",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 30,
  priorUseWashout = 30
)

attrition(cdm$simvastin_4) %>% select(number_records, reason, excluded_records, excluded_subjects)

```

### priorObservation parameter

The parameter `priorObservation` defines the minimum number of days of
prior observation necessary for drug eras to be taken into account. If
set to NULL, the drug eras are not required to fall within the
*observation_period*. 

```{r, message=FALSE, warning=FALSE}
cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_5",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 30,
  priorUseWashout = 30,
  priorObservation = 30
)

attrition(cdm$simvastin_5) %>% select(number_records, reason, excluded_records, excluded_subjects)
```

### cohortDateRange parameter

The `cohortDateRange` parameter defines the range for the
*cohort_start_date* and *cohort_end_date*.

```{r, message=FALSE, warning=FALSE}
cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_6",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 30,
  priorUseWashout = 30,
  priorObservation = 30,
  cohortDateRange = as.Date(c("2010-01-01", "2011-01-01"))
)

attrition(cdm$simvastin_6) %>% select(number_records, reason, excluded_records, excluded_subjects)
```

### limit parameter

The input `limit` allows `all` (default) and `first` options. If we set
it to `first`, we will only obtain the first record that fulfills all
the criteria. Observe how it impacts the attrition of the
**simvastin_7** in comparison to the
**simvastin_6** cohort. The number of records has decreased because of the `First` limit.

```{r, message=FALSE, warning=FALSE}
cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_7",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 30,
  priorUseWashout = 30,
  priorObservation = 30,
  cohortDateRange = as.Date(c("2010-01-01", "2011-01-01")),
  limit = "First"
)

attrition(cdm$simvastin_7) %>% select(number_records, reason, excluded_records, excluded_subjects)
```

If we just wanted to get the first-ever era, we can also use this
parameter. To achieve that, try the following setting:

```{r}
cdm <- generateDrugUtilisationCohortSet(cdm,
  name = "simvastin_8",
  conceptSet = conceptSet_ingredient,
  imputeDuration = "none",
  durationRange = c(0, Inf),
  gapEra = 0,
  priorUseWashout = Inf,
  priorObservation = 0,
  cohortDateRange = as.Date(c(NA, NA)),
  limit = "First"
)
```

Constructing concept sets and generating various cohorts are the initial
steps in conducting a drug utilisation study. For further guidance on
using getting more information like characteristics from these cohorts,
please refer to the other vignettes.
