EVI: Epidemic Volatility Index as an Early-Warning Tool

Description

This is an R package implementing the epidemic volatility index (EVI), as discussed by Kostoulas et. al. (2021) and variations by Pateras et. al. (2023). EVI is a new, conceptually simple, early warning tool for oncoming epidemic waves. EVI is based on the volatility of newly reported cases per unit of time, ideally per day, and issues an early warning when the volatility change rate exceeds a threshold.

Author(s)

Maintainer: Konstantinos Pateras kostas.pateras@gmail.com

Authors:

• Eletherios Meletis emeletis@outlook.com

• Paolo Eusebi paoloeusebi@gmail.com

• Matt Denwood md@sund.ku.dk

• Polychronis Kostoulas pkost@uth.gr

See Also

Useful links:

• https://www.nature.com/articles/s41598-021-02622-3

Cases of the first 149 days of the Covid-19 pandemic in Austria.

Description

A data frame containing the number of cases for the first 149 days of the Covid-19 pandemic in Austria

Usage

data(Austria)

Format

A data frame with 149 rows and 3 variables:

Date

ID of date encoded with origin="01-01-1970".

Cases

Number of newly observed cases per day.

Cum_Cases

Cumulative number of newly observed cases per day.

Source

https://github.com/CSSEGISandData/COVID-19

Cases of the first 149 days of the Covid-19 pandemic in Italy.

Description

A data frame containing the number of cases for the first 149 days of the Covid-19 pandemic in Italy.

Usage

data(Italy)

Format

A data frame with 149 rows and 3 variables:

Date

ID of date encoded with origin="01-01-1970".

Cases

Number of newly observed cases per day.

Cum_Cases

Cumulative number of newly observed cases per day.

Source

https://github.com/CSSEGISandData/COVID-19

Calculation of the convergence Epidemic Volatility Index

Description

This sencondary function produces the convergence Epidemic Volatility Index based on input data.

Usage

cEVI_fun(cases, lag_n, c_n)

Arguments

Value

• Dates: the date for each time point (with origin 01-01-1970).

• Days: the serial number for each time point.

• EVI: the estimated EVI for each time point.

References

Pateras K, Meletis E, Denwood M, et al. The convergence epidemic index (cEVI) an early warning tool for identifying waves in an epidemic. Inf Dis Mod, (2023)

Examples

cEVI_fun(cases=c(0,0,1,3,4,10,40,90,105,160,210,301,510,670,680,650,670,665),lag_n=3,c_n=0.1)

This function produces the Epidemic Volatility Index based output data (beta)

Description

This is a secondary function of the EVI-package that you should use to analyze a time series of observed cases per unit of time (ideally per day). This function is based on ongoing work and should be used with caution.

Usage

deviant(
  new_cases,
  cum = FALSE,
  r_a = 7,
  r = 0.2,
  lag_max = 30,
  past = 364/2,
  method = "EVI"
)

Arguments

Details

For each time point the stored variables are:

Value

• Dates: the date for each time point (with origin 01-01-1970).

• Days: the serial number for each time point.

• EVI: the estimated EVI for each time point.

• Cases: the rolling average of the newly observed cases for each time point. A 7-day rolling average is calculated by default (i.e., r_a=7). The user has the option to change this by modifying r_a.

• 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.

References

Kostoulas P, Meletis E, Pateras K, et al. The epidemic volatility index, a novel early warning tool for identifying new waves in an epidemic. Sci Rep 11, 23775 (2021). doi:10.1038/s41598-021-02622-3 Pateras K, Meletis E, Denwood M, et al. The convergence epidemic index (cEVI) an early warning tool for identifying waves in an epidemic. Inf Dis Mod, (2023). doi:10.1016/j.idm.2023.05.001

Examples

data("Italy")
deviant(new_cases=Italy$Cases[35:55], cum=FALSE, r_a=7, r=0.2, lag_max=30,method="EVI")
#deviant(new_cases=Italy$Cases, cum=FALSE, r_a=7, r=0.2, lag_max=30,method="EVI")
#This step should take some time and the time elapsed will be printed.

# data("Austria")
# deviant(new_cases=Austria$Cases, cum=FALSE, r_a=7, r=0.2, lag_max=30,method="EVI")

This function is used after first running the deviant function

Description

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 early warnings for the new cases that are recorded. After running the deviant_update() function the output of the deviant function is also updated with a new row of data for each newly observed time point.

Usage

deviant_update(
  all_cases = NA,
  new_cases = NA,
  EVI_input,
  cum = FALSE,
  r_a = 7,
  r = 0.2,
  lag_max = 30,
  method = "EVI",
  past = 364/2
)

