
\documentclass[a4paper,11pt]{article}
\usepackage{graphicx}
\usepackage{a4wide}
\usepackage[colorlinks,linkcolor=blue,citecolor=red]{hyperref}
\usepackage{natbib}
\usepackage{float}
\usepackage{tikz}
\usepackage{parskip}
\usepackage{amsmath}
\title{Introduction to the \textbf{extreme events} functionality}
\author{Ajay Shah, Vimal Balasubramaniam and Vikram Bahure}
\begin{document}
%\VignetteIndexEntry{eventstudies: Extreme events functionality}
% \VignetteDepends{}
% \VignetteKeywords{extreme event analysis}
% \VignettePackage{eventstudies}
\maketitle
\begin{abstract}
The \textit{eventstudies} package includes an extreme events
functionality. This package has \textit{ees}
function which does extreme event analysis by fusing the
consecutive extreme events in a single event. The methods and
functions are elucidated by employing data-set of S\&P 500 and Nifty. 
\end{abstract}

\SweaveOpts{engine=R,pdf=TRUE}
\section{Introduction}
Using this function, one can understand the distribution and run
length of the clustered events, quantile values for the extreme
events and yearly distribution of the extreme events. In the sections
below we replicate the analysis for S\&P 500 from the Patnaik, Shah
and Singh (2013) and we generate the extreme event study plot for
event on S\&P 500 and response of NIFTY. A detail methodology is also
discussed in the paper.

\section{Extreme event analysis}
This function needs input in returns format on which extreme
event analysis is to be done. Further, we define tail events for given
probability value. For instance, if \textit{prob.value} is 5 then both
side 5\% tail events are considered as extreme, lower tail and upper
tail (5\% to 95\%).
<<>>==
library(eventstudies)
data(eesData)
input <- eesData$sp500
# Suppress messages
  deprintize<-function(f){
    return(function(...) {capture.output(w<-f(...));return(w);});
  }
output <- deprintize(ees)(input, prob.value=5)
@
% I don't understand this output. Maybe you should explain what it means.
The output is a list and  consists of summary statistics for complete
data-set, extreme event analysis for lower tail and extreme event
analysis for upper tail. Further, these lower tail and upper tail list
objects consists of 5 more list objects with following output:
\begin{enumerate}
\item Extreme events dataset
\item Distribution of clustered and unclustered % events.
\item Run length distribution
\item Quantile values of extreme events
\item Yearly distribution of extreme events
\end{enumerate}

\subsection{Summary statistics}
Here we have data summary for the complete data-set which shows
minimum, 5\%, 25\%, median, mean, 75\%, 95\%, maximum, standard
deviation (sd), inter-quartile range (IQR) and number of
observations. The output shown below matches with the fourth column
in Table 1 of the paper.
<<>>==
output$data.summary
@ 
\subsection{Extreme events dataset} 
The output for upper tail and lower tail are in the same format as
mentioned above. The data-set is a time series object which has 2
columns. The first column is \textit{event.series} column which has
returns for extreme events and the second column is
\textit{cluster.pattern} which signifies the number of consecutive
days in the cluster. Here we show results for the lower tail of S\&P
500. Below is the extreme event data set on which analysis is done.
<<>>=
str(output$lower.tail$data)
@

\subsection{Distribution of clustered and unclustered events}
In the analysis we have clustered, unclustered and mixed clusters. We
remove the mixed clusters and study the rest of the clusters by fusing
them. Here we show, number of clustered and unclustered data used in
the analysis. The \textit{removed.clstr} refers to mixed cluster which
are removed and not used in the analysis.\textit{Tot.used} represents
total number of extreme events used for the analysis which is sum of
\textit{unclstr} (unclustered events) and \textit{used.clstr} (Used
clustered events). \textit{Tot}
are the total number of extreme events in the data set. The results
shown below match with second row in Table 2 of the paper.
<<>>=
output$lower.tail$extreme.event.distribution
@ 

\subsection{Run length distribution of clusters}
Clusters used in the analysis are defined as consecutive extreme
events. Run length shows total number of clusters with \textit{n} consecutive
days. In the example below we have 3 clusters with  \textit{two}
consecutive events and 0 clusters with \textit{three} consecutive
events. The results shown below match with second row in Table 3 of
the paper.
<<>>=
output$lower.tail$runlength
@ 

\subsection{Extreme event quantile values}
Quantile values show 0\%, 25\%, median, 75\%,100\% and mean values for
the extreme events data. The results shown below match with second row
of Table 4 in the paper.
<<>>=
output$lower.tail$quantile.values
@ 

\subsection{Yearly distribution of extreme events}
This table shows the yearly distribution and
the median value for extreme events data. The results shown below
match with third and forth column for S\&P 500 in the Table 5 of the
paper.  
<<>>=
output$lower.tail$yearly.extreme.event
@ 
The yearly distribution for extreme events include unclustered event
and clustered events which are fused. While in extreme event distribution of
clustered and unclustered event, the clustered events are defined as
total events in a cluster. For example, if there is a clustered event
with three consecutive extreme events then yearly distribution will
treat it as one single event. Here below the relationship between the
Tables is explained through equations:\\\\
\textit{Sum of yearly distribution for lower tail = 59 \\ 
Unclustered events for lower tail = 56\\\\
Clustered events for lower tail = 3 + 0\\
Total events in clusters (Adding number of events in each cluster)
= 3*2 + 0*3 = 6\\ 
Total used events = Unclustered events for lower tail + Total events
in clusters \\ = 56 + 6 = 62 \\\\
Sum of yearly distribution for lower tail =  Unclustered events for
lower tail + Total events in clusters\\ = 56 + 3 =59}
<<>>=
sum(output$lower.tail$yearly.extreme.event[,"number.lowertail"])
output$lower.tail$extreme.event.distribution[,"unclstr"]
output$lower.tail$runlength
@ 

\section{Extreme event study plot}
Here, we replicate the Figure 7, from the paper Patnaik, Shah and
Singh (2013). First, we need to have a merged time series object with
event series and response series with no missing values for unerring
results. After getting the time series object we just need to use the
following function and fill the relevant arguments to generate the
extreme event study plot. 

The function generates extreme values for the event series with the
given probability value. Once the values are generated, clustered
extreme events are fused together for the response series and
extreme evenstudy plot is generated for very bad and very good
events. The detail methodology is mentioned in the paper. 
<<>>=
eesPlot(z=eesData, response.series.name="nifty", event.series.name="sp500",
        titlestring="S&P500", ylab="(Cum.) change in NIFTY", prob.value=5, 
        width=5)
@ 
\begin{figure}[t]
  \begin{center}
    \caption{Extreme event on S\&P500 and response of NIFTY}
    \setkeys{Gin}{width=1\linewidth}
    \setkeys{Gin}{height=0.8\linewidth}
<<fig=TRUE,echo=FALSE>>=
res <- deprintize(eesPlot)(z=eesData, response.series.name="nifty", event.series.name="sp500",titlestring="S&P500", ylab="(Cum.) change in NIFTY", prob.value=5, width=5)
@
\end{center}
\label{fig:one}
\end{figure}

\section{Computational details}
The package code is purely written in R. It has dependencies to zoo
(\href{http://cran.r-project.org/web/packages/zoo/index.html}{Zeileis
  2012}) and boot
(\href{http://cran.r-project.org/web/packages/boot/index.html}{Ripley
  2013}).  R itself as well as these packages can be obtained from \href{http://CRAN.R-project.org/}{CRAN}.
%\section{Acknowledgments}

\end{document}
