Help for package EventDetectR

Version:

0.3.5

Title:

Event Detection Framework

Description:

Detect events in time-series data. Combines multiple well-known R packages like 'forecast' and 'neuralnet' to deliver an easily configurable tool for multivariate event detection.

Encoding:

UTF-8

LazyData:

yes

Type:

Package

ByteCompile:

TRUE

BugReports:

https://github.com/frehbach/EventDetectR/issues

URL:

https://github.com/frehbach/EventDetectR

Repository:

CRAN

Depends:

R (≥ 3.1.0)

Imports:

imputeTS, forecast, ggplot2, gridExtra, neuralnet

Suggests:

testthat, utils, caret, e1071

License:

GPL-3

RoxygenNote:

7.1.1

NeedsCompilation:

Packaged:

2020-10-10 15:13:34 UTC; sowmya

Author:

Margarita Rebolledo [aut], Sowmya Chandrasekaran [aut, cre], Frederik Rehbach [aut], Steffen Moritz

[aut]

Maintainer:

Sowmya Chandrasekaran <sowzz.17@gmail.com>

Date/Publication:

2020-10-10 15:50:02 UTC

EventDetectR-package description

Description

Detect events/ anomalies in time-series data.

Details

The EventDetectR package enables detection of events/ anomalies in multivariate time-series data. It combines multiple well-known R packages like 'forecast, 'neuralnet' to deliver an easily configurable tool for event detection.

bedAlgo: postProcessors to classify events

Description

bedAlgo provides the continuous probability of an event at every prediction timestep. The memory about the recent past event is automatically included to predict the future. An event is initiated when the BED probability exceeds the eventThreshold. The probability that the data represents expected normal behavior in 'n' trials is represented as
B(r;n,p)=(n!)/(r!(n-r)!) p^(r) q^((n-r))
where the 'n' trials is given by 'bedWindowSize', 'q' represents the probability that a trial succeeds and 'p' represents the probability that a trial fails as an event. We keep the value of both 'p' and 'q' as 0.5 and hence the equation is simplified to
B(r;n,p)=(n!)(r!(n-r)!)0.5^n
The advantage of this BED is that it helps in reducing the false alarm, while the disadvantage is the slight delay in identifying the true event

Usage

bedAlgo(model)

Arguments

model

model to which the postprocessor shall be added

Value

model model with added postprocessing results

build Event Detection Model

Description

Builds an event detection object (edObject) containing all models and configurations that are used to detect events in given data.

Usage

buildEDModel(
  x,
  dataPrepators = "ImputeTSInterpolation",
  dataPreparationControl = list(),
  buildModelAlgo = "ForecastETS",
  buildForecastModelControl = list(),
  buildNeuralNetModelControl = list(),
  postProcessors = "bedAlgo",
  postProcessorControl = list(),
  ignoreVarianceWarning = FALSE,
  oldModel = NULL
)

Arguments

x

data.frame containing initial data on which the model will be fitted. Data should be free of events. The data should not include a timestamp column

dataPrepators

string or vector of strings, that defines which preparators to use. Lists are not accepted. Usage Example: dataPreparators = "ImputeTSInterpolation" results in the usage of imputeTS::na.interpolation as a data preparator. All possible preparators are listed via: getSupportedPreparations() Can also be set to NULL in order to shut off data preparation

dataPreparationControl

list, control-list containing all additional parameters that shall be passed to the dataPreparators.

buildModelAlgo

string, model name to be used. All possible preparators are listed via: getSupportedModels().

buildForecastModelControl

list, control-list containing all additional parameters that shall be passed to forecast modeling algorithm

buildNeuralNetModelControl

list, control-list containing all additional parameters that shall be passed to the neuralnet modeling algorithm

postProcessors

string or vector of strings, that defines which postProcessors to use. Lists are not accepted. Usage Example: postProcessors = "bedAlgo" results in the usage of bed as a event postProcessing tool. All possible preparators are listed via: getSupportedPostProcessors() Can also be set to NULL in order to shut off data postProcessing

postProcessorControl

list, control-list containing all additional parameters that shall be passed to the postProcessirs.

ignoreVarianceWarning

Ignores the continously appearing warning for missing variance in some variable columns given a smaller windowSize

oldModel

If another model was previously fitted it can be passed to the next model fit. By doing so the eventHistory is preserved

Value

model, event detection object (edObject) containing all models and configurations that are used to detect events in given data.

Examples


## build a simple event detection model with standard configuration
x <- stationBData[100:200,-1]
buildEDModel(x,ignoreVarianceWarning = TRUE)

## Set up a more complex event detection model defining some additional configuration
buildEDModel(x, buildModelAlgo = "ForecastArima",ignoreVarianceWarning = TRUE)

 ## Set up a multivariate neuralnetwork model