Arguments

References

Pateras K, Meletis E, Denwood M, et al. The convergence epidemic index (cEVI) an early warning tool for identifying waves in an epidemic. Inf Dis Mod, (2023). doi:10.1016/j.idm.2023.05.001 Kostoulas P, Meletis E, Pateras K, et al. The epidemic volatility index, a novel early warning tool for identifying new waves in an epidemic. Sci Rep 11, 23775 (2021). doi:10.1038/s41598-021-02622-3

Examples

## Single update ##
# If we have first observed only the 148 cases from the 
# Italian data we run the deviant function on these cases:

data("Italy")
EVI_output0<-deviant(new_cases=Italy$Cases[20:35], cum=FALSE, r_a=7, r=0.2, lag_max=30)
# EVI_output0<-deviant(new_cases=Italy$Cases[1:148], cum=FALSE, r_a=7, r=0.2, lag_max=30)
# When the number of cases for the next day is 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:

EVI_output0<-deviant_update(new_cases=Italy$Cases[36], 
                            EVI_input=EVI_output0,
                            cum=FALSE, r_a=7, r=0.2, lag_max=30)

# EVI_output0<-deviant_update(new_cases=Italy$Cases[149], 
#                             EVI_input=EVI_output0,
#                             cum=FALSE, r_a=7, r=0.2, lag_max=30)
# The result of running the deviant_update function is to update the output of 
# the deviant_function 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.



# Multiple update steps when new data come using either an EVI or cEVI updater ##
data("Italy")
EVI_output<-deviant(new_cases=Italy$Cases[1:20], cum=FALSE, 
                   r_a=7, r=0.2, lag_max=30,method = "EVI")

EVI_output2<-deviant_update(new_cases = c(100,93,80,54,12), 
                           EVI_input=EVI_output,method = "EVI")

#EVI_output2

# Same as above EVI_output2

#EVI_output2<-deviant_update(all_cases = c(Italy$Cases[1:20],100,93,80,54,12),
#EVI_input=EVI_output,method = "EVI")

#EVI_output2

#EVI_output3<-deviant_update(new_cases = c(2,2,10,1,0),EVI_input=EVI_output2, 
#method = "cEVI")

#EVI_output3

# Even though EVI and cEVI can be used interchangeably, we suggest users to 
# stick to the initial method.

Calculation of the Epidemic Volatility Index

Description

Calculates the relative change in the standard deviation between two consecutive rolling windows.

Usage

evi(rollsd)

Arguments

Examples

data("Italy")
cases = mova(cases=Italy$Cases)
roll = rollsd(cases=cases, lag_t=7)
ev = evi(rollsd=roll)

This function produces plots of the time series data with the EVI predictions.

Description

Three types of plots are generated: (i) 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. (ii) 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). (iii) 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).

Usage

evi.graphs(EVI_output, graph = c("EVI"), ln = T, type = "p")

Arguments

Details

An EVI_output is required as input, derived from the deviant() function.

References

Kostoulas P, Meletis E, Pateras K, et al. The epidemic volatility index, a novel early warning tool for identifying new waves in an epidemic. Sci Rep 11, 23775 (2021). doi:10.1038/s41598-021-02622-3 Pateras K, Meletis E, Denwood M, et al. The convergence epidemic index (cEVI) an early warning tool for identifying waves in an epidemic. Inf Dis Mod, (2023)

Examples

data("Italy")
EVI_output<-deviant(new_cases=Italy$Cases[1:20], cum=FALSE, r_a=7, r=0.2, lag_max=30,method="EVI")
#EVI_output<-deviant(new_cases=Italy$Cases, cum=FALSE, r_a=7, r=0.2, lag_max=30,method="EVI")

evi.graphs(EVI_output=EVI_output, graph="EVI", ln=TRUE)
evi.graphs(EVI_output=EVI_output, graph="PPV", ln=TRUE)
evi.graphs(EVI_output=EVI_output, graph="NPV", ln=TRUE)
evi.graphs(EVI_output=EVI_output, graph="EVI", ln=TRUE, type="l") # For the line EVI plot

Sensitivity-Specificity estimation for each cut-off value and rolling window size

Description

This function calculates the sensitivity and the specificity for each cut-off value and rolling window size.

Usage

evifcut(evi = NA, cevi = NA, cases, cut = NA, r, method = "EVI")

Arguments

Value

Returns a list of the estimated Sensitivity, Specificity, apparent and true prevalence for each cut-off value and rolling window size

References

