earlywarning: Early warning system for a new data point
In gioca77/SAAO: Statistical Analysis of Accident Data

Description Usage Arguments Details Value See Also Examples

View source: R/earlywarning.R

Function to determine and visualize prediction intervals for new, additional data points in a traffic accident time series.

earlywarning(
  accidents,
  exposition = NULL,
  from = NULL,
  until = NULL,
  n = 1e+06,
  pred.level = NULL,
  alternative = "greater",
  output_return = TRUE,
  main = NULL,
  x_axis = NULL,
  max_y = NULL,
  min_y = NULL,
  orientation_x = NULL,
  add_exp = FALSE,
  lang = "en"
)

`accidents`	Either an R date/time or character vector with accident dates. For character vectors, only the following date formats are allowed: '2014-04-22', '2014/04/22', '22.4.2014'.
`exposition`	Optional data frame with exposition data. The first column is the time value, the second column the exposure. If the time value is a specific date (e.g. '22.4.2014'), this is considered as the start date of this exposure. If the time value is a year (format '2010') the exposure is taken for the whole year. Exposure values are extended until a new entry is available. If necessary, the first exposure value is extended backwards. DEFAULT NULL.
`from`	From which date or year (1.1.) the time series should be considered. Optional. If not specified, the 1.1 from the year of the earliest accident is used.
`until`	Until what date or year (31.12) the time series should be considered. Optional. If not specified, the 31.12 from the year of the latest accident is used.
`n`	Number of simulations.
`pred.level`	Level of the prediction interval, if NULL (default) the empirical distribution of the prediction interval, expressed as return periods, is shown.
`alternative`	A character string specifying if the return period / prediction interval are calculated one- or two-sided, must be one of "greater" (default), "two.sided" or "less". You can specify just the initial letter.
`output_return`	TRUE/FALSE Option to show uncertainty ranges as return periods (TRUE) or as probabilities (FALSE). Only active if pred.level is NULL.
`main`	Optional title for the plot.
`x_axis`	Optional, points at which tick-marks are to be drawn.
`max_y`	Optional maximum value for the y-axis.
`min_y`	Optional minimum value for the y-axis, defaults to 0.
`orientation_x`	Alignment of the tick labels on the x-axis; "v" for vertical, "h" for horizontal. By default horizontal alignment is selected for 8 years or less.
`add_exp`	Option to supplement the output plot with the exposure as an additional axis. Furthermore an additional plot of the exposure alone is produced. Only active if exposure is available.
`lang`	Language for output ("en", "fr", "de" or "it"), defaults to "en".

The function provides functionality to evaluate if a new, additional data point in a traffic accident count data time series is compatible with the past evolution of the series. It is based on simulated bootstrap prediction intervals that can also be displayed in the form of return periods. If a new, additional data point is declared as striking, it means that either an exceptional event happened or that there is a disruption in the data generating process.

A specific R object (class_earlywarning) is generated as function output. The main object is the plot with the prediction interval for the newest observation in the time-serie. The function print.class_earlywarning() is used to extract the most important key figures of the analysis. Specifically, the output contains a list of the following elements:

`ci`	Prediction interval or limits for a 5-, 10-, 20- and 100-year event respectively 20%, 10%, 5% and 1% return probabilty for the new value.
`fit`	Output of the count regression model (Negative Binomial or Poisson family.
`return_value`	Return period respectively return probabilty for the new value.
`data`	Prepared data that were used for the analysis.
`test_overdisp`	p-value of the deviance dispersion test.
`pred.level`	Level of the prediction interval.
`plot`	Plot graphical analysis (ggplot-class).
`lang`	Selected language.
`plot_exposition`	Addional plot of the exposition, if available (ggplot-class).

timeseriesanalysis() function to evaluate the trend in a traffic accident time series.

  ex1 <- earlywarning(example_earlywarnung)
  print(ex1)
  plot(ex1)
  summary(ex1)
  summary(ex1$fit)
  ex2 <-earlywarning(example_earlywarnung, pred.level = 0.95)
  ex2
  ex3 <-earlywarning(example_earlywarnung, pred.level = 0.99)
  ex3
  ex4 <- earlywarning(accidents = example1_timeserie, exposition=exposition_ex1, lang = "de")
  plot(ex4)
  ex5 <- earlywarning(accidents = example1_timeserie, exposition=exposition_ex2, add_exp = TRUE, lang = "fr")
  print(ex5)
  plot(ex5$plot_exposition)
  ex6 <- earlywarning(accidents = example3_timeserie, exposition=exposition_ex3, lang = "it")
  summary(ex6)