buildEDModel(x, buildModelAlgo = "NeuralNetwork",ignoreVarianceWarning = TRUE)

detectEvents in a given data.frame

Description

detectEvents builds a prediction model (edObject) on the first 'windowSize' points of the given data x. The next 'nIterationRefit' data-points are classified as 'Event' or not. The window is moved iteratively and the next models are fitted. The first 'windowSize' points will always be classified as no Event and should only contain 'clean' data

Usage

detectEvents(
  x,
  windowSize = 100,
  nIterationsRefit = 1,
  verbosityLevel = 0,
  dataPrepators = "ImputeTSInterpolation",
  dataPreparationControl = list(),
  buildModelAlgo = "ForecastETS",
  buildForecastModelControl = list(),
  buildNeuralNetModelControl = list(),
  postProcessors = "bedAlgo",
  postProcessorControl = list(),
  ignoreVarianceWarning = TRUE
)

Arguments

x

data.frame, data which shall be classified as event or not

windowSize

amount of data points to consider in each prediction model

nIterationsRefit

amount of points into the future which will be predicted without fitting a new model. E.g. if nIterationsRefit = 10 then the next five dataPoints are classified without refitting.

verbosityLevel

Print output of function progress. 0 -> No output, 1 -> every 100th model building iteration, 2 -> every 10th, 3 -> every iteration

dataPrepators

dataPreparationControl

list, control-list containing all additional parameters that shall be passed to the dataPreparators.

buildModelAlgo

string, model name to be used. All possible preparators are listed via: getSupportedModels().

buildForecastModelControl

list, control-list containing all additional parameters that shall be passed to the forecast modelling algo.

buildNeuralNetModelControl

list, control-list containing all additional parameters that shall be passed to the neuralnet modelling algo.

postProcessors

postProcessorControl

list, control-list containing all additional parameters that shall be passed to the postProcessirs.

ignoreVarianceWarning

Ignores the continously appearing warning for missing variance in some variable columns given a smaller windowSize

Value

edsResults edObject, list of results. $classification -> data.frame containing the T/F event classification

Examples

## Run event detection with default settings:
def <- detectEvents(x = stationBData[1:100,-1])


## Refit the model at every new datapoint,
## have someoutput with verbosityLevel = 2 and ignore
## the variance warning
ed <- detectEvents(stationBData[1:110,-1],nIterationsRefit = 1,
                   verbosityLevel = 2,ignoreVarianceWarning = TRUE)

## Switch to another model: Arima
ed2 <- detectEvents(stationBData[1:110,-1],nIterationsRefit = 1,
                    verbosityLevel = 0,ignoreVarianceWarning = TRUE,
                    buildModelAlgo = "ForecastArima")

   ## Switch to multivariate model: NeuralNetwork
ed3 <- detectEvents(stationBData[1:110,-1],nIterationsRefit = 1, buildModelAlgo = "NeuralNetwork")

Predict Univariate Models Forecast Package

Description

Predict Univariate Models Forecast Package

Usage

eventClassification(object, newData, ...)

Arguments

object

fitted model that shall be predicted

...

additional parameters

Value

eventDetector fittedModel with

geccoIC2018Test

Description

2018s Test set of the gecco industrial challenge - http://www.spotseven.de/gecco/gecco-challenge/

getSupportedModels()

Value

allSupportedModels a list of strings with each supported method name. The strings can be copied and used in calls to 'eventDetect' or 'buildEDModel'

Examples

models <- getSupportedModels()

getSupportedPostProcessors

Description

Get a list of all data postprocessing methods that are currently supported in package 'eventDetectR'.

Usage

getSupportedPostProcessors()

Value

allSupportedPostProcessors a list of strings with each supported method name. The strings can be copied and used in calls to 'eventDetect' or 'buildEDModel'

Examples

preps <- getSupportedPostProcessors()

getSupportedPreparations

Description

Get a list of all data preparation methods that are currently supported in package 'eventDetectR'.

Usage

getSupportedPreparations()

Value

allSupportedPreparations a list of strings with each supported method name. The strings can be copied and used in calls to 'eventDetect' or 'buildEDModel'

Examples

preps <- getSupportedPreparations()

Fitting Neuralnet Models

Description

Fitting Neuralnet Models

Usage

model_NeuralNetwork(x, control)

Arguments

x

data

control

control list with settings

Details

Multivariate Neuralnetwork model is formulated for each of the parameter using its own lagged values and rest of all parameters involved. For instance, considering 3 parameters 'p1', 'p2', 'p3', the value of 'p1' at time step 'i' is calclated as
p1[i] = p2[i] + p3[i] + p1[i-1]
It is recommended to activate the normalization of the data.

