[Returnanalytics-commits] r3506 - in pkg/FactorAnalytics: . R man vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Mon Aug 11 09:50:40 CEST 2014
Author: pragnya
Date: 2014-08-11 09:50:40 +0200 (Mon, 11 Aug 2014)
New Revision: 3506
Added:
pkg/FactorAnalytics/vignettes/fitTsfm_vignette.Rnw
pkg/FactorAnalytics/vignettes/fitTsfm_vignette.pdf
Removed:
pkg/FactorAnalytics/vignettes/fitTsfm.pdf
Modified:
pkg/FactorAnalytics/DESCRIPTION
pkg/FactorAnalytics/R/fitTsfm.R
pkg/FactorAnalytics/R/fmEsDecomp.R
pkg/FactorAnalytics/R/fmSdDecomp.R
pkg/FactorAnalytics/R/fmVaRDecomp.R
pkg/FactorAnalytics/R/plot.tsfm.r
pkg/FactorAnalytics/R/summary.tsfm.r
pkg/FactorAnalytics/man/fitTsfm.Rd
pkg/FactorAnalytics/man/fmEsDecomp.Rd
pkg/FactorAnalytics/man/fmSdDecomp.Rd
pkg/FactorAnalytics/man/fmVaRDecomp.Rd
pkg/FactorAnalytics/man/plot.tsfm.Rd
pkg/FactorAnalytics/man/summary.tsfm.Rd
Log:
Added .Rnw file for fitTsfm vignette, minor edits to fitTsfm and related functions.
Modified: pkg/FactorAnalytics/DESCRIPTION
===================================================================
--- pkg/FactorAnalytics/DESCRIPTION 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/DESCRIPTION 2014-08-11 07:50:40 UTC (rev 3506)
@@ -28,7 +28,7 @@
ellipse
Imports: corrplot
Suggests:
- testthat, quantmod
+ testthat, quantmod, knitr
LazyLoad: yes
LazyDataCompression: xz
URL: http://r-forge.r-project.org/R/?group_id=579
Modified: pkg/FactorAnalytics/R/fitTsfm.R
===================================================================
--- pkg/FactorAnalytics/R/fitTsfm.R 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/R/fitTsfm.R 2014-08-11 07:50:40 UTC (rev 3506)
@@ -39,7 +39,8 @@
#' of this up-market factor can be interpreted as the number of free put
#' options. Similarly, "TM" follows Treynor-Mazuy (1966), to account for market
#' timing with respect to volatility, and \code{market.sqd=(Rm-Rf)^2} is added
-#' as a factor in the regression. Option "both" adds both of these factors.
+#' as a factor in the regression. Option "both" (default) adds both of these
+#' factors.
#'
#' \subsection{Data Processing}{
#'
@@ -68,7 +69,7 @@
#' See details. Default is "OLS".
#' @param variable.selection the variable selection method, one of "none",
#' "stepwise","subsets","lars". See details. Default is "none".
-#' @param mkt.timing one of "HM", "TM" or "both". Default is NULL. See Details.
+#' @param mkt.timing one of "HM", "TM" or "both" (default). See Details.
#' \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
@@ -104,7 +105,7 @@
#' Where N is the number of assets, K is the number of factors and T is the
#' number of time periods.
#'
-#' @author Eric Zivot, Yi-An Chen and Sangeetha Srinivasan.
+#' @author Eric Zivot, Sangeetha Srinivasan and Yi-An Chen.
#'
#' @references
#' Christopherson, J. A., Carino, D. R., & Ferson, W. E. (2009). Portfolio
@@ -140,7 +141,7 @@
#' data(managers)
#' fit <- fitTsfm(asset.names=colnames(managers[,(1:6)]),
#' factor.names=colnames(managers[,(7:9)]),
-#' mkt.name="SP500 TR", mkt.timing="both", data=managers)
+#' mkt.name="SP500 TR", mkt.timing="HM", data=managers)
#' summary(fit)
#' fitted(fit)
#' # plot actual returns vs. fitted factor model returns for HAM1
@@ -149,6 +150,10 @@
#' # group plot; type selected from menu prompt; auto-looped for multiple plots
#' # plot(fit)
#'
+#' # example: Market-timing factors with robust fit
+#' fit <- fitTsfm(asset.names=colnames(managers[,(1:6)]), factor.names=NULL,
+#' mkt.name="SP500 TR", data=managers, fit.method="Robust")
+#'
#' # example using "subsets" variable selection
#' fit.sub <- fitTsfm(asset.names=colnames(managers[,(1:6)]),
#' factor.names=colnames(managers[,(7:9)]),
@@ -166,7 +171,7 @@
fitTsfm <- function(asset.names, factor.names, mkt.name=NULL, rf.name=NULL,
data=data, fit.method=c("OLS","DLS","Robust"),
variable.selection=c("none","stepwise","subsets","lars"),
- mkt.timing=NULL, control=fitTsfm.control(...), ...) {
+ mkt.timing="both", control=fitTsfm.control(...), ...) {
# record the call as an element to be returned
call <- match.call()
@@ -181,10 +186,6 @@
stop("Invalid argument: variable.selection must be either 'none',
'stepwise','subsets' or 'lars'")
}
- if (xor(is.null(mkt.name), is.null(mkt.timing))) {
- stop("Missing argument: 'mkt.name' and 'mkt.timing' are both required to
- include market-timing factors.")
- }
# extract arguments to pass to different fit and variable selection functions
decay <- control$decay
@@ -220,12 +221,11 @@
# convert all asset and factor returns to excess return form if specified
if (!is.null(rf.name)) {
- cat("Excess returns were computed and used for all assets and factors.")
dat.xts <- "[<-"(dat.xts,,vapply(dat.xts, function(x) x-data.xts[,rf.name],
FUN.VALUE = numeric(nrow(dat.xts))))
} else {
- cat("Note: fitTsfm was NOT asked to compute EXCESS returns. Input returns
- data was used as it is for all factors and assets.")
+ warning("Excess returns were not computed. Returns data were used as input
+ for all factors and assets.")
}
# opt add mkt-timing factors: up.market=max(0,Rm-Rf), market.sqd=(Rm-Rf)^2
Modified: pkg/FactorAnalytics/R/fmEsDecomp.R
===================================================================
--- pkg/FactorAnalytics/R/fmEsDecomp.R 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/R/fmEsDecomp.R 2014-08-11 07:50:40 UTC (rev 3506)
@@ -45,7 +45,7 @@
#' \item{pcES}{N x (K+1) matrix of percentage component contributions to VaR.}
#' Where, \code{K} is the number of factors and N is the number of assets.
#'
-#' @author Eric Zviot, Yi-An Chen and Sangeetha Srinivasan
+#' @author Eric Zviot, Sangeetha Srinivasan and Yi-An Chen
#'
#' @references
#' Epperlein, E., & Smillie, A. (2006). Portfolio risk analysis Cracking VAR
Modified: pkg/FactorAnalytics/R/fmSdDecomp.R
===================================================================
--- pkg/FactorAnalytics/R/fmSdDecomp.R 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/R/fmSdDecomp.R 2014-08-11 07:50:40 UTC (rev 3506)
@@ -33,7 +33,7 @@
#' \item{pcSd}{N x (K+1) matrix of percentage component contributions to SD.}
#' Where, \code{K} is the number of factors and N is the number of assets.
#'
-#' @author Eric Zivot, Yi-An Chen and Sangeetha Srinivasan
+#' @author Eric Zivot, Sangeetha Srinivasan and Yi-An Chen
#'
#' @references
#' Hallerback (2003). Decomposing Portfolio Value-at-Risk: A General Analysis.
Modified: pkg/FactorAnalytics/R/fmVaRDecomp.R
===================================================================
--- pkg/FactorAnalytics/R/fmVaRDecomp.R 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/R/fmVaRDecomp.R 2014-08-11 07:50:40 UTC (rev 3506)
@@ -43,7 +43,7 @@
#' \item{pcVaR}{N x (K+1) matrix of percentage component contributions to VaR.}
#' Where, \code{K} is the number of factors and N is the number of assets.
#'
-#' @author Eric Zivot, Yi-An Chen and Sangeetha Srinivasan
+#' @author Eric Zivot, Sangeetha Srinivasan and Yi-An Chen
#'
#' @references
#' Hallerback (2003). Decomposing Portfolio Value-at-Risk: A General Analysis.
Modified: pkg/FactorAnalytics/R/plot.tsfm.r
===================================================================
--- pkg/FactorAnalytics/R/plot.tsfm.r 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/R/plot.tsfm.r 2014-08-11 07:50:40 UTC (rev 3506)
@@ -75,7 +75,7 @@
#' is \code{TRUE}.
#' @param ... further arguments to be passed to other plotting functions.
#'
-#' @author Eric Zivot, Yi-An Chen and Sangeetha Srinivasan
+#' @author Eric Zivot, Sangeetha Srinivasan and Yi-An Chen
#'
#' @seealso \code{\link{fitTsfm}} and \code{\link{summary.tsfm}} for details
#' about the time series factor model fit, extractor functions and summary
Modified: pkg/FactorAnalytics/R/summary.tsfm.r
===================================================================
--- pkg/FactorAnalytics/R/summary.tsfm.r 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/R/summary.tsfm.r 2014-08-11 07:50:40 UTC (rev 3506)
@@ -37,7 +37,7 @@
#' format the coefficients, standard errors, etc. and additionally give
#' significance stars if \code{signif.stars} is TRUE.
#'
-#' @author Yi-An Chen & Sangeetha Srinivasan.
+#' @author Sangeetha Srinivasan & Yi-An Chen.
#'
#' @seealso \code{\link{fitTsfm}}, \code{\link[stats]{summary.lm}}
#'
Modified: pkg/FactorAnalytics/man/fitTsfm.Rd
===================================================================
--- pkg/FactorAnalytics/man/fitTsfm.Rd 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/man/fitTsfm.Rd 2014-08-11 07:50:40 UTC (rev 3506)
@@ -9,7 +9,7 @@
fitTsfm(asset.names, factor.names, mkt.name = NULL, rf.name = NULL,
data = data, fit.method = c("OLS", "DLS", "Robust"),
variable.selection = c("none", "stepwise", "subsets", "lars"),
- mkt.timing = NULL, control = fitTsfm.control(...), ...)
+ mkt.timing = "both", control = fitTsfm.control(...), ...)
\method{coef}{tsfm}(object, ...)
@@ -40,7 +40,7 @@
\item{variable.selection}{the variable selection method, one of "none",
"stepwise","subsets","lars". See details. Default is "none".}
-\item{mkt.timing}{one of "HM", "TM" or "both". Default is NULL. See Details.
+\item{mkt.timing}{one of "HM", "TM" or "both" (default). See Details.
\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
@@ -122,7 +122,8 @@
of this up-market factor can be interpreted as the number of free put
options. Similarly, "TM" follows Treynor-Mazuy (1966), to account for market
timing with respect to volatility, and \code{market.sqd=(Rm-Rf)^2} is added
-as a factor in the regression. Option "both" adds both of these factors.
+as a factor in the regression. Option "both" (default) adds both of these
+factors.
\subsection{Data Processing}{
@@ -141,7 +142,7 @@
data(managers)
fit <- fitTsfm(asset.names=colnames(managers[,(1:6)]),
factor.names=colnames(managers[,(7:9)]),
- mkt.name="SP500 TR", mkt.timing="both", data=managers)
+ mkt.name="SP500 TR", mkt.timing="HM", data=managers)
summary(fit)
fitted(fit)
# plot actual returns vs. fitted factor model returns for HAM1
@@ -150,6 +151,10 @@
# group plot; type selected from menu prompt; auto-looped for multiple plots
# plot(fit)
+# example: Market-timing factors with robust fit
+fit <- fitTsfm(asset.names=colnames(managers[,(1:6)]), factor.names=NULL,
+ mkt.name="SP500 TR", data=managers, fit.method="Robust")
+
# example using "subsets" variable selection
fit.sub <- fitTsfm(asset.names=colnames(managers[,(1:6)]),
factor.names=colnames(managers[,(7:9)]),
@@ -163,7 +168,7 @@
variable.selection="lars", lars.criterion="cv")
}
\author{
-Eric Zivot, Yi-An Chen and Sangeetha Srinivasan.
+Eric Zivot, Sangeetha Srinivasan and Yi-An Chen.
}
\references{
Christopherson, J. A., Carino, D. R., & Ferson, W. E. (2009). Portfolio
Modified: pkg/FactorAnalytics/man/fmEsDecomp.Rd
===================================================================
--- pkg/FactorAnalytics/man/fmEsDecomp.Rd 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/man/fmEsDecomp.Rd 2014-08-11 07:50:40 UTC (rev 3506)
@@ -73,7 +73,7 @@
ES.decomp$cES
}
\author{
-Eric Zviot, Yi-An Chen and Sangeetha Srinivasan
+Eric Zviot, Sangeetha Srinivasan and Yi-An Chen
}
\references{
Epperlein, E., & Smillie, A. (2006). Portfolio risk analysis Cracking VAR
Modified: pkg/FactorAnalytics/man/fmSdDecomp.Rd
===================================================================
--- pkg/FactorAnalytics/man/fmSdDecomp.Rd 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/man/fmSdDecomp.Rd 2014-08-11 07:50:40 UTC (rev 3506)
@@ -59,7 +59,7 @@
decomp$pcSd
}
\author{
-Eric Zivot, Yi-An Chen and Sangeetha Srinivasan
+Eric Zivot, Sangeetha Srinivasan and Yi-An Chen
}
\references{
Hallerback (2003). Decomposing Portfolio Value-at-Risk: A General Analysis.
Modified: pkg/FactorAnalytics/man/fmVaRDecomp.Rd
===================================================================
--- pkg/FactorAnalytics/man/fmVaRDecomp.Rd 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/man/fmVaRDecomp.Rd 2014-08-11 07:50:40 UTC (rev 3506)
@@ -71,7 +71,7 @@
VaR.decomp$cVaR
}
\author{
-Eric Zivot, Yi-An Chen and Sangeetha Srinivasan
+Eric Zivot, Sangeetha Srinivasan and Yi-An Chen
}
\references{
Hallerback (2003). Decomposing Portfolio Value-at-Risk: A General Analysis.
Modified: pkg/FactorAnalytics/man/plot.tsfm.Rd
===================================================================
--- pkg/FactorAnalytics/man/plot.tsfm.Rd 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/man/plot.tsfm.Rd 2014-08-11 07:50:40 UTC (rev 3506)
@@ -117,7 +117,7 @@
# plot(fit.macro)
}
\author{
-Eric Zivot, Yi-An Chen and Sangeetha Srinivasan
+Eric Zivot, Sangeetha Srinivasan and Yi-An Chen
}
\seealso{
\code{\link{fitTsfm}} and \code{\link{summary.tsfm}} for details
Modified: pkg/FactorAnalytics/man/summary.tsfm.Rd
===================================================================
--- pkg/FactorAnalytics/man/summary.tsfm.Rd 2014-08-11 02:39:12 UTC (rev 3505)
+++ pkg/FactorAnalytics/man/summary.tsfm.Rd 2014-08-11 07:50:40 UTC (rev 3506)
@@ -67,7 +67,7 @@
summary(fit$asset.fit[[1]])
}
\author{
-Yi-An Chen & Sangeetha Srinivasan.
+Sangeetha Srinivasan & Yi-An Chen.
}
\seealso{
\code{\link{fitTsfm}}, \code{\link[stats]{summary.lm}}
Deleted: pkg/FactorAnalytics/vignettes/fitTsfm.pdf
===================================================================
(Binary files differ)
Added: pkg/FactorAnalytics/vignettes/fitTsfm_vignette.Rnw
===================================================================
--- pkg/FactorAnalytics/vignettes/fitTsfm_vignette.Rnw (rev 0)
+++ pkg/FactorAnalytics/vignettes/fitTsfm_vignette.Rnw 2014-08-11 07:50:40 UTC (rev 3506)
@@ -0,0 +1,455 @@
+\documentclass[a4paper]{article}
+\usepackage{Rd}
+\usepackage{amsmath}
+\usepackage[round]{natbib}
+\usepackage{bm}
+\usepackage{verbatim}
+\usepackage[latin1]{inputenc}
+\bibliographystyle{abbrvnat}
+\usepackage{url}
+
+\let\proglang=\textsf
+\renewcommand{\topfraction}{0.85}
+\renewcommand{\textfraction}{0.1}
+\renewcommand{\baselinestretch}{1.5}
+\setlength{\textwidth}{15cm} \setlength{\textheight}{22cm} \topmargin-1cm \evensidemargin0.5cm \oddsidemargin0.5cm
+
+\usepackage{lmodern}
+\usepackage[T1]{fontenc}
+
+% \VignetteIndexEntry{Fitting a time series factor model with 'fitTsfm' in factorAnalytics}
+%\VignetteEngine{knitr::knitr}
+
+\begin{document}
+
+\title{Fitting a Time series Factor Model with fitTsfm in factorAnalytics}
+\author{Sangeetha Srinivasan}
+\maketitle
+
+\begin{abstract}
+The purpose of this vignette is to demonstrate the use of \code{fitTsfm} and related control, analysis and plot functions in the \code{factorAnalytics} package.
+\end{abstract}
+
+\tableofcontents
+\bigskip
+
+\section{Overview}
+
+\subsection{Load Package}
+
+The latest version of the \verb"factorAnalytics" package can be downloaded from R-forge through the following command:
+\begin{verbatim}
+install.packages("factorAnalytics", repos="http://R-Forge.R-project.org")
+\end{verbatim}
+Load the package and it's dependencies.
+<<message=FALSE>>=
+library(factorAnalytics)
+@
+
+\subsection{Summary of related functions}
+Here's a list of the functions and methods demonstrated in this vignette:
+
+\begin{itemize}
+
+\item \verb"fitTsfm(asset.names, factor.names, data, fit.method, variable.selection)": Fits a time series (a.k.a. macroeconomic) factor model for one or more asset returns or excess returns using time series regression. Ordinary least squares-OLS, discounted least squares-DLS and robust regression fitting are possible. Variable selection methods include Step-wise, Subsets and Lars. An object of class \code{"tsfm"} containing the fitted objects, model coefficients, R-squared and residual volatility are returned.
+
+\item \verb"coef(object)": Extracts the coefficient matrix (intercept and factor betas) for all assets fit by the \code{tsfm} object.
+
+\item \verb"fitted(object)": Returns an \code{xts} data object of fitted asset returns from the factor model for all assets.
+
+\item \verb"residuals(object)": Returns an \code{xts} data object of residuals from the fitted factor model for all assets.
+
+\item \verb"fmCov(object, use)": Returns the \code{N x N} symmetric covariance matrix for asset returns based on the fitted factor model. \code{use} specifies how missing values are to be handled.
+
+\item \verb"fmSdDecomp(object)": Returns a list containing the standard deviation of asset returns based on the fitted factor model and the marginal, component and percentage component factor contributions estimated from the given sample. \code{use} specifies how missing values are to be handled.
+
+\item \verb"fmVaRDecomp(object, p, method, invert)": Returns a list containing the value-at-risk for asset returns based on the fitted factor model and the marginal, component and percentage component factor contributions estimated from the given sample. \code{p} and \code{method} specify the confidence level and method to calculate VaR. \code{invert} allows the VaR value to be expressed as a loss (vs. fund's return/profit).
+
+\item \verb"fmEsDecomp(object)": Returns a list containing the expected shortfall for asset returns based on the fitted factor model and the marginal, component and percentage component factor contributions estimated from the given sample. \code{p} and \code{method} specify the confidence level and method to calculate VaR. \code{invert} allows the VaR value to be expressed as a loss (vs. fund's return/profit).
+
+\item \verb"paFm(fit)": Decompose total returns into returns attributed to factors and specific returns. An object of class \code{"pafm"} is returned, with methods for generic functions \code{plot}, \code{summary} and \code{print}.
+
+\item \verb"plot(x)": The \code{plot} method for class \code{"tsfm"} can be used for plotting factor model characteristics of an individual asset or a group of assets (default). The type of individual/group plot can be specified or chosen from a menu prompt (default if type not specified). Further the menu reappears (default) to enable multiple plots for the same asset(s) unless looping is disabled by setting \code{loop=FALSE}.
+
+\item \verb"predict(object, newdata)": The \code{predict} method for class \code{"tsfm"} returns a vector or matrix of predicted values for a new data sample or simulated values.
+
+\item \verb"summary(object, se.type)": The \code{summary} method for class \code{"tsfm"} returns an object of class \code{"summary.tsfm"} containing the summaries of the fitted \code{lm}, \code{lmRob} or \code{lars} objects and the chosen type (HC/HAC) of standard errors and t-statistics to display. Printing the factor model summary object outputs the call, coefficients (with standard errors and t-statistics), r-squared and residual volatility (under the homo-skedasticity assumption) for all assets.
+
+\end{itemize}
+
+\subsection{Data}
+
+The following examples primarily use the \code{managers} dataset from the \verb"PerformanceAnalytics" package. It's an \code{xts} data object with 132 observations on 10 variables; frequency is monthly.
+<<>>=
+data(managers)
+colnames(managers)
+range(index(managers))
+@
+
+In the examples below, the monthly returns for the six hypothetical asset managers (HAM1 through HAM6) will be the explained asset returns. Columns 7 through 9, composed of the EDHEC Long-Short Equity hedge fund index, the S\&P 500 total returns, and the total return series for the US Treasury 10-year bond will serve as explanatory factors. The last column (US 3-month T-bill) can be considered as the risk free rate. The series have unequal histories in this sample and \code{fitTsfm} removes asset-wise incomplete cases (asset's return data combined with respective factors' return data) before fitting a factor model.
+<<>>=
+asset.names <- colnames(managers[,1:6])
+factor.names <- colnames(managers[,7:9])
+mkt.name <- "SP500 TR"
+rf.name <- "US 3m TR"
+@
+
+Typically, factor models are fit using excess returns. If the asset and factor returns are not already in excess return form, \code{rf.name} can be specified to convert returns into excess returns. Similarly, market returns can be specified to add market-timing factors to the factor model.
+
+The \verb"CommonFactors" dataset in the \verb"factorAnalytics" package also provides a collection of common factors as both monthly (\verb"factors.M") and quarterly (\verb"factors.Q") time series.
+<<>>=
+data(CommonFactors)
+names(factors.Q)
+range(index(factors.Q))
+@
+
+\section{Fit a time series factor model}
+
+In a time series or macroeconomic factor model, observable economic time series such as industrial production growth rate, interest rates, market returns and inflation are used as common factors that contribute to asset returns. For example, the famous single factor model by \citet{sharpe1970portfolio} uses the market excess return as the common factor (captures economy-wide or market risk) for all assets and the unexplained returns in the error term represents the non-market firm specific risk. Whereas, \citet{chen1986economic} find that surprise inflation, the spread between long and short-term interest rates and between high and low grade bonds are significantly priced, while the market portfolio, aggregate consumption risk and oil price risk are not priced separately.
+
+\subsection{Excess returns \& Market Timing factors}
+
+Let's take a look at the arguments for \code{fitTsfm}. The default regression fitting method is Ordinary Least Squares (OLS) and all factors are included in the model for all assets; no variable selection method is used. If \code{rf.name} is not specified by the user, perhaps because returns are already in excess return form, all returns are used as input by default.
+<<tidy=TRUE>>=
+args(fitTsfm)
+@
+
+Here's an implementation of Sharpe's single index model for the 6 hypothetical assets described earlier. Since \code{rf.name} was included, excess returns were computed for all asset and factor returns before model fitting. The component \code{asset.fit} contains a list of fitted objects, one 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"}. The different fit and variable selection methods are described in the next section.
+<<>>=
+fit.Sharpe <- fitTsfm(asset.names=asset.names, factor.names="SP500 TR",
+ rf.name="US 3m TR", data=managers)
+names(fit.Sharpe)
+fit.Sharpe
+@
+
+In the following example, market timing factors are included in addition to the 3 other factors available in the \code{managers} dataset. Market timing accounts for the price movement of the general stock market relative to fixed income securities. "HM" follows \citet{henriksson1981market} and $up.market = max(0, R_m-R_f)$, is added as a factor in the regression. Similarly, "TM" follows \citet{treynor1966can}, to account for market timing with respect to volatility, and $market.sqd = (R_m-R_f)^2$ is added as a factor. Option "both" (default) adds both of these factors.
+<<>>=
+# adding up-market timing factor ("HM") to the model
+fit1 <- fitTsfm(asset.names=asset.names, factor.names=factor.names,
+ mkt.name="SP500 TR", mkt.timing="HM", data=managers)
+fit1$beta
+fit1$r2
+fit1$resid.sd
+@
+
+\subsection{Fit methods \& Variable Selection}
+
+Alternatives to "OLS" regression are \verb"robust regression" (resistant to outliers and heteroskedasticity) and \verb"exponentially discounted weights" (accounts for time variation in coefficients). These can be selected via the argument \code{fit.method} as shown below.
+
+<<>>=
+fit2 <- fitTsfm(asset.names=asset.names, factor.names=factor.names,
+ mkt.name="SP500 TR", data=managers, fit.method="Robust")
+fit2$beta
+fit2$r2
+fit2$resid.sd
+@
+
+Notice the lower R-squared values and smaller residual volatilities with robust regression. Figures 1 and 2 give a graphical comparison of the fitted returns for asset "HAM3" and residual volatilities from the factor model fits. Figure 1 depicts the smaller influence that the volatility of Jan 2000 has on the robust regression. Plot options are described in detail in section 4.
+
+<<fig.cap="HAM3 Returns: fit1-OLS (top) vs fit2-Robust (bottom)", fig.show='hold'>>=
+par(mfrow=c(2,1))
+plot(fit1, plot.single=TRUE, which.plot.single=1, asset.name="HAM3", loop=FALSE)
+plot(fit2, plot.single=TRUE, which.plot.single=1, asset.name="HAM3", loop=FALSE)
+@
+
+<<fig.cap="Residual vol: fit1-OLS (left) vs fit2-Robust (right)", fig.width=3, fig.height=2.5, out.width='.49\\linewidth', fig.show='hold'>>=
+par(mfrow=c(1,2))
+plot(fit1, which.plot.group=5, loop=FALSE, xlim=c(0,0.043))
+plot(fit2, which.plot.group=5, loop=FALSE, xlim=c(0,0.043))
+@
+
+By adding more factors in fit1 and fit2, though the R-squared values have improved (when compared to Sharpe's single index model), one might prefer to employ variable selection methods such as \verb"stepwise", \verb"subsets" or \verb"lars" to avoid over-fitting. The method can be selected via the \code{variable.selection} argument. The default \verb"none", uses all the factors and performs no variable selection. \verb"stepwise" performs traditional forward or backward stepwise OLS regression, starting from an initial (given) set of factors and adds factors only if the regression fit, as measured by the Bayesian Information Criterion (BIC) or Akaike Information Criterion (AIC), improves. \verb"subsets" enables subsets selection using \code{regsubsets}; chooses the best performing subset of any given size. \verb"lars" corresponds to least angle regression using \code{lars} with variants "lasso", "lar", "forward.stagewise" or "stepwise".
+
+Remarks:
+\begin{itemize}
+\item Variable selection methods \verb"stepwise" and \verb"subsets" can be combined with any of the fit methods, "OLS", "DLS" or "Robust".
+\item If variable selection method selected is \verb"lars", \code{fit.method} will be ignored.
+\item Refer to the section on \code{fitTsfm.control} for more details on the control arguments to the different variable selection methods.
+\end{itemize}
+
+The next example uses the \verb"lars" variable selection method. The default type and criterion used are \verb"lasso" and the \verb"Cp" statistic. The \verb"subsets" variable selection method is demonstrated next for comparison using the same set of factors. However, the best subset of size 4 for each asset is chosen. Figures 3 and 4 display the factor betas from the two fits.
+<<>>=
+fit.lars <- fitTsfm(asset.names=colnames(managers[,(1:6)]),
+ factor.names=colnames(managers[,(7:9)]), data=managers,
+ rf.name="US 3m TR", mkt.name="SP500 TR")
+fit.lars$beta
+fit.lars$r2
+
+fit.sub <- fitTsfm(asset.names=colnames(managers[,(1:6)]),
+ factor.names=colnames(managers[,(7:9)]), data=managers,
+ rf.name="US 3m TR", mkt.name="SP500 TR",
+ variable.selection="subsets", subset.size=4)
+fit.sub$beta
+fit.sub$r2
+@
+
+<<fig.cap="Factor betas: fit.lars", fig.show='hold'>>=
+plot(fit.lars, which.plot.group=2, loop=FALSE)
+@
+
+<<fig.cap="Factor betas: fit.sub", fig.show='hold'>>=
+plot(fit.sub, which.plot.group=2, loop=FALSE)
+@
+\newpage
+
+\subsection{fitTsfm.control}
+
+Since \code{fitTsfm} calls many different regression fitting and variable selection methods, it made sense to collect all the optional controls for these functions and process them via \code{fitTsfm.control}. This function is meant to be used internally by \code{fitTsfm} when arguments are passed to it via the ellipsis. The use of control parameters was demonstrated with subset.size in the fit.sub example earlier.
+
+<<tidy=TRUE>>=
+args(fitTsfm.control)
+@
+
+Here's an ordered list of control parameters passed by \code{fitTsfm} matched with their respective functions for easy reference. See the corresponding help files for more details on each parameter.
+\begin{itemize}
+\item \verb"lm": "weights","model","x","y","qr"
+\item \verb"lmRob": "weights","model","x","y","nrep"
+\item \verb"step": "scope","scale","direction","trace","steps","k"
+\item \verb"regsubsets": "weights","nbest","nvmax","force.in","force.out","method","really.big"
+\item \verb"lars": "type","normalize","eps","max.steps","trace"
+\item \verb"cv.lars": "K","type","normalize","eps","max.steps","trace"
+\end{itemize}
+
+There are 3 other important arguments passed to \code{fitTsfm.control} that determine the type of factor model fit chosen.
+\begin{itemize}
+\item \verb"decay": Determines the decay factor for \code{fit.method="DLS"}, which performs exponentially weighted least squares, with weights adding to unity.
+\item \verb"subset.size": Number of factors required in the factor model when performing \verb"subsets" selection. This might be meaningful when looking for the best model of a certain size (perhaps for parsimony, perhaps to compare with a different model of the same size, perhaps to avoid over-fitting/ data dredging etc.)
+\item \verb"lars.criterion": An option (one of "Cp" or "cv") to assess model selection for the \code{"lars"} variable selection method. "Cp" is Mallow's Cp statistic and "cv" is K-fold cross-validated mean squared prediction error.
+\end{itemize}
+
+\subsection{Summary, Predict, Coefficients, Fitted values and Residuals}
+
+<<>>=
+methods(class="tsfm")
+@
+
+Many useful generic accessor functions are available for \code{tsfm} fit objects. Here are some examples using the time series factor model fit by \code{fit.sub} earlier. \code{coef()} returns a matrix of estimated model coefficients including the intercept. \code{fitted()} returns an xts data object of the component of asset returns explained by the factor model. \code{residuals()} returns an xts data object of the part of asset returns not explained by the factor model.
+
+\code{summary()} prints standard errors and t-statistics for all estimated coefficients in addition to R-squared values and residual volatilities. Heteroskedasticity and auto-correlation consistent estimates and standard errors are available via the \code{se.type} argument. The returned "summary.tsfm" object also contains the summary objects returned by \code{lm}, \code{lm.Rob} or \code{lars}, which usually give more detailed statistics from the regression fit. \code{predict} uses the fitted factor model to estimate asset returns given a set of new or simulated factor return data.
+
+<<>>=
+coef(fit.sub)
+tail(fitted(fit.sub))
+tail(residuals(fit.sub))
+
+# comparing data, fitted and residual values for HAM1
+tail(merge(fit.sub$data[,1], fitted(fit.sub)[,1], residuals(fit.sub)[,1]))
+
+# printed summary for the time series factor model
+summary(fit.sub, se.type="HAC")
+
+@
+
+\section{Factor Model Covariance \& Risk Decomposition}
+
+\subsection{Factor model covariance}
+
+Following \citet{zivot2006modeling}, $R_(i, t)$, the return on asset $i$ ($i = 1, ..., N$) at time $t$ ($t = 1, ..., T$), is fitted with a factor model of the form,
+\begin{equation}
+R_{i,t} = \alpha_i + \bm\beta_i \: \mathbf{f_t} + \epsilon_{i,t}
+\end{equation}
+where, $\alpha_i$ is the intercept, $\mathbf{f_t}$ is a $K \times 1$ vector of factor returns at time $t$, $\bm\beta_i$ is a $1 \times K$ vector of factor exposures for asset $i$ and the error terms $\epsilon_{i,t}$ are serially uncorrelated across time and contemporaneously uncorrelated across assets so that $\epsilon_{i,t} \sim iid(0, \sigma_i^2)$. Thus, the variance of asset $i$'s return is given by
+\begin{equation}
+var(R_{i,t}) = \bm\beta_i\: var(\mathbf{f_t})\: \bm\beta_i' + \sigma_i^2
+\end{equation}
+
+And, the $N \times N$ covariance matrix of asset returns is
+\begin{equation}
+var(\mathbf{R}) = \bm\Omega = \mathbf{B}\: var(\mathbf{F})\: \mathbf{B}' + \mathbf{D}
+\end{equation}
+where, $R$ is the $N \times T$ matrix of asset returns, $B$ is the $N \times K$ matrix of factor betas, $\mathbf{F}$ is a $K \times T$ matrix of factor returns and $D$ is a diagonal matrix with $\sigma_i^2$ along the diagonal.
+
+\code{fmCov()} computes the factor model covariance from a fitted factor model and uses "pairwise.complete.obs" (default) to handle NAs. Other options for handling missing observations include "everything", "all.obs", "complete.obs" and "na.or.complete".
+
+<<fig.cap="Factor model return correlation (pairwise complete obs)">>=
+fmCov(fit.sub)
+# return correlation plot; Angular Order of the Eigenvectors
+plot(fit.sub, which.plot.group=7, loop=FALSE, order="AOE", method="ellipse",
+ tl.pos = "d")
+@
+
+\subsection{Standard deviation decomposition}
+
+Given the factor model in equation 1, the standard deviation of the asset $i$'s return can be decomposed as follows (based on \citet{meucci2007risk}):
+\begin{align}
+R_{i,t} &= \alpha_i + \bm\beta_i \: \mathbf{f_t} + \epsilon_{i,t} \\
+&= \bm\beta_i^* \: \mathbf{f_t^*}
+\end{align}
+where, $\bm\beta_i^* = (\bm\beta_i \: \sigma_i)$ and $\mathbf{f_t^*} = [\mathbf{f_t'} \: z_t]'$, with $z_t \sim iid(0, 1)$.
+
+By Euler's theorem, the standard deviation of asset $i$'s return is:
+\begin{align}
+Sd.fm_i = \sum_{k=1}^{K+1} cSd_{i,k} = \sum_{k=1}^{K+1} \beta^*_{i,k} \: mSd_{i,k}
+\end{align}
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/returnanalytics -r 3506
More information about the Returnanalytics-commits
mailing list