---
title: "Standardise OMOP results"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{omop}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r base, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  warning = FALSE, 
  message = FALSE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)
```

# Introduction
This vignette illustrates how `EpiStandard` can be used to standardise results from the `IncidencePrevalence` package, a DARWIN-EU package for estimating incidence and prevalence from data mapped to the OMOP Common Data Model.

## Set-up

We first load the relevant packages and then create a mock OMOP-formatted dataset containing a population and an outcome of interest.

```{r cdm}
library(EpiStandard)
library(IncidencePrevalence)
library(omopgenerics)
library(dplyr)

cdm <- mockIncidencePrevalence(
  sampleSize = 10000,
  outPre = 0.25
)
```

## Estimate Incidence Rates

We use the IncidencePrevalence package to generate a denominator cohort with age and sex stratifications, and then calculate overall outcome incidence and incidence by calendar year for each stratum combination. For more information on how to use this package, refer to its [website](https://darwin-eu.github.io/IncidencePrevalence/).

Notice that the results are stored as a [summarised_result](https://darwin-eu.github.io/omopgenerics/articles/summarised_result.html) object.
 
```{r crude inc}
cdm <- generateDenominatorCohortSet(
  cdm = cdm,
  name = "denominator",
  cohortDateRange = as.Date(c("2008-01-01", "2020-01-01")),
  ageGroup = list(c(0, 19), c(20, 64), c(65, 150), c(0, 150)),
  sex = c("Male", "Female"),
  daysPriorObservation = 0
)

inc <- estimateIncidence(
  cdm = cdm,
  denominatorTable = "denominator",
  outcomeTable = "outcome",
  interval = c("years", "overall"),
  outcomeWashout = 0,
  repeatedEvents = FALSE
)

inc |> glimpse()
```
To use `EpiStandard`, we first filter the incidence results to the age groups of interest for standardisation and then convert the results into a format that facilitates further manipulation.

## Standardise Incidence Rates

```{r tidy inc}
incidenceTidy <- inc |>
  filterSettings(denominator_age_group %in% c("0 to 19", "20 to 64", "65 to 150")) |>
  asIncidenceResult()

incidenceTidy |> glimpse()
```

Now that the incidence results are in the correct format, we prepare the reference population. In this example, we use the European Standard Population (`esp2013`). As this population uses 5-year age bands, we merge these groups to match those used to estimate incidence.

```{r standard pop}
standardPop <- mergeAgeGroups(
  standardPopulation("Europe"),
  newGroups = c("0 to 19", "20 to 64", "65 to 150")
) |>
  rename("denominator_age_group" = "age_group")
standardPop |> glimpse()
```


Finally, we use the `directlyStandardiseRates()` function to standardise the incidence results to the reference population. We specify the columns containing the event counts, person-years, and population weights, as well as the column identifying age groups. Since we want to standardise within each outcome, sex, and calendar-time stratum, we use the `strata` argument as follows:

```{r standard inc}
standardInc <- directlyStandardiseRates(
  data = incidenceTidy,
  refdata = standardPop,
  event = "outcome_count",
  denominator = "person_years",
  age = "denominator_age_group",
  pop = "pop",
  strata = c("incidence_start_date", "denominator_sex", "analysis_interval", "outcome_cohort_name")
)
standardInc |> glimpse()
```

Note that `incidence_end_date` may differ for the last interval of the study period across age groups; therefore, it was not included in the `strata` argument.