Value

fitted multivariate neural network model

Fitting Forecast Models

Description

Fitting Forecast Models

Usage

model_UnivariateForecast(x, strName, control)

Arguments

x

data

strName

name of the Forecast model that shall be fitted

control

control list with settings

Value

fitted Forecast model

Plot an Event Detection Object

Description

Plot an Event Detection Object

Usage

## S3 method for class 'edObject'
plot(x, varsToPlot = names(edObject$classification), ...)

Arguments

x

edObject

varsToPlot

vars

...

Additional parameters

Value

A Plot

Predict MultivariateNeuralNetwork Models neuralnet Package

Description

Predict MultivariateNeuralNetwork Models neuralnet Package

Usage

## S3 method for class 'NeuralNetwork'
predict(object, newData = NULL, ...)

Arguments

object

fitted model that shall be predicted

newData

data.frame with newData that is compared to the models prediction to judge if events occured or not

...

additional parameters

Value

predicted value

Predict Univariate Models Forecast Package

Description

Predict Univariate Models Forecast Package

Usage

## S3 method for class 'UnivariateForecast'
predict(object, newData = NULL, ...)

Arguments

object

fitted model that shall be predicted

newData

data.frame with newData that is compared to the models forecast to judge if events occured or not

...

additional parameters

Value

predicted value

Data Preparation with Impute TS

Description

Data Preparation with Impute TS

Usage

preparator_imputeTS(x, prepStr, control)

Arguments

x

data to process

prepStr

string of preparator name to use

control

control parameters, extra settings

Value

x prepared data

Print an Event Detection Object

Description

Prints the last classification results for an event detection object. If 'nLast' (integer) is given, it specifies the amount of rows to be printed.

Usage

## S3 method for class 'edObject'
print(x, ...)

Arguments

x

edObject, the event detection object that shall be printed

...

any additional parameters

qualityStatistics

Description

Wrapper function for caret::confusionMatrix. qualityStatistics calculates statistics for judging the quality of the eventDetection based on the fitted edModel and a reference dataset

Usage

qualityStatistics(edObject, reference)

Arguments

edObject

The eventdetection object you obtain by running 'detectEvents'

reference

true/false vector, reference vector based on labeled data: which datapoints are real events.

Value

list, Confusion Matrix and Statistics

Examples

train <- geccoIC2018Train[15000:17000,]
edObject <- detectEvents(train[,-c(1,11)],windowSize = 1000,
                nIterationsRefit = 500,verbosityLevel = 2,
                postProcessorControl = list(nStandardDeviationseventThreshold = 3))
qualityStatistics(edObject, train$EVENT)

Imposes simulated events on the top of the data

Description

Simulates Events on columns of a data frame or a matrix by applying different transformations. The events of type sinusoidal, square, binomial or ramp can be used.

Usage

simulateEvents(
  Data,
  Params,
  Event_type,
  Event_strength = NULL,
  Start_index = NULL,
  Event_duration = NULL,
  Percentage = NULL
)

Arguments

Data

Data frame or matrix containing the data to which the events will be introduced

Params

Numeric vector or vector of strings indicating the column names (in case Data is a data frame) or the column numbers (in case Data is a matrix) of the parameters in which an event will be simulated

Event_type

String vector indicating which type of transformation the parameters will undergo. Current valid options include sinusoidal, square, ramp and slowsinusoidal. If Params contains more that one element and Event_type only contains one element the same transformation will be applied to all given Params

Event_strength

(Optional) Numeric Vector indicating the amplitude. Only valid for sinusoidal and square transformations. When specified for other type of transformations it will have no effect. However it must have the same number of elements as Params.

Start_index

Numeric, indicates the index where the event should start

Event_duration

Numeric, indicates the number of steps the transformation should last. Default is 100

Percentage

(Optional) Numeric value from 0 to 1. Alternative input indicating the percentage of data that should be affected by the transformation. Either Event_duration or Percentage should be especified.

Value

Matrix or data frame containing the selected columns with simulated events

Examples


#Generate event of type sinusoidal and ramp on two columns of the stationBData data set
simupar<-c("B_PH_VAL","B_TEMP_VAL")
SimulatedEvents<-simulateEvents(stationBData,
                                simupar,Event_type = c("sinusoidal","ramp"),
                                Start_index = 2500)

#When specifiying Event_strength the lenght of the vector needs to match the number
#of elements in Params.
SimulatedEvents<-simulateEvents(stationBData,
                                simupar,Event_type = c("sinusoidal","ramp"),
                                Start_index = 2500,
                                Percentage = 0.2,
                                Event_strength = c(4,1))

stationBData

Description

Data for package testing purposes