Package 'EVI'

Title: 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.
Authors: Eletherios Meletis [aut], Konstantinos Pateras [aut, cre], Paolo Eusebi [aut], Matt Denwood [aut], Polychronis Kostoulas [aut]
Maintainer: Konstantinos Pateras <[email protected]>
License: GPL (>= 3)
Version: 0.2.0-0
Built: 2025-01-24 05:12:32 UTC
Source: https://github.com/cran/EVI

Help Index


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


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

cases

the time series of the newly observed cases per unit of time (ideally per day).

lag_n

Integer. Restriction of the window size for the rolling window size.

c_n

threshold alpha-level value (0 <= c <= 0.5) for issuing an early warning. If cevi <= c_n an early warning is issued and otherwise is not.

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.

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

new_cases

the time series of the newly observed cases per unit of time (ideally per day).

cum

TRUE or FALSE; TRUE if the time series is recorded as the cumulative number of the reported cases and FALSE (the default) if newly reported cases per unit of time are recorded.

r_a

The window size for the moving average that will be analyzed. If set to 1 the actual observations are analyzed. However, due to the variability of the reported cases between working days and weekends it is recommended that the 7-day moving average is analyzed (i.e. r_a = 7), which is the default for this argument. Users could prefer a longer interval of 14 days or one month (i.e., r_a=14 or 30, respectively).

r

Definition for the minimum difference in the mean number of cases, one week before and after each time point that, if present, should be detected. This is the case definition and the default is 0.2 (with 0 <= r <= 1). A value of r=0.2 means that we have a case when the mean number of the newly observed cases in the next 7 days is at least 20% higher than the mean number of the newly observed cases in the past 7 days.

lag_max

Integer. Restriction of the maximum window size for the rolling window size. The default is set to one month (lag_max=30) to prevent excess volatility of past epidemic waves from affecting the most recent volatility estimates and the ability of EVI to warn for upcoming waves that may be smaller and of lower volatility than previous ones.

past

Integer. Default The full length of the input data series. Restriction on the historical data that EVI/cEVI will use. This is set to 365 (default) to account for a year and aid running times.

method

either "EVI" or "cEVI", default equals to "EVI".

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

all_cases

the time series of the previous and newly observed cases per unit of time (ideally per day).

new_cases

the time series of the newly observed cases per unit of time (ideally per day).

EVI_input

the previous EVI function output

cum

TRUE if the time series is recorded as the cumulative number of the reported cases and FALSE (the default) if newly reported cases per unit of time are recorded.

r_a

The window size for the moving average that will be analyzed. If set to 1 the actual observations are analyzed. However, due to the variability of the reported cases between working days and weekends it is recommended that the 7-day moving average is analyzed (i.e. r_a = 7), which is the default for this argument. Users could prefer a longer interval of 14 days or one month (i.e., r_a=14 or 30, respectively).

r

Definition for the minimum difference in the mean number of cases, one week before and after each time point that, if present, should be detected. This is the case definition and the default is 0.2 (with 0 <= r <= 1). A value of r=0.2 means that we have a case when the mean number of the newly observed cases in the next 7 days is at least 20% higher than the mean number of the newly observed cases in the past 7 days.

lag_max

Integer. Restriction of the maximum window size for the rolling window size. The default is set to one month (lag_max=30) to prevent excess volatility of past epidemic waves from affecting the most recent volatility estimates and the ability of EVI to warn for upcoming waves that may be smaller and of lower volatility than previous ones.

method

either "EVI" or "cEVI", default equals to "EVI".

past

Integer. Default the full length of the input data series. Restriction on the historical data that EVI/cEVI will use. This is fixed and equal to the index used in the deviant function.

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

rollsd

numeric vector - returned and stored as roll from the rollsd() function.

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

EVI_output

output of the deviant() function

graph

Type of graph to be plotted. Options: "EVI", "PPV", "NPV". "EVI" (the default) is giving 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. "PPV" is giving a plot of the confirmed cases with colored dots corresponding to time points with an early warning. Color intensity is increasing with higher PPV. "NPV" is giving a plot of the confirmed cases with colored dots corresponding to time points without an early warning. Color intensity is increasing with higher NPV.

ln

TRUE or FALSE; If TRUE (the default) the output of the graph will be presented on the logarithmic scale. IF FALSE the output data will be presented on the original scale.

type

By default, points are plotted on EVI graphs. In cases where, changes are very sudden or data sparsely available, type="l" introduces lines on top of points for the "EVI" type of graph.

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

evi

numeric vector - object (obtained from the evi function and stored as ev) that corresponds to the relative change in the standard deviation.

cevi

numeric vector - object (obtained from the cevi function and stored as cev) that corresponds to either a positive or negative test.

cases

numeric vector with the number of new cases per unit of time (i.e., daily).

cut

threshold value (0 <= c <= 0.5) for issuing an early warning. If evi >= c, an early warning is issued and otherwise is not.

r

Definition for the minimum difference in the mean number of cases, one week before and after each time point that, if present, should be detected. This is the case definition and the default is 0.2 (with 0 <= r <= 1). A value of r=0.2 means that we have a case when the mean number of the newly observed cases in the next 7 days is at least 20% higher than the mean number of the newly observed cases in the past 7 days.

method

either "EVI" or "cEVI", default equals to "EVI".

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

Index1

e.g. output of the deviant() function

Index2

e.g. output of the deviant() function (e.g. method = cEVI)

ln

TRUE or FALSE; If TRUE (the default) the output of the graph will be presented on the logarithmic scale. IF FALSE the output data will be presented on the original scale.

type

By default, points are plotted on EVI graphs. In cases where, changes are very sudden or data sparsely available, type="l" introduces lines on top of points for the "EVI" type of graph.

size.index

Size of the points, default=1

Index1.lab

Text for index 1, "EVI1"

Index2.lab

Text for index 2, "EVI2"

Index3.lab

Text for index conjuction, "EVI-"

Index.country

Label for country/area/region under analysis

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

evi

numeric vector - object (obtained from the evi function and stored as ev) that corresponds to the relative change in the standard deviation.

cevi

numeric vector - object (obtained from the cevi function and stored as cev) that corresponds to a positive and negative test.

cut

threshold value (0 <= c <= 0.5) for issuing an early warning. If evi >= c an early warning is issued and otherwise is not.

cases

numeric vector with the number of new cases per unit of time (i.e., daily).

method

either "EVI" or "cEVI", default equals to "EVI".

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)

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


Function that calculates the standard deviation

Description

Calculates and returns the standard deviation of a vector

Usage

medvol(x)

Arguments

x

numeric vector

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

cases

the time series of the newly observed cases per unit of time (ideally per day).

r_a

The window size for the moving average that will be analyzed. If set to 1 the actual observations are analyzed. However, due to the variability of the reported cases between working days and weekends it is recommended that the 7-day moving average is analyzed (i.e. r_a = 7), which is the default for this argument. Users could prefer a longer interval of 14 days or one month (i.e., r_a=14 or 30, respectively).

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

cases

the time series of the newly observed cases per unit of time (ideally per day).

lag_t

integer - the size of the rolling window for which the rolling standard deviation is calculated (minimum/default value = 7, maximum recommended value = 30).

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

cases

the time series of the newly observed cases per unit of time (ideally per day).

r

Definition for the minimum difference in the mean number of cases, one week before and after each time point that, if present, should be detected. This is the case definition and the default is 0.2 (with 0 <= r <= 1). A value of r=0.2 means that we have a case when the mean number of the newly observed cases in the next 7 days is at least 20% higher than the mean number of the newly observed cases in the past 7 days.

Examples

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