[Eventstudies-commits] r282 - in pkg: R man

noreply at r-forge.r-project.org noreply at r-forge.r-project.org
Thu Apr 3 12:04:54 CEST 2014

Author: chiraganand
Date: 2014-04-03 12:04:54 +0200 (Thu, 03 Apr 2014)
New Revision: 282

Changed the default nlags to NULL, modified structure/text of the manuals, fixed a bug in subperiod.lmAMM to handle xts. Made classes of return values consistent.

Modified: pkg/R/lmAMM.R
--- pkg/R/lmAMM.R	2014-04-02 19:18:50 UTC (rev 281)
+++ pkg/R/lmAMM.R	2014-04-03 10:04:54 UTC (rev 282)
@@ -2,7 +2,7 @@
 ARinnovations <- function(x) {
   stopifnot(NCOL(x) == 1)
   dt <- NULL
-  if (class(x) == "zoo") {
+  if (any(c("xts","zoo") %in% class(x))) {
     dt <- index(x)
     x <- as.numeric(x)
@@ -127,7 +127,7 @@
 ## One regressor, one period AMM estimation
-lmAMM <- function(firm.returns, X, nlags=NA, verbose=FALSE) {
+lmAMM <- function(firm.returns, X, nlags=NULL, verbose=FALSE) {
   do.ols <- function(nlags) {
     tmp <- cbind(firm.returns, X[,1]) # Assume 1st is stock index, and no lags are required there.
     labels <- c("firm.returns","market.returns")
@@ -148,13 +148,14 @@
     lm(firm.returns ~ ., data=as.data.frame(tmp))
-  if (is.na(nlags)) {
-    if (verbose) {cat("Trying to find the best lag structure...\n")}
+  if (is.null(nlags)) {
+    if(verbose) {cat("Trying to find the best lag structure...\n")}
     bestlag <- 0
     bestm <- NULL
     bestAIC <- Inf
     for (trylag in 0:min(10,log10(length(firm.returns)))) {
       thism <- do.ols(trylag)
+      if (is.null(m)) {return(NULL)}
       thisAIC <- AIC(thism, k=log(length(thism$fitted.values)))
       if (verbose) {cat(trylag, " lags, SBC = ", thisAIC, "\n")}
       if (thisAIC < bestAIC) {
@@ -346,5 +347,3 @@
   legend("topleft",legend=c("AMM residual","Firm returns"),lty=1:2, lwd=2,
          col=c("indian red", "navy blue"), bty='n')

Modified: pkg/R/phys2eventtime.R
--- pkg/R/phys2eventtime.R	2014-04-02 19:18:50 UTC (rev 281)
+++ pkg/R/phys2eventtime.R	2014-04-03 10:04:54 UTC (rev 282)
@@ -37,7 +37,7 @@
     return(list(result=remapped, outcome="success"))
-  answer <- apply(events, 1, timeshift)
+  answer <- apply(events, 1, timeshift) #this thing loops on num events
   answer <- unlist(answer, recursive = FALSE)
   rownums <- grep("outcome", names(answer))
   outcomes <- as.character(do.call("c", answer[rownums]))

Modified: pkg/man/ees.Rd
--- pkg/man/ees.Rd	2014-04-02 19:18:50 UTC (rev 281)
+++ pkg/man/ees.Rd	2014-04-03 10:04:54 UTC (rev 282)
@@ -1,14 +1,15 @@
-Extreme events study analysis: Summary statistics
+\title{ Summary statistics of extreme events }
+  This function generates summary statistics for identification and
+  analysis of extreme events. 
-\description{ This function generates summary statistics table from Patnaik, Shah and Singh (2013), using a univariate time series.}
-ees(input, prob.value)
+   ees(input, prob.value)

Modified: pkg/man/lmAMM.Rd
--- pkg/man/lmAMM.Rd	2014-04-02 19:18:50 UTC (rev 281)
+++ pkg/man/lmAMM.Rd	2014-04-03 10:04:54 UTC (rev 282)
@@ -7,60 +7,63 @@
   exposure and residuals.}
-lmAMM(firm.returns, X, nlags = NA, verbose = FALSE)
+   lmAMM(firm.returns, X, nlags = NULL, verbose = FALSE)
+  \item{firm.returns}{a \sQuote{zoo} vector of data for one
+    regressor (firm).
+  }
-  \item{firm.returns}{a \pkg{zoo} time series object of firm returns.}
+  \item{X}{a matrix of regressors obtained by using \sQuote{makeX}. 
+    See \sQuote{Details} when this is specified as a market model. 
+  }
+  \item{nlags}{specifies a lag length required from the specified set
+    of regressors. When unspecified, the best lag using the AIC is used.
+  }
-  \item{X}{a time series of explanatory variables obtained from the
-    \sQuote{makeX} function. See \sQuote{Details}.}
-  \item{nlags}{an \sQuote{integer} with the number of lags of
-    explanatory variables.}
-  \item{verbose}{\sQuote{logical}. Print function details. If
-    \sQuote{TRUE}, print detailed results while running. Default is
-    \sQuote{FALSE}.}
+  \item{verbose}{\sQuote{logical}. If \sQuote{TRUE}, prints details of
+    piece-wise analysis.}
-% FIXME: review/rewrite?
-  The function relates firm returns to the regressors (market
-  index movements, currency fluctuations etc.) using the linear model
-  \sQuote{lm}.  It computes firm exposure for all the regressors in
-  columns of \dQuote{X} and subsequently estimates AMM residuals by
-  purging out variation from the regressand.
+  This function estimates a linear regression model with multiple
+  variables using \sQuote{lm}, stores coefficients as
+  \sQuote{exposures}, and HAC adjusted standard errors as \sQuote{s.exposures}. 
-  Function \sQuote{makeX} is used to prepare the explanatory variables
-  (\dQuote{X}) used in the estimation of AMM. The first variable of
-  \dQuote{X} is always the stock market index. Other variables could be
-  currency, bond returns, or any macro-economic indicator for example.
+  This function is the core engine for other functions that estimate
+  AMMs. Each regression is expected in this package to have a minimum of
+  30 observations, a condition that translates into a month of
+  daily data. If the total number of observations is less than 30, the
+  function returns \sQuote{NULL}. 
+  Function \sQuote{makeX} is used to obtain a matrix of regressors used
+  as input for \sQuote{X}. 
-  If \dQuote{nlags} is \sQuote{NA} (default), then the function finds
+  If \dQuote{nlags} is \sQuote{NULL}, then the function finds
   the best lag structure using the AIC(n).
-  \sQuote{lmAMM} calls the \code{stats::lm} to do the
-  OLS. \sQuote{print} function on an object of \sQuote{class}
+  \sQuote{lmAMM} calls \code{stats::lm} to estimate the linear model.
+  \sQuote{print} function on an object of \sQuote{class}
   \dQuote{amm} can be used to see the call (formula) to \code{lm}.
-\value{The function returns an object of \sQuote{class} \dQuote{amm}.
+\value{The function returns an object of \sQuote{class}
+  \dQuote{amm}; \sQuote{NULL} if \code{nrow(firm.returns) < 30}.
   Function \sQuote{summary} is provided to print a summary of
   results. \sQuote{print} prints the coefficients and exposures of the
   analysis. \sQuote{plot} plots the model residuals and firm returns.
   An object of class \dQuote{amm} is a \sQuote{list} containing the
-  output of \code{stats::lm} function which includes \dQuote{residuals},
+  output of \code{stats::lm} (which includes \dQuote{residuals}),
   along with the following components:
   \item{exposures}{a \sQuote{numeric} containing exposure estimates for
     the firm.}
-  \item{s.exposures}{a \sQuote{numeric} containing the HAC adjusted
+  \item{s.exposures}{a \sQuote{numeric} containing HAC adjusted
     standard error of the exposures estimated for the firm.}
   \item{nlags}{shows the lag length provided by user.}
@@ -88,6 +91,7 @@
           verbose = FALSE)
 a <- lmAMM(firm.returns, X, nlags = 0, verbose = FALSE)

Modified: pkg/man/makeX.Rd
--- pkg/man/makeX.Rd	2014-04-02 19:18:50 UTC (rev 281)
+++ pkg/man/makeX.Rd	2014-04-03 10:04:54 UTC (rev 282)
@@ -1,10 +1,10 @@
-\title{Prepare explanatory variables for computation of Augmented Market
+\title{Prepare regressors for computation of Augmented Market
-\description{\sQuote{makeX} is used to prepare explanatory variables for
+\description{\sQuote{makeX} is used to prepare regressors for
   computation of Augmented Market Models. It can be used to create a
   matrix of explanatory variables in the form specified by the user for
   estimation of AMM.}
@@ -22,44 +22,56 @@
   \item{market.returns}{a univariate timeseries object of \sQuote{class}
-    \pkg{zoo}. It is generally fixed to the stock market index.}
+    \pkg{zoo}. In market models, this is normally the returns of a
+    stock market index.}
-  \item{others}{a \pkg{zoo} matrix with other regressors of interest in the
-    AMM. This could be currency, bond returns, foreign flows, or any
-    other variable.}
+  \item{others}{a \pkg{zoo} matrix of other regressors for the multiple
+  regression model.}
   \item{switch.to.innov}{a \sQuote{logical} vector with an element for
     each column in \dQuote{others} specifying whether to switch the
-    column from raw values to AR residuals. Default is \sQuote{TRUE} for
-    all the columns.}
+    column from raw values to auto-regressive residuals. Default is \sQuote{TRUE} for
+    all the columns. See \sQuote{Details}.}
   \item{market.returns.purge}{a \sQuote{logical} indicating
   whether to purge the effects of \dQuote{others} from
-  \dQuote{market.returns}.}
+  \dQuote{market.returns}. See \sQuote{Details}.}
- \item{nlags}{The number of lag terms present in this model explaining
-   \dQuote{market.returns} using all these \dQuote{others}.}
+ \item{nlags}{ a integer specifying the number of lags required when
+   \sQuote{market.returns.purge} is \sQuote{TRUE}.}
- \item{dates}{Specified break dates as \sQuote{Date} object.}
+ \item{dates}{ a \sQuote{Date} vector, default set to \sQuote{NULL},
+ specifying breaks. See \sQuote{Details}.} 
- \item{verbose}{Whether detailed output is required. Default is
-   \sQuote{FALSE}.}
+ \item{verbose}{ a \sQuote{logical} value, with the default being
+   \sQuote{FALSE}, specifying whether detailed output is required.} 
-\details{ Augmented market model (AMM) purges out the variation of market returns and variable of interest as specified in \sQuote{others}, from the dependent variable. This function creates the regressors for the AMM model using market returns and \sQuote{others}. 
+  This function prepares the regressors of interest for the purpose of
+  running aumgmented market models.
+  The \sQuote{logical} vector \sQuote{switch.to.innov} is applicable
+  only to the regressors in \sQuote{others} matrix and not to the time
+  series vector in \sQuote{market.returns}. 
+  When \sQuote{market.returns.purge} is \sQuote{TRUE}, residuals from a
+  regression of \sQuote{market.returns} on \sQuote{others} is
+  obtained. If \sQuote{dates} are provided, this regression is done
+  within sub-periods as identified by the \sQuote{dates} vector. When
+  \sQuote{dates} is set to default value of \sQuote{NULL}, the start and
+  end points of \sQuote{market.returns} is taken as the period for
+  estimation. 
 \section{Warning}{The input data should not contain \sQuote{NA}s, as is
-  required by the \dQuote{lm} function to compute linear estimates. Please use
+  required by the \dQuote{lm} function to estimate a linear regression. Please use
   \sQuote{na.omit} before feeding data into this function.}
-\value{This function generates a user specified matrix of explanatory
-  variables that will be further used in running Augmented market
-  models.}
+\value{a time-series object of regressors is returned.}
 \author{Ajay Shah, Vimal Balasubramaniam}

Modified: pkg/man/phys2eventtime.Rd
--- pkg/man/phys2eventtime.Rd	2014-04-02 19:18:50 UTC (rev 281)
+++ pkg/man/phys2eventtime.Rd	2014-04-03 10:04:54 UTC (rev 282)
@@ -55,7 +55,7 @@
   Returns a \sQuote{list} of two elements:
-  \item{z.e}{a \pkg{zoo}/\pkg{xts} object indexed with event time; \dQuote{NULL} if
+  \item{z.e}{a \pkg{zoo} object indexed with event time; \dQuote{NULL} if
   there are no \dQuote{success} in \dQuote{outcomes}.}
   \item{outcomes}{a character vector with outcome definition for each event.}

Modified: pkg/man/subperiod.lmAMM.Rd
--- pkg/man/subperiod.lmAMM.Rd	2014-04-02 19:18:50 UTC (rev 281)
+++ pkg/man/subperiod.lmAMM.Rd	2014-04-03 10:04:54 UTC (rev 282)
@@ -19,7 +19,7 @@
-  \item{firm.returns}{a \sQuote{numeric} vector of data for one
+  \item{firm.returns}{a \sQuote{zoo} vector of data for one
     regressor (firm).

More information about the Eventstudies-commits mailing list