---
title: "Summarise observation period"
output: 
  html_document:
    pandoc_args: [
      "--number-offset=1,0"
      ]
    number_sections: yes
    toc: yes
vignette: >
  %\VignetteIndexEntry{summarise_observation_period}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Introduction

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

In this vignette, we will explore the *OmopSketch* functions designed to provide an overview of the `observation_period` table. Specifically, there are 3 key functions that facilitate this:

-   `summariseObservationPeriod()`: get some overall statistics describing the `observation_period` table
-   `plotObservationPeriod()`: create plots showing the results
-   `tableObservationPeriod()`: display the results in a formatted table

## Create a mock cdm

Let's see an example of its functionalities. To start with, we will load essential packages and create a mock cdm using the R package [omock](https://ohdsi.github.io/omock/).

```{r, warning=FALSE}
library(dplyr)
library(OmopSketch)
library(omock)

# Connect to mock database
cdm <- mockCdmFromDataset(datasetName = "GiBleed", source = "duckdb")
```

# Summarise observation periods

Let's now use the `summariseObservationPeriod()` function from the **OmopSketch** package to generate an overview of the `observation_period` table.  
This function provides both a general summary of the table and some detailed statistics, such as the **Number of subjects** and the **Duration in days** for each observation period (e.g., first, second, etc.).


```{r, warning=FALSE}
summarisedResult <- summariseObservationPeriod(cdm = cdm)

summarisedResult
```

Notice that the output is in the [summarised result](https://darwin-eu.github.io/omopgenerics/articles/summarised_result.html) format.

We can use the function arguments to specify which summary statistics to compute. For instance, the estimates argument allows us to define which estimates we want to calculate for variables such as the Duration in days of the observation period or the Number of records per person.

```{r, warning=FALSE}
summarisedResult <- summariseObservationPeriod(
  cdm = cdm,
  estimates = c("mean", "sd", "q05", "q95")
)

summarisedResult |>
  filter(variable_name == "Duration in days") |>
  select(group_level, variable_name, estimate_name, estimate_value)
```

By default, the function returns statistics for the **Number of subjects**, **Duration in days**, and **Days to next observation** both overall and by each ordinal observation period (for example, first, second, etc.).

If we are only interested in overall statistics rather than those broken down by ordinal period, we can set the argument `byOrdinal = FALSE`:

```{r, warning=FALSE}
summarisedResult <- summariseObservationPeriod(
  cdm = cdm,
  estimates = c("mean", "sd", "q05", "q95"), 
  byOrdinal = FALSE
)

summarisedResult |>
  filter(variable_name == "Duration in days") |>
  distinct(group_name, group_level)
```

## Missingness

When the argument `missingData = TRUE` is set, the results will include an overall summary of missing data in the table, including the number of `0`s in the concept columns. 
This output is analogous to the results produced by the OmopSketch function `summariseMissingData()`.

```{r, warning=FALSE}
summarisedResult <- summariseObservationPeriod(
  cdm = cdm,
  estimates = c("mean", "sd", "q05", "q95"), 
  missingData = TRUE
)

summarisedResult |>
  filter(variable_name == "Column name") |>
  select(group_level, variable_name, estimate_name, estimate_value)
```


## Quality

When the argument `quality = TRUE` is set, the results will include a quality assessment of the observation period table.  
This assessment provides information such as:

- Issues with date columns (e.g., start dates occurring after end dates, or dates preceding a subject’s birth date).  
- The presence of `person_id` values that do not exist in the `person` table.
- A summary of the types of concept_id available in the table.

```{r, warning=FALSE}
summarisedResult <- summariseObservationPeriod(
  cdm = cdm,
  estimates = "mean", 
  missingData = FALSE, 
  quality = TRUE
)

summarisedResult |>
  select(group_level, variable_name, variable_level, estimate_name, estimate_value)
```

## Strata

It is also possible to stratify the results by sex and age groups:

```{r, warning=FALSE, eval=FALSE}
summarisedResult <- summariseObservationPeriod(
  cdm = cdm,
  estimates = c("mean", "sd", "q05", "q95"),
  sex = TRUE,
  ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf)),
)
```

Notice that, by default, the "overall" group will be also included, as well as crossed strata (that means, `sex == "Female"` and `ageGroup == "\>35"`).

## Tidy the summarised object

`tableObservationPeriod()` will help you to create a table (see supported types with: `visOmopResults::tableType()`). By default it creates a [gt](https://gt.rstudio.com/) table.

```{r, warning=FALSE}
summarisedResult <- summariseObservationPeriod(
  cdm = cdm,
  estimates = c("mean", "sd", "q05", "q95"),
  sex = TRUE
)

summarisedResult |>
  tableObservationPeriod(type = "gt")
```

## Visualise the results

Finally, we can visualise the result using `plotObservationPeriod()`.

```{r, warning=FALSE}
summarisedResult <- summariseObservationPeriod(cdm = cdm)

plotObservationPeriod(
  result = summarisedResult,
  variableName = "Number subjects",
  plotType = "barplot"
)
```

Note that either `Number subjects` or `Duration in days` can be plotted. For `Number of subjects`, the plot type can be `barplot`, whereas for `Duration in days`, the plot type can be `barplot`, `boxplot`, or `densityplot`."

Additionally, if results were stratified by sex or age group, we can further use `facet` or `colour` arguments to highlight the different results in the plot. To help us identify by which variables we can colour or facet by, we can use [visOmopResult](https://darwin-eu.github.io/visOmopResults/) package.

```{r, warning=FALSE}
summarisedResult <- summariseObservationPeriod(cdm = cdm, sex = TRUE)

plotObservationPeriod(
  result = summarisedResult,
  variableName = "Duration in days",
  plotType = "boxplot",
  facet = "sex"
)

summarisedResult <- summariseObservationPeriod(
  cdm = cdm,
  sex = TRUE,
  ageGroup = list("<35" = c(0, 34), ">=35" = c(35, Inf))
)

plotObservationPeriod(
  result = summarisedResult,
  colour = "sex",
  facet = "age_group"
)
```

# Disconnect from CDM

Finally, disconnect from the mock CDM.

```{r}
cdmDisconnect(cdm = cdm)
```
