---
title: "Introduction to epidesc"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Introduction to epidesc}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
---

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

## Overview

The R package **epidesc** provides the tools to easily compute a series of epidemiological indicators to
characterise different transmission patterns of infectious diseases. The work is based on the publication
[How heterogeneous is the dengue transmission profile in Brazil? A study in six Brazilian states](https://doi.org/10.1371/journal.pntd.0010746) 
published in PLOS Neglected Tropical Diseases by Iasmim Ferreira de Almeida, Raquel Martins Lana and Cláudia Torres Codeço in 2022.

While **epidesc** includes all the descriptors proposed in the original publication, we aim to continuously expand its library of epidemiological descriptors. Contributions are always welcome! Please open an issue or contact us by email to discuss your ideas.

To show the functionality of the package, we load weekly dengue data for municipalities in Rio de Janeiro.

```{r setup}
library(epidesc)

data(dengueRio)
head(dengueRio)
```

## Data requirements

**epidesc** has a few simple data requirements:

1. The input must be a `data.frame` containing the case counts and the corresponding spatial and temporal identifiers with no missing values. 
In the sample dataset, these are the columns `cases` (number of dengue cases), `date` (temporal identifier), and `muni_code` (spatial identifier).
2. The data must be aggregated at the weekly level, with dates stored in `Date` format.
3. Each time series must be regular, with a 7-day interval between consecutive observations. If no cases are reported for a given spatial unit in a particular epidemiological week, that observation must still be included in the dataset with the case count set to zero.
4. If an incidence descriptor is required, the population at risk also needs to be provided.

If any of these requirements are not met, the package function will throw error messages to let you know what is happening. 

## Formatting dates

The only required pre-processing step is to convert the dates into epidemiological *yearweek* format: yyyyww. We can easily do so by using the function `epiyearweek` as follows.
Note that `epiyearweek` lets you choose whether epidemiological weeks start on a Sunday or a Monday via the `start` argument; Brazilian epidemiological weeks start on a Sunday:

```{r}
dengue <- dengueRio
dengue$yearweek <- epiyearweek(dengue$date, start = "Sunday")
head(dengue)
```

If you would like to check the start and end dates of the epidemiological weeks in the example data, you can access: [https://portalsinan.saude.gov.br/calendario-epidemiologico-2017](https://portalsinan.saude.gov.br/calendario-epidemiologico-2017). 

> 📝 **NOTE**: For years where there is an epiweek 53, cases are split between week 52 and week 1 of the following year so that all years have 52 weeks. 
This behaviour is controlled by the argumant `collapse53` in the function `desc_year`, which is TRUE by default since it is recommended to do so.

## Descriptor list

To see the list of available descriptors and their required parameters, we can use the function `desc_list()`:

```{r, eval = FALSE}
desc_list()
```

```{r, echo=FALSE}
knitr::kable(desc_list())
```

In this table we can see each indicator's class, function name, description, and required parameters.
We will need this is information when we specify which descriptors we want to compute.

## Computing descriptors

The first step when computing the descriptors is to decide which ones to compute and what values to use for the parameters.
In our case, we are interested in computing the following indicators:

* *Ap*
* *Cmax* with 'x' equal to 5
* *Cnf* with 'n' equal to 3 and 'x' equal to 5
* *Inc* for 100,000 persons

To compute these descriptors, we need to pass a nested list to the `desc_year` function. In the first level, we state the output descriptors names that we would like to use, and in the second level, we specify the name of the function `fun` as in the table above as well as the parameters (`x`, `n` or `p` depending on the descriptor): 

```{r}
descriptors <- list(
  Ap = list(fun = "Ap"),
  Cmax = list(fun = "Cmax", x = 5),
  Cnf = list(fun = "Cnf", n = 3, x = 5),
  Inc = list(fun = "Inc", p = 100000)
)
```

The last detail we need to consider is the epidemiological week we want to use as the start
of the year for computing yearly descriptors. For many diseases, such as dengue in Brazil, the start of the season does not coincide with the 1st of January but rather it occurs much later in the year, so it makes more sense to use this time point. We can specify the first epidemiological week with the argument `sweek`. In our example, we set it to week 41, meaning that yearly descriptors for year `t` will be computed starting from week 41 of year `t` until week 40 of year `t+1`.

Now we are ready to finally compute our descriptors with a call to `desc_year`:

```{r}
res <- desc_year(
  data = dengue,            # Input data frame
  cases = "cases",          # Name of the column of the cases
  time = "yearweek",        # Name of the column with the epiyearweek
  space = "muni_code",      # Name of the column with the spatial ID
  pop = "pop",              # Column with population, needed because of 'Inc'
  sweek = 41,               # Starting epiweek 41 for dengue in Brazil
  descriptors = descriptors # Descriptor list
)
```

Our descriptors have been computed! Let's have a look at the results of epidemiological year 2020 (from W41-2020 to W40-2021):

```{r}
head(res[res$epiyear == "2020/2021", ])
```

Descriptors are calculated only for **complete epidemiological years**. If an epidemiological year has missing weeks or missing case records, the corresponding descriptors will be returned as NA. This typically occurs at the beginning and end of a time series, where the first or last epidemiological year is incomplete.

For example, although the dataset starts in the first SE of 2017, the epidemiological year 2016/2017 begins in epidemiological week 41 of 2016. Because data are only available from 2017 onward, this epidemiological year is incomplete and its descriptors are returned as NA. The same applies to the final epidemiological year if the dataset ends before all epidemiological weeks are available (e.g., 2022).

```{r}
head(res[res$epiyear == "2016/2017", ])
head(res[res$epiyear == "2022/2023", ])
```