diff --git a/R/phys2eventtime.R b/R/phys2eventtime.R index e899921..e2db708 100644 --- a/R/phys2eventtime.R +++ b/R/phys2eventtime.R @@ -20,8 +20,8 @@ phys2eventtime <- function(z, events, width=10) { if (is.null(ncol(z))) { stop(paste("'z' should be of class zoo/xts with at least one column. Use '[' with drop = FALSE")) } - if (!any(class(events$when) %in% c("POSIXt", "Date"))) { - stop("events$when should be one of 'Date' or 'date-time' classes.") + if (!any(class(events$when) %in% c("POSIXt", "Date", "integer"))) { + stop("events$when should be one of 'Date', 'date-time' or 'integer' classes.") } if (any(is.na(events$when))) { stop("events$when should not contain NA values.") diff --git a/README.md b/README.md index 5364e14..fc4141e 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,10 @@ es <- eventstudies::eventstudy(firm.returns = StockPriceReturns, plot(es) ``` +Note that `firm.returns` must be a `zoo` object, and `event.list` must be a `data.frame` with columns `name` and `when`. + +If you wish to pass data in absolute values ("levels") instead of as relative return data, pass `is.levels=TRUE` to the `eventstudies` function. + ## Help ```R ?eventstudy diff --git a/vignettes/eventstudies.Rnw b/vignettes/eventstudies.Rnw index c13f788..f2a0d6c 100644 --- a/vignettes/eventstudies.Rnw +++ b/vignettes/eventstudies.Rnw @@ -49,7 +49,7 @@ head(SplitDates) The representation of dates is a data frame with two columns. The first column is the name of the unit of observation which experienced -the event. The second column is the event date. +the event, named \texttt{name}. The second column is the event date, named \texttt{when}. The second thing that is required for doing an event study is data for stock price returns for all the firms. The sample dataset supplied in diff --git a/vignettes/mwe.Rnw b/vignettes/mwe.Rnw new file mode 100644 index 0000000..e0504ff --- /dev/null +++ b/vignettes/mwe.Rnw @@ -0,0 +1,127 @@ +\documentclass[a4paper,11pt]{article} +\usepackage[utf8]{inputenc} +\usepackage{graphicx} +\usepackage{a4wide} +\usepackage[colorlinks,linkcolor=blue,citecolor=red]{hyperref} +\usepackage{natbib} +\usepackage{float} +\usepackage{parskip} +\usepackage{amsmath} +\usepackage{fancyref} +\title{A minimal example of using the \textbf{eventstudies} package in R} +\author{Anshul Singhvi} +\begin{document} + +% \VignetteIndexEntry{A minimal example of using the \textbf{eventstudies} package in R} +% \VignetteDepends{} +% \VignetteKeyword{eventstudies} +% \VignettePackage{eventstudies} + +\maketitle + +% \begin{abstract} +% \end{abstract} +\SweaveOpts{engine=R,pdf=TRUE} + +\section{Creating our dataset} + +We want to create a synthetic dataset which still allows us to perform some kind of event study. We'll take the simplest case of two variables, which ramp up to 1 and remain there. + +In order to perform an event study, we need two data sources: +\begin{itemize} + \item A \texttt{zoo} object which contains the timeseries data for each variable, in one of the following formats: + \begin{itemize} + \item \textbf{Levels}: absolute levels, i.e., raw data values. + \item \textbf{Returns}: $100 \cdot \log\left(\mathop{diff}\left(\mathbf{levels}\right)\right)$. 1 is 1\% in returns data. This is commonly found in e.g. financial datasets. + \end{itemize} + \item A \texttt{data.frame} object which contains the event times and which variable they pertain to. This must have two columns: + \begin{itemize} + \item \texttt{name}: a column which holds the variable names, as they occur in the \texttt{zoo} timeseries object. The \texttt{name} of each row specifies the column of the \texttt{zoo} timeseries object that the event time applies to. + \item \texttt{when}: a column which holds event time. This can be a \texttt{Date}, \texttt{POSIXt}, or \texttt{numeric} value, as long as it works with the time index in the \texttt{zoo} timeseries. + \end{itemize} +\end{itemize} + +We'll begin by creating the timeseries object in zoo. + +\subsection{Creating the data as a \texttt{zoo} object} + +We want to create a timeseries, whose behaviour changes after a certain point in time. +We begin at 0, ascend linearly to reach 1 at the event time, then remain at 1. +We perform this for two variables, \texttt{variable.one} and \texttt{variable.two}. +This is a minimal example, so you can easily see how to structure your own data to work with eventstudies. + +In order to create our dataset, we create one \texttt{zoo} object per variable, then \texttt{cbind} them into the final \texttt{zoo} object. + +<>= +library(zoo) + +variable.one <- zoo(c(seq(0, 1, length.out = 4), c(1, 1, 1, 1, 1, 1))) +variable.two <- zoo(c(seq(0, 1, length.out = 5), c(1, 1, 1, 1, 1))) + +level.zoo.object <- cbind(variable.one, variable.two) +@ + +Note the use of the \texttt{seq} function; it forms a range which goes from zero to one, with \texttt{length.out} steps. + +We can see how these two timeseries look in Figure \Fref{fig:timeseries} + +\begin{figure} + \begin{center} + <>= + plot(level.zoo.object) + @ + \caption{What our synthetic timeseries look like}\label{fig:timeseries} + \end{center} +\end{figure} + +\subsection{Defining event times in a \texttt{data.frame}} + +Now that we've defined the timeseries, we'll also define a \texttt{data.frame} which describes when the events happen. +Here, since we've created the data, we know that the events happen at time 4 for \texttt{variable.one}, and at time 5 for \texttt{variable.two}. +The time values can be of type \texttt{date-time}, \texttt{Date}, or \texttt{integer}. To use integers in R, we use the \texttt{L} suffix, as in \texttt{4L}. + +Note that the column names have to be precisely what is shown here. + +<>= +dates.data.frame <- data.frame( + name = c("variable.one", "variable.two"), + when = c(3L, 4L)) +@ + +\section{Performing the event study} + +Now, we simply perform the event study. +We provide the \textt{level.zoo.object} which we constructed in Section 1.1, +along with the \texttt{dates.data.frame} which we constructed in Section 1.2. + +Here, the zoo object is passed to \texttt{firm.returns} (the name is slightly misleading) and the events dataframe is passed to \texttt{event.list}. + + + +As for parameters, we set \texttt{is.levels = TRUE}, since we are providing absolute data (levels) and not rescaled change data (returns). +If your data is in the returns format as previously described, please set this to \texttt{FALSE}. + +We set \texttt{event.window = 2}, since the data is quite small. +Feel free to set the window value as high or low as necessary, though. + +We set \texttt{type = "None"}, since we aren't running any market model for decorrelation. + +<>= +library(eventstudies) +es <- eventstudy(firm.returns = level.zoo.object, + event.list = dates.data.frame, + event.window = 2, + type = "None", + is.levels = TRUE,) +@ + +\begin{figure} + \begin{center} + <>= + plot(es) + @ + \caption{The event study of our synthetic data}\label{fig:es} + \end{center} +\end{figure} + +\end{document} \ No newline at end of file