Kostoulas P, Meletis E, Pateras K, et al. The epidemic volatility index, a novel early warning tool for identifying new waves in an epidemic. Sci Rep 11, 23775 (2021). doi:10.1038/s41598-021-02622-3 Pateras K, Meletis E, Denwood M, et al. The convergence epidemic index (cEVI) an early warning tool for identifying waves in an epidemic. Inf Dis Mod, (2023)

Examples

## EVI Example ##
#data("Italy")
#cases = mova(cases = Italy$Cases)
#roll = rollsd(cases = cases,lag_t = 7)
#ev = evi(rollsd = roll)
#evifcut(evi = ev, cases = cases, cut = 0.01, r = 0.2)

Combining multiple epidemic volatility indices into a multi-early warning index plot

Description

This function returns an overlap graph containing two indices.

1. If index number 1 results in an early warning,then a yellow point will be shown.

2. If index number 2 results in an early warning, then a orange point will be shown.

3. If both indexes result in early warnings, then a red point will be shown.

Usage

evirlap(
  Index1,
  Index2,
  ln = T,
  type = "p",
  size.index = 1,
  Index1.lab = "EVI1",
  Index2.lab = "EVI2",
  Index3.lab = "EVI-",
  Index.country = NULL
)

Arguments

Details

The evirlap function can literally combine any two indices with only 2 requirements. The two vectors (Index1, Index2) to be of equal length and to contain either 0s (no warnings) or 1s (warnings).

For each time point the stored variables are:

Value

• evirlap: A graph with two EVI indexes shown simulteounsly.

References

Pateras K, Meletis E, Denwood M, et al. The convergence epidemic index (cEVI) an early warning tool for identifying waves in an epidemic. Inf Dis Mod, (2023)

Examples

# Run basic functions to acquire early warnings results
#data('Italy')
#EVI_output=deviant(new_cases=Italy$Cases, cum=FALSE, method="EVI")
#cEVI_output=deviant(new_cases=Italy$Cases, cum=FALSE, method="cEVI")

# Plot the EVI combination graph
#evirlap(Index1=EVI_output, Index2=cEVI_output, ln=TRUE)
#evirlap(Index1=EVI_output, Index2=cEVI_output, ln=TRUE, type="l") # For the line EVI plot

# Austria first 150 case example
#data('Austria')
#tmp_EVI_at=deviant(new_cases = Austria$Cases)
#tmp_cEVI_at=deviant(new_cases = Austria$Cases,lag_max = 40,method = "cEVI")
#evirlap(Index1 = tmp_EVI_at,Index2 = tmp_cEVI_at)

Issue of an Early Warning

Description

This secondary function produces the early warning signal (Index).

Usage

indic(evi = NA, cevi = NA, cut = NA, cases, method = "EVI")

Arguments

Value

A vector of 0s and 1s is produced, where a 1 (Index = 1) is recorded when an early warning is issued and a 0 (Index = 0) when an early warning is not issued.

References

Kostoulas P, Meletis E, Pateras K, et al. The epidemic volatility index, a novel early warning tool for identifying new waves in an epidemic. Sci Rep 11, 23775 (2021). doi:10.1038/s41598-021-02622-3 Pateras K, Meletis E, Denwood M, et al. The convergence epidemic index (cEVI) an early warning tool for identifying waves in an epidemic. Inf Dis Mod, (2023)

Examples

## EVI example ##

data("Italy")
cases = mova(cases = Italy$Cases, r_a = 7)
roll = rollsd(cases = cases, lag_t = 7)
ev = evi(rollsd = roll)
ind=indic(evi = ev, cut = 0.01, cases = cases)

Function that calculates the standard deviation

Description

Calculates and returns the standard deviation of a vector

Usage

medvol(x)

Arguments

Examples

x=c(2,2,1,4,9,10,23,10,9,10,14,12,10)
medvol(x)

Function that calculates the moving average of a time series

Description

Calculates the moving average for a time series.

Usage

mova(cases, r_a = 7)

Arguments

Examples

data("Italy")
mova(cases=Italy$Cases, r_a=7)
mova(cases=Italy$Cases, r_a=14)

Rolling standard deviation

Description

-A function to compute the rolling standard deviation for a time series.

Usage

rollsd(cases, lag_t)

Arguments

Examples

data("Italy")
cases = mova(cases=Italy$Cases, r_a=7)
roll = rollsd(cases=cases,lag_t=7)

A function that defines the true status based on the case definition

Description

Status = 1 when the expected rise in the number of cases occurs and Status = 0 when the expected rise in the number of cases does not occur

Usage

status(cases, r)

Arguments

Examples

data("Italy")
cases = mova(cases=Italy$Cases)
status = status(cases=cases, r=0.2)