[Returnanalytics-commits] r3600 - in pkg/FactorAnalytics: . R man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Mon Feb 9 21:05:44 CET 2015
Author: chenyian
Date: 2015-02-09 21:05:44 +0100 (Mon, 09 Feb 2015)
New Revision: 3600
Added:
pkg/FactorAnalytics/R/fitTsfmUpDn.r
pkg/FactorAnalytics/man/fitTsfmUpDn.Rd
Modified:
pkg/FactorAnalytics/NAMESPACE
pkg/FactorAnalytics/R/fitTsfmLagBeta.r
pkg/FactorAnalytics/R/fitTsfmMT.r
pkg/FactorAnalytics/man/fitTsfmLagBeta.Rd
pkg/FactorAnalytics/man/fitTsfmMT.Rd
Log:
The first version of fitTsfmUpDn.r. It is a wrapper function of fitTsfm.r and returns a list object containing "Up" and "Dn". Both are class of "Tsfm".
Modified: pkg/FactorAnalytics/NAMESPACE
===================================================================
--- pkg/FactorAnalytics/NAMESPACE 2015-02-08 01:33:35 UTC (rev 3599)
+++ pkg/FactorAnalytics/NAMESPACE 2015-02-09 20:05:44 UTC (rev 3600)
@@ -32,6 +32,7 @@
export(fitTsfm)
export(fitTsfmMT)
export(fitTsfmLagBeta)
+export(fitTsfmUpDn)
export(fmCov)
export(fmEsDecomp)
export(fmSdDecomp)
Modified: pkg/FactorAnalytics/R/fitTsfmLagBeta.r
===================================================================
--- pkg/FactorAnalytics/R/fitTsfmLagBeta.r 2015-02-08 01:33:35 UTC (rev 3599)
+++ pkg/FactorAnalytics/R/fitTsfmLagBeta.r 2015-02-09 20:05:44 UTC (rev 3600)
@@ -58,8 +58,8 @@
#' @param asset.names vector containing names of assets, whose returns or
#' excess returns are the dependent variable.
#' @param factor.names vector containing names of the macroeconomic factors.
-#' @param mkt.name name of the column for market excess returns (Rm-Rf); this
-#' is necessary to add market timing factors. Default is NULL.
+#' @param mkt.name name of the column for market excess returns (Rm-Rf). It
+#' is required for a lagged Betas factor model.
#' @param rf.name name of the column of risk free rate variable to calculate
#' excess returns for all assets (in \code{asset.names}) and factors (in
#' \code{factor.names}). Default is NULL, and no action is taken.
@@ -142,7 +142,7 @@
#' # load data from the database
#' data(managers)
#'
-#' # example: Market-timing factors with OLS fit
+#' # example: A lagged Beetas model with OLS fit
#' fit <- fitTsfmLagBeta(asset.names=colnames(managers[,(1:6)]),LagBeta=2,
#' factor.names="SP500.TR",mkt.name="SP500.TR",
#' rf.name="US.3m.TR",data=managers)
Modified: pkg/FactorAnalytics/R/fitTsfmMT.r
===================================================================
--- pkg/FactorAnalytics/R/fitTsfmMT.r 2015-02-08 01:33:35 UTC (rev 3599)
+++ pkg/FactorAnalytics/R/fitTsfmMT.r 2015-02-09 20:05:44 UTC (rev 3600)
@@ -58,8 +58,8 @@
#' @param asset.names vector containing names of assets, whose returns or
#' excess returns are the dependent variable.
#' @param factor.names vector containing names of the macroeconomic factors.
-#' @param mkt.name name of the column for market excess returns (Rm-Rf); this
-#' is necessary to add market timing factors. Default is NULL.
+#' @param mkt.name name of the column for market excess returns (Rm-Rf); It
+#' is required for a market timing model.
#' @param rf.name name of the column of risk free rate variable to calculate
#' excess returns for all assets (in \code{asset.names}) and factors (in
#' \code{factor.names}). Default is NULL, and no action is taken.
Added: pkg/FactorAnalytics/R/fitTsfmUpDn.r
===================================================================
--- pkg/FactorAnalytics/R/fitTsfmUpDn.r (rev 0)
+++ pkg/FactorAnalytics/R/fitTsfmUpDn.r 2015-02-09 20:05:44 UTC (rev 3600)
@@ -0,0 +1,205 @@
+#' @title Fit a up and down market factor model using time series regression
+#'
+#' @description This is a wrapper function to fits a up/down market model for one
+#' or more asset returns or excess returns using time series regression.
+#' Users can choose between ordinary least squares-OLS, discounted least
+#' squares-DLS (or) robust regression. Several variable selection options
+#' including Stepwise, Subsets, Lars are available as well. An object of class
+#' \code{"tsfm"} is returned.
+#'
+#' @details
+#' Typically, factor models are fit using excess returns. \code{rf.name} gives
+#' the option to supply a risk free rate variable to subtract from each asset
+#' return and factor to compute excess returns.
+#'
+#' Estimation method "OLS" corresponds to ordinary least squares using
+#' \code{\link[stats]{lm}}, "DLS" is discounted least squares (weighted least
+#' squares with exponentially declining weights that sum to unity), and,
+#' "Robust" is robust regression (using \code{\link[robust]{lmRob}}).
+#'
+#' If \code{variable.selection="none"}, uses all the factors and performs no
+#' variable selection. Whereas, "stepwise" performs traditional stepwise
+#' LS or Robust regression (using \code{\link[stats]{step}} or
+#' \code{\link[robust]{step.lmRob}}), that starts from the initial set of
+#' factors and adds/subtracts factors only if the regression fit, as measured
+#' by the Bayesian Information Criterion (BIC) or Akaike Information Criterion
+#' (AIC), improves. And, "subsets" enables subsets selection using
+#' \code{\link[leaps]{regsubsets}}; chooses the best performing subset of any
+#' given size or within a range of subset sizes. Different methods such as
+#' exhaustive search (default), forward or backward stepwise, or sequential
+#' replacement can be employed.See \code{\link{fitTsfm.control}} for more
+#' details on the control arguments.
+#'
+#' \code{variable.selection="lars"} corresponds to least angle regression
+#' using \code{\link[lars]{lars}} with variants "lasso" (default), "lar",
+#' "stepwise" or "forward.stagewise". Note: If \code{variable.selection="lars"},
+#' \code{fit.method} will be ignored.
+#'
+#'
+#' \subsection{Data Processing}{
+#'
+#' Note about NAs: Before model fitting, incomplete cases are removed for
+#' every asset (return data combined with respective factors' return data)
+#' using \code{\link[stats]{na.omit}}. Otherwise, all observations in
+#' \code{data} are included.
+#'
+#' Note about \code{asset.names} and \code{factor.names}: Spaces in column
+#' names of \code{data} will be converted to periods as \code{fitTsfm} works
+#' with \code{xts} objects internally and colnames won't be left as they are.
+#' }
+#'
+#' @param asset.names vector containing names of assets, whose returns or
+#' excess returns are the dependent variable.
+#' @param factor.names vector containing names of the macroeconomic factors.
+#' @param mkt.name name of the column for market excess returns (Rm-Rf). It
+#' is required for a up/down market model.
+#' @param rf.name name of the column of risk free rate variable to calculate
+#' excess returns for all assets (in \code{asset.names}) and factors (in
+#' \code{factor.names}). Default is NULL, and no action is taken.
+#' @param data vector, matrix, data.frame, xts, timeSeries or zoo object
+#' containing column(s) named in \code{asset.names}, \code{factor.names} and
+#' optionally, \code{mkt.name} and \code{rf.name}.
+#' @param fit.method the estimation method, one of "OLS", "DLS" or "Robust".
+#' See details. Default is "OLS".
+#' @param variable.selection the variable selection method, one of "none",
+#' "stepwise","subsets","lars". See details. Default is "none".
+#' \code{mkt.name} is required if any of these options are to be implemented.
+#' @param control list of control parameters. The default is constructed by
+#' the function \code{\link{fitTsfm.control}}. See the documentation for
+#' \code{\link{fitTsfm.control}} for details.
+#' @param ... arguments passed to \code{\link{fitTsfm.control}}
+#'
+#' @return
+#'
+#' fitTsfmUpDn returns a list object containing \code{Up} and \code{Dn}.
+#' Both \code{Up} and \code{Dn} are class of \code{"tsfm"}.
+#'
+#' fitTsfm returns an object of class \code{"tsfm"} for which
+#' \code{print}, \code{plot}, \code{predict} and \code{summary} methods exist.
+#'
+#' The generic accessor functions \code{coef}, \code{fitted} and
+#' \code{residuals} extract various useful features of the fit object.
+#' Additionally, \code{fmCov} computes the covariance matrix for asset returns
+#' based on the fitted factor model
+#'
+#' An object of class \code{"tsfm"} is a list containing the following
+#' components:
+#' \item{asset.fit}{list of fitted objects for each asset. Each object is of
+#' class \code{lm} if \code{fit.method="OLS" or "DLS"}, class \code{lmRob} if
+#' the \code{fit.method="Robust"}, or class \code{lars} if
+#' \code{variable.selection="lars"}.}
+#' \item{alpha}{length-N vector of estimated alphas.}
+#' \item{beta}{N x K matrix of estimated betas.}
+#' \item{r2}{length-N vector of R-squared values.}
+#' \item{resid.sd}{length-N vector of residual standard deviations.}
+#' \item{fitted}{xts data object of fitted values; iff
+#' \code{variable.selection="lars"}}
+#' \item{call}{the matched function call.}
+#' \item{data}{xts data object containing the assets and factors.}
+#' \item{asset.names}{asset.names as input.}
+#' \item{factor.names}{factor.names as input.}
+#' \item{fit.method}{fit.method as input.}
+#' \item{variable.selection}{variable.selection as input.}
+#' Where N is the number of assets, K is the number of factors and T is the
+#' number of time periods.
+#'
+#' @author Yi-An Chen.
+#'
+#' @references
+#' Christopherson, J. A., Carino, D. R., & Ferson, W. E. (2009). Portfolio
+#' performance measurement and benchmarking. McGraw Hill Professional.
+#'
+#' Efron, B., Hastie, T., Johnstone, I., & Tibshirani, R. (2004). Least angle
+#' regression. The Annals of statistics, 32(2), 407-499.
+#'
+#' Hastie, T., Tibshirani, R., Friedman, J., Hastie, T., Friedman, J., &
+#' Tibshirani, R. (2009). The elements of statistical learning (Vol. 2, No. 1).
+#' New York: Springer.
+#'
+#' Henriksson, R. D., & Merton, R. C. (1981). On market timing and investment
+#' performance. II. Statistical procedures for evaluating forecasting skills.
+#' Journal of business, 513-533.
+#'
+#' Treynor, J., & Mazuy, K. (1966). Can mutual funds outguess the market.
+#' Harvard business review, 44(4), 131-136.
+#'
+#' @seealso The \code{tsfm} methods for generic functions:
+#' \code{\link{plot.tsfm}}, \code{\link{predict.tsfm}},
+#' \code{\link{print.tsfm}} and \code{\link{summary.tsfm}}.
+#'
+#' And, the following extractor functions: \code{\link[stats]{coef}},
+#' \code{\link[stats]{fitted}}, \code{\link[stats]{residuals}},
+#' \code{\link{fmCov}}, \code{\link{fmSdDecomp}}, \code{\link{fmVaRDecomp}}
+#' and \code{\link{fmEsDecomp}}.
+#'
+#' \code{\link{paFm}} for Performance Attribution.
+#'
+#' @examples
+#' # load data from the database
+#' data(managers)
+#'
+#' # example: Up and down market factor model with OLS fit
+#' fitUpDn <- fitTsfmUpDn(asset.names=colnames(managers[,(1:6)]),mkt.name="SP500.TR",
+#' data=managers, fit.method="OLS",control=NULL)
+#' # List object
+#' fitUpDn
+#'
+#' summary(fitUpDn$Up)
+#' summary(fitUpDn$Dn)
+#'
+#' @importFrom PerformanceAnalytics checkData
+#' @importFrom robust lmRob step.lmRob
+#' @importFrom leaps regsubsets
+#' @importFrom lars lars cv.lars
+#'
+#' @export
+
+
+fitTsfmUpDn <- function(asset.names, factor.names=NULL, mkt.name=NULL, rf.name=NULL,
+ data=data, fit.method=c("OLS","DLS","Robust"),
+ variable.selection=c("none","stepwise","subsets","lars"),
+ control=fitTsfm.control(...),...) {
+
+ if (is.null(mkt.name)){
+ stop("Missing argument: mkt.name has to be specified for up and down market model.")
+ }
+
+
+
+ factor.names <- union(factor.names,mkt.name)
+
+ # convert data into an xts object and hereafter work with xts objects
+ data.xts <- checkData(data)
+ # convert index to 'Date' format for uniformity
+ time(data.xts) <- as.Date(time(data.xts))
+
+ # extract columns to be used in the time series regression
+ dat.xts <- merge(data.xts[,asset.names], data.xts[,factor.names])
+ ### After merging xts objects, the spaces in names get converted to periods
+
+ # convert all asset and factor returns to excess return form if specified
+ if (!is.null(rf.name)) {
+ dat.xts <- "[<-"(dat.xts,,vapply(dat.xts, function(x) x-data.xts[,rf.name],
+ FUN.VALUE = numeric(nrow(dat.xts))))
+ warning("Up market is defined as the excess Market returns is no less than 0.")
+ } else {
+ warning("Up market is defined as the Market returns is no less than 0.")
+ }
+
+ mkt <- dat.xts[,mkt.name]
+ # up market
+ dataUp.xts <- dat.xts[mkt >= 0]
+
+ fitUp <- fitTsfm(asset.names=asset.names,factor.names=factor.names,mkt.name=mkt.name,rf.name=rf.name,
+ data=dataUp.xts,fit.method=fit.method,variable.selection=variable.selection,
+ control=control)
+
+
+ # down market
+ dataDn.xts <- dat.xts[mkt < 0]
+ fitDn <- fitTsfm(asset.names=asset.names,factor.names=factor.names,mkt.name=mkt.name,rf.name=rf.name,
+ data=dataDn.xts,fit.method=fit.method,variable.selection=variable.selection,
+ control=control)
+
+return(list(Up = fitUp, Dn = fitDn))
+}
Modified: pkg/FactorAnalytics/man/fitTsfmLagBeta.Rd
===================================================================
--- pkg/FactorAnalytics/man/fitTsfmLagBeta.Rd 2015-02-08 01:33:35 UTC (rev 3599)
+++ pkg/FactorAnalytics/man/fitTsfmLagBeta.Rd 2015-02-09 20:05:44 UTC (rev 3600)
@@ -15,8 +15,8 @@
\item{factor.names}{vector containing names of the macroeconomic factors.}
-\item{mkt.name}{name of the column for market excess returns (Rm-Rf); this
-is necessary to add market timing factors. Default is NULL.}
+\item{mkt.name}{name of the column for market excess returns (Rm-Rf). It
+is required for a lagged Betas factor model.}
\item{rf.name}{name of the column of risk free rate variable to calculate
excess returns for all assets (in \code{asset.names}) and factors (in
@@ -132,7 +132,7 @@
# load data from the database
data(managers)
-# example: Market-timing factors with OLS fit
+# example: A lagged Beetas model with OLS fit
fit <- fitTsfmLagBeta(asset.names=colnames(managers[,(1:6)]),LagBeta=2,
factor.names="SP500.TR",mkt.name="SP500.TR",
rf.name="US.3m.TR",data=managers)
Modified: pkg/FactorAnalytics/man/fitTsfmMT.Rd
===================================================================
--- pkg/FactorAnalytics/man/fitTsfmMT.Rd 2015-02-08 01:33:35 UTC (rev 3599)
+++ pkg/FactorAnalytics/man/fitTsfmMT.Rd 2015-02-09 20:05:44 UTC (rev 3600)
@@ -15,8 +15,8 @@
\item{factor.names}{vector containing names of the macroeconomic factors.}
-\item{mkt.name}{name of the column for market excess returns (Rm-Rf); this
-is necessary to add market timing factors. Default is NULL.}
+\item{mkt.name}{name of the column for market excess returns (Rm-Rf); It
+is required for a market timing model.}
\item{rf.name}{name of the column of risk free rate variable to calculate
excess returns for all assets (in \code{asset.names}) and factors (in
Added: pkg/FactorAnalytics/man/fitTsfmUpDn.Rd
===================================================================
--- pkg/FactorAnalytics/man/fitTsfmUpDn.Rd (rev 0)
+++ pkg/FactorAnalytics/man/fitTsfmUpDn.Rd 2015-02-09 20:05:44 UTC (rev 3600)
@@ -0,0 +1,170 @@
+% Generated by roxygen2 (4.1.0): do not edit by hand
+% Please edit documentation in R/fitTsfmUpDn.r
+\name{fitTsfmUpDn}
+\alias{fitTsfmUpDn}
+\title{Fit a up and down market factor model using time series regression}
+\usage{
+fitTsfmUpDn(asset.names, factor.names = NULL, mkt.name = NULL,
+ rf.name = NULL, data = data, fit.method = c("OLS", "DLS", "Robust"),
+ variable.selection = c("none", "stepwise", "subsets", "lars"),
+ control = fitTsfm.control(...), ...)
+}
+\arguments{
+\item{asset.names}{vector containing names of assets, whose returns or
+excess returns are the dependent variable.}
+
+\item{factor.names}{vector containing names of the macroeconomic factors.}
+
+\item{mkt.name}{name of the column for market excess returns (Rm-Rf). It
+is required for a up/down market model.}
+
+\item{rf.name}{name of the column of risk free rate variable to calculate
+excess returns for all assets (in \code{asset.names}) and factors (in
+\code{factor.names}). Default is NULL, and no action is taken.}
+
+\item{data}{vector, matrix, data.frame, xts, timeSeries or zoo object
+containing column(s) named in \code{asset.names}, \code{factor.names} and
+optionally, \code{mkt.name} and \code{rf.name}.}
+
+\item{fit.method}{the estimation method, one of "OLS", "DLS" or "Robust".
+See details. Default is "OLS".}
+
+\item{variable.selection}{the variable selection method, one of "none",
+"stepwise","subsets","lars". See details. Default is "none".
+\code{mkt.name} is required if any of these options are to be implemented.}
+
+\item{control}{list of control parameters. The default is constructed by
+the function \code{\link{fitTsfm.control}}. See the documentation for
+\code{\link{fitTsfm.control}} for details.}
+
+\item{...}{arguments passed to \code{\link{fitTsfm.control}}}
+}
+\value{
+fitTsfmUpDn returns a list object containing \code{Up} and \code{Dn}.
+Both \code{Up} and \code{Dn} are class of \code{"tsfm"}.
+
+fitTsfm returns an object of class \code{"tsfm"} for which
+\code{print}, \code{plot}, \code{predict} and \code{summary} methods exist.
+
+The generic accessor functions \code{coef}, \code{fitted} and
+\code{residuals} extract various useful features of the fit object.
+Additionally, \code{fmCov} computes the covariance matrix for asset returns
+based on the fitted factor model
+
+An object of class \code{"tsfm"} is a list containing the following
+components:
+\item{asset.fit}{list of fitted objects for each asset. Each object is of
+class \code{lm} if \code{fit.method="OLS" or "DLS"}, class \code{lmRob} if
+the \code{fit.method="Robust"}, or class \code{lars} if
+\code{variable.selection="lars"}.}
+\item{alpha}{length-N vector of estimated alphas.}
+\item{beta}{N x K matrix of estimated betas.}
+\item{r2}{length-N vector of R-squared values.}
+\item{resid.sd}{length-N vector of residual standard deviations.}
+\item{fitted}{xts data object of fitted values; iff
+\code{variable.selection="lars"}}
+\item{call}{the matched function call.}
+\item{data}{xts data object containing the assets and factors.}
+\item{asset.names}{asset.names as input.}
+\item{factor.names}{factor.names as input.}
+\item{fit.method}{fit.method as input.}
+\item{variable.selection}{variable.selection as input.}
+Where N is the number of assets, K is the number of factors and T is the
+number of time periods.
+}
+\description{
+This is a wrapper function to fits a up/down market model for one
+or more asset returns or excess returns using time series regression.
+Users can choose between ordinary least squares-OLS, discounted least
+squares-DLS (or) robust regression. Several variable selection options
+including Stepwise, Subsets, Lars are available as well. An object of class
+\code{"tsfm"} is returned.
+}
+\details{
+Typically, factor models are fit using excess returns. \code{rf.name} gives
+the option to supply a risk free rate variable to subtract from each asset
+return and factor to compute excess returns.
+
+Estimation method "OLS" corresponds to ordinary least squares using
+\code{\link[stats]{lm}}, "DLS" is discounted least squares (weighted least
+squares with exponentially declining weights that sum to unity), and,
+"Robust" is robust regression (using \code{\link[robust]{lmRob}}).
+
+If \code{variable.selection="none"}, uses all the factors and performs no
+variable selection. Whereas, "stepwise" performs traditional stepwise
+LS or Robust regression (using \code{\link[stats]{step}} or
+\code{\link[robust]{step.lmRob}}), that starts from the initial set of
+factors and adds/subtracts factors only if the regression fit, as measured
+by the Bayesian Information Criterion (BIC) or Akaike Information Criterion
+(AIC), improves. And, "subsets" enables subsets selection using
+\code{\link[leaps]{regsubsets}}; chooses the best performing subset of any
+given size or within a range of subset sizes. Different methods such as
+exhaustive search (default), forward or backward stepwise, or sequential
+replacement can be employed.See \code{\link{fitTsfm.control}} for more
+details on the control arguments.
+
+\code{variable.selection="lars"} corresponds to least angle regression
+using \code{\link[lars]{lars}} with variants "lasso" (default), "lar",
+"stepwise" or "forward.stagewise". Note: If \code{variable.selection="lars"},
+\code{fit.method} will be ignored.
+
+
+\subsection{Data Processing}{
+
+Note about NAs: Before model fitting, incomplete cases are removed for
+every asset (return data combined with respective factors' return data)
+using \code{\link[stats]{na.omit}}. Otherwise, all observations in
+\code{data} are included.
+
+Note about \code{asset.names} and \code{factor.names}: Spaces in column
+names of \code{data} will be converted to periods as \code{fitTsfm} works
+with \code{xts} objects internally and colnames won't be left as they are.
+}
+}
+\examples{
+# load data from the database
+data(managers)
+
+# example: Up and down market factor model with OLS fit
+fitUpDn <- fitTsfmUpDn(asset.names=colnames(managers[,(1:6)]),mkt.name="SP500.TR",
+ data=managers, fit.method="OLS",control=NULL)
+ # List object
+ fitUpDn
+
+ summary(fitUpDn$Up)
+ summary(fitUpDn$Dn)
+}
+\author{
+Yi-An Chen.
+}
+\references{
+Christopherson, J. A., Carino, D. R., & Ferson, W. E. (2009). Portfolio
+performance measurement and benchmarking. McGraw Hill Professional.
+
+Efron, B., Hastie, T., Johnstone, I., & Tibshirani, R. (2004). Least angle
+regression. The Annals of statistics, 32(2), 407-499.
+
+Hastie, T., Tibshirani, R., Friedman, J., Hastie, T., Friedman, J., &
+Tibshirani, R. (2009). The elements of statistical learning (Vol. 2, No. 1).
+New York: Springer.
+
+Henriksson, R. D., & Merton, R. C. (1981). On market timing and investment
+performance. II. Statistical procedures for evaluating forecasting skills.
+Journal of business, 513-533.
+
+Treynor, J., & Mazuy, K. (1966). Can mutual funds outguess the market.
+Harvard business review, 44(4), 131-136.
+}
+\seealso{
+The \code{tsfm} methods for generic functions:
+\code{\link{plot.tsfm}}, \code{\link{predict.tsfm}},
+\code{\link{print.tsfm}} and \code{\link{summary.tsfm}}.
+
+And, the following extractor functions: \code{\link[stats]{coef}},
+\code{\link[stats]{fitted}}, \code{\link[stats]{residuals}},
+\code{\link{fmCov}}, \code{\link{fmSdDecomp}}, \code{\link{fmVaRDecomp}}
+and \code{\link{fmEsDecomp}}.
+
+\code{\link{paFm}} for Performance Attribution.
+}
+
More information about the Returnanalytics-commits
mailing list