# Epidemic Volatility Index (EVI) Explained

This document aims to provide a short introduction to running the EVI tool, by illustrating a simple example.

For illustration purposes we use the cases of the first 149 days of the COVID-19 pandemic in Italy.

A data frame containing the number of cases for the first 149 days of the COVID-19 pandemic can be stored in R running:

data("Italy")

For each day the number of COVID-19 cases are recorded in the data frame.

## Running the deviant() function

The deviant() function is the main function of the EVI-package that is used to analyze a time series of observed cases per unit of time (ideally per day).

The following call of deviant() runs the EVI tool and returns a data frame named EVI_output that stores for each time point: * Dates: the date for each time point (with origin 01-01-1970) * Days: the serial number for each time point * Cases: the rolling average of the newly observed cases for each time point * Index: takes values 1 or 0 for the issuance of an early warning or not, respectively * ppv: the positive predictive value for each time point * npv: the negative predictive value for each time point * lag_all: the selected rolling window size for EVI calculation for each time point * c_all: the selected cut-off for issuing an early warning for each time point * se_all: the sensitivity (Se) of EVI up to this time point * sp_all: the specificity (Sp) of EVI up to this time point

Let run the deviant() function for the first 49 days.

deviant(new_cases = Italy$Cases[1:49], cum = FALSE, r_a = 7, r = 0.2, lag_max = 30) ## Updater function Once the deviant() function has been used to analyze the already observed time series, the deviant_update() function is used to obtain the EVI output and issue early warnings for the new cases that are recorded. After running the deviant_update() function the output of the deviant() function (EVI_output) is also updated with a new row of data for each newly observed time point. Assuming that we have first observed only the 49 cases from the Italian data and we have run the deviant() function on these cases. Later when the number of cases for the next day (in our example: day 50) are observed we want to obtain the estimates for this day without having to reanalyze the entire time series. This is done by using the deviant_update() function: deviant_update(new_cases=Italy$Cases[1:50], cum=FALSE, r_a=7, r=0.2, lag_max=30)

By running the deviant_update() function the output of the deviant() function is updated by adding an additional row with estimates for the new data. In this example the EVI_output file will now have 149 rows. If two additional days are analyzed two additional rows will be added and so on.

## Plot the EVI_output

Three main types of plots can be generated: * A plot of the confirmed cases with red dots corresponding to time points that an early warning was issued and grey dots corresponding to time points without an early warning indication. * A plot of the confirmed cases with colored dots corresponding to time points with an early warning. Color intensity is increasing with higher positive predictive value (PPV). * A plot of the confirmed cases with colored dots corresponding to time points without an early warning. Color intensity is increasing with higher negative predictive value (NPV).

For the eVI.graphs() function to run an EVI_output is required as input, derived from the deviant() or deviant_update() functions.

## Full example

You can run the deviant() function for the all the observed COVID-19 cases from the first 149 days of the pandemic.

deviant(new_cases = Italy\$Cases, cum = FALSE, r_a = 7, r = 0.2, lag_max = 30)

## Citation

citation("EVI")
##
## To cite package 'EVI' in publications use:
##
##   Eletherios Meletis, Konstantinos Pateras, Paolo Eusebi, Matt Denwood
##   and Polychronis Kostoulas (2022). EVI: Epidemic Volatility Index as
##   an Early-Warning Tool. R package version 0.1.1-4.
##   https://www.nature.com/articles/s41598-021-02622-3
##
## A BibTeX entry for LaTeX users is
##
##   @Manual{,
##     title = {EVI: Epidemic Volatility Index as an Early-Warning Tool},
##     author = {Eletherios Meletis and Konstantinos Pateras and Paolo Eusebi and Matt Denwood and Polychronis Kostoulas},
##     year = {2022},
##     note = {R package version 0.1.1-4},
##     url = {https://www.nature.com/articles/s41598-021-02622-3},
##   }

## This vignette was built with:

sessionInfo()
## R version 4.1.2 (2021-11-01)
## Platform: x86_64-w64-mingw32/x64 (64-bit)
## Running under: Windows 10 x64 (build 19042)
##
## Matrix products: default
##
## locale:
## [1] LC_COLLATE=C                  LC_CTYPE=Greek_Greece.1253
## [3] LC_MONETARY=Greek_Greece.1253 LC_NUMERIC=C
## [5] LC_TIME=Greek_Greece.1253
##
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base
##
## other attached packages:
## [1] EVI_0.1.1-4
##
## loaded via a namespace (and not attached):
##  [1] highr_0.9        bslib_0.3.1      compiler_4.1.2   pillar_1.7.0
##  [5] jquerylib_0.1.4  tools_4.1.2      digest_0.6.29    jsonlite_1.8.0
##  [9] evaluate_0.14    lifecycle_1.0.1  tibble_3.1.6     gtable_0.3.0
## [13] pkgconfig_2.0.3  rlang_1.0.2.9000 DBI_1.1.2        cli_3.2.0
## [17] rstudioapi_0.13  yaml_2.2.1       xfun_0.29        fastmap_1.1.0
## [21] dplyr_1.0.8      stringr_1.4.0    knitr_1.37       generics_0.1.2
## [25] sass_0.4.0       vctrs_0.3.8      tidyselect_1.1.2 grid_4.1.2
## [29] cowplot_1.1.1    glue_1.5.1       R6_2.5.1         fansi_1.0.2
## [33] rmarkdown_2.11   farver_2.1.0     purrr_0.3.4      ggplot2_3.3.5
## [37] magrittr_2.0.1   scales_1.1.1     htmltools_0.5.2  ellipsis_0.3.2
## [41] assertthat_0.2.1 colorspace_2.0-3 labeling_0.4.2   utf8_1.2.2
## [45] stringi_1.7.6    munsell_0.5.0    crayon_1.5.0