---
title: "Conversions to and from the incidence class"
author: "Thibaut Jombart, Zhian N. Kamvar"
date: "`r Sys.Date()`"
output:
   rmarkdown::html_vignette:
     toc: true
     toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Conversions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---



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


This vignette documents to types of conversion which can be made using the *incidence* class:

- *'exports'*: conversion from an *incidence* object to another type of object;
   this can be useful for processing incidence data in another software, or for
   reporting results.

- *'imports'*conversion from already computed incidence into an *incidence*
   object; this can be useful for using features of the *incidence* package for
   data handling and plotting with incidence data computed elsewhere.



<br>

# Exporting results

To export results, we first compute semi-weekly incidence (with weeks starting
on Sunday, the beginning of the CDC epiweek) by gender from the simulated Ebola
data used in the [overview
vignette](https://www.repidemicsconsortium.org/incidence/articles/overview.html):

```{r example}
library(outbreaks)
library(incidence)
dat <- ebola_sim$linelist$date_of_onset
i_14 <- incidence(dat, interval = "2 epiweeks", groups = ebola_sim$linelist$gender)
i_14
plot(i_14, border = "white")
```

To export the data to a `data.frame`, one simply needs:

```{r}
as.data.frame(i_14)
```

The first column contains the dates marking the (inclusive) left side of the
time intervals used for computing incidence, and the other columns give counts
for the different groups. This function also has an option for exporting data as
a 'long' format, i.e. with a column for 'groups' and a column for counts. This
format can be useful especially when working with *ggplot2*, which expect data
in this shape:

```{r, long}
df <- as.data.frame(i_14, long = TRUE)
head(df)
tail(df)

## example of custom plot using steps:
library(ggplot2)
ggplot(df, aes(x = dates, y = counts)) + geom_step(aes(color = groups))
```


Finally, note that when ISO weeks are used, these are also reported in the output:

```{r, iso}
i_7 <- incidence(dat, interval = "week")
i_7
plot(i_7, border = "white")
head(as.data.frame(i_7))
tail(as.data.frame(i_7))

```




<br>

# Importing pre-computed incidence

The function `as.incidence` facilitates the conversion of pre-computed
incidences to an *incidence* object. Typically, the input will be imported into
R from a *.csv* file or other spreadsheet formats.


`as.incidence` is a generic with methods for several types of objects (see
`?as.incidence`). The main method is `matrix`, as other types are coerced to
`matrix` first and then passed to `as.incidence.matrix`:

```{r, conversions}
args(incidence:::as.incidence.matrix)
```

The only mandatory argument `x` is a table of counts, with time intervals in
rows and groups in columns; if there are no groups, then the column doesn't need
a name; but if there are several groups, then columns should be named to
indicate group labels. Optionally, `dates` can be provided to indicate the
(inclusive) lower bounds of the time intervals, corresponding to the rows of
`x`; most sensible date formats will do; if indicated as a character string,
make sure the format is `YYYY-mm-dd`, e.g. `2017-04-01` for the 1st April 2017.


Let us illustrate the conversion using a simple vector of incidence:
```{r}
vec <- c(1,2,3,0,3,2,4,1,2,1)

i <- as.incidence(vec)
i

plot(vec, type = "s")
plot(i, border = "white")

```

Assuming the above incidences are computed weekly, we would then use:
```{r}
i <- as.incidence(vec, interval = 7)
i
plot(i, border = "white")

```

Note that in this case, incidences have been treated as per week, and
corresponding dates in days have been computed during the conversion (the first
day is always '1'), so that the first days of weeks 1, 2, 3... are:
```{r}
i$dates
```

In practice, it is best to provide the actual dates marking the lower bounds of
the time intervals. We can illustrate this by a round trip using the example of
the previous section:

```{r, round_trip}
## convertion: incidence --> data.frame:
i_14
df <- as.data.frame(i_14)
head(df)
tail(df)

## conversion: data.frame --> incidence
new_i <- as.incidence(df[group_names(i_14)], df$dates, interval = "2 epiweeks")
new_i

## check round trip
identical(new_i, i_14)

```