CTRE/README.Rmd at master · strakaps/CTRE · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

# CTRE

[![Travis-CI Build Status](https://api.travis-ci.org/UNSW-MATH/CTRE.svg?branch=master)](https://travis-ci.org/UNSW-MATH/CTRE)
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/CTRE)](https://cran.r-project.org/package=CTRE)
[![Downloads](http://cranlogs.r-pkg.org/badges/CTRE)](https://cran.r-project.org/package=CTRE)
[![DL_Total](http://cranlogs.r-pkg.org/badges/grand-total/CTRE?color=blue)](https://cran.r-project.org/package=CTRE)

The CTRE package fits a CTRE model ("Continuous Time Random Exceedances")
to extremes of 'bursty' time series.

+ A [bursty](https://en.wikipedia.org/wiki/Burstiness) time series typically
  has heavy-tailed inter-arrival times.
+ Given a high threshold, the times between threshold crossings follow a
  [Mittag-Leffler](https://strakaps.github.io/MittagLeffleR/) distribution,
  whose scale parameter increases with the threshold.

The magnitudes of the extremes are modelled via the
[POT](https://en.wikipedia.org/wiki/Extreme_value_theory#Data_analysis)
("Peaks-Over-Threshold") method, which is standard in Extreme Value Theory.
It is the time between threshold crossings that is the focus of the CTRE model.

## Installation

### Stable release on CRAN

You can install `CTRE` from CRAN via

```{r CRAN-installation, eval = FALSE}
install.packages("CTRE")
library(CTRE)
```

### Development version on Github

Install the `devtools` package first, then

```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("strakaps/CTRE")
library("CTRE")
```

## Usage

Below is the main workflow for fitting a CTRE model to a time series.
See the [Reference page](/CTRE/reference/index.html) for more details on each
R function.

* Create a [`ctre`](/CTRE/reference/ctre.html) object from a time series,
  a data frame, or two vectors.
* Plot it with [`plot`](/CTRE/reference/plot.ctre.html)
* Discard the data below a threshold with [`thin`](/CTRE/reference/thin.html)
* Extract data with [`interarrival`](/CTRE/reference/interarrival.html),
  [`time`](/CTRE/reference/time.html) and
  [`magnitudes`](/CTRE/reference/magnitudes.html)
* Create stability plots with [`MLestimates`](/CTRE/reference/MLestimates.html)
* Look at diagnostic plots
  ([`mlqqplot`](/CTRE/reference/mlqqplot.html), [`acf`](/CTRE/reference/acf.html),
  [`empcopula`](/CTRE/reference/empcopula.html))


## Shiny App

+ The package comes with two examples of bursty time series: solar flare
magnitudes and bitcoin trading volumes.
+ For parameter estimates of the Mittag-Leffler distribution, see the tab
"Exceedance Times".
+ For the POT model fit, see the tab "Exceedances"
+ CTRE model assumptions are checked via
    - a QQ plot of the Mittag-Leffler distribution
    - an empirical copula plot checking for dependence between
      inter-arrival times and magnitudes
    - a plot of the autocorrelation function for the two series (interarrival
      times and magnitudes).

To run the Shiny app from within RStudio:

```{r, eval=FALSE}
runCTREshiny()
```

<div>
<iframe src="https://strakaps.shinyapps.io/ctre-app/" style="border: none; width: 800px; height: 900px"></iframe>
</div>


## The CTRE paper

"Peaks Over Threshold for Bursty Time Series",
Katharina Hees, Smarak Nayak, Peter Straka (2018).
<https://arxiv.org/abs/1802.05218>