\HeaderA{PerformanceAnalytics-package}{Econometric tools for performance and risk analysis.}{PerformanceAnalytics.Rdash.package}
\aliasA{PerformanceAnalytics}{PerformanceAnalytics-package}{PerformanceAnalytics}
\keyword{package}{PerformanceAnalytics-package}
\begin{Description}\relax
\kbd{PerformanceAnalytics} provides an \R{} library of econometric functions for performance and risk analysis of financial instruments or portfolios. This library aims to aid practitioners and researchers in using the latest research for analysis of both normally and non-normally distributed return streams.

We created this library to include functionality that has been appearing in the academic literature on performance analysis and risk over the past several years, but had no functional equivalent in \R.  In doing so, we also found it valuable to have wrapper functions for functionality easily replicated in \R, so that we could access that functionality using a function with defaults and naming consistent with common usage in the finance literature.  The following sections cover Time Series Data, Performance Analysis, Risk Analysis (with a separate treatment of VaR), Summary Tables of related statistics, Charts and Graphs, a variety of Wrappers and Utility functions, and some thoughts on work yet to be done.
\end{Description}
\begin{Details}\relax
\Tabular{rl}{
Package: & PerformanceAnalytics\\
License: & GPL\\
Copyright: & (c) 2004-2009 Brian G. Peterson and Peter Carl\\
}

In general, this library requires return (rather than price) data. Almost all of the functions will work with any periodicity, from annual, monthly, daily, to even minutes and seconds.

In this summary, we attempt to provide an overview of the capabilities provided by \kbd{PerformanceAnalytics} and pointers to other literature and resources in \R{} useful for performance and risk analysis.  We hope that this summary and the accompanying package and documentation partially fill a hole in the tools available to a financial engineer or analyst.
\end{Details}
\begin{Section}{Time Series Data}
Not all, but many of the measures in this package require time series data.  \kbd{PerformanceAnalytics} uses the \code{\LinkA{xts}{xts}} package for managing time series data for several reasons.  Besides being fast and efficient, \code{\LinkA{xts}{xts}} includes functions that test the data for periodicity and draw attractive and readable time-based axes on charts.  Another benefit is that \code{\LinkA{xts}{xts}} provides compatability with Rmetrics' \code{\LinkA{timeSeries}{timeSeries}}, \code{\LinkA{zoo}{zoo}} and other time series classes, such that \kbd{PerformanceAnalytics} functions that return a time series will return the results in the same format as the object that was passed in.  Jeff Ryan and Josh Ulrich, the authors of \code{\LinkA{xts}{xts}}, have been extraordinarily helpful to the development of \kbd{PerformanceAnalytics} and we are very greatful for their contributions to the community.  The \code{\LinkA{xts}{xts}} package extends the excellent \code{\LinkA{zoo}{zoo}} package written by Achim Zeileis and Gabor Grothendieck. \code{\LinkA{zoo}{zoo}} provides more general time series support, whereas \code{\LinkA{xts}{xts}} provides functionality that is specifically aimed at users in finance.

Users can easily load returns data as time series for analysis with \kbd{PerformanceAnalytics} by using the \code{\LinkA{Return.read}{Return.read}} function.  The \code{\LinkA{Return.read}{Return.read}} function loads csv files of returns data where the data is organized as dates in the first column and the returns for the period in subsequent columns.  See \code{\LinkA{read.zoo}{read.zoo}} and \code{\LinkA{as.xts}{as.xts}} if more flexibility is needed.

The functions described below assume that input data is organized with asset returns in columns and dates represented in rows.  All of the metrics in \kbd{PerformanceAnalytics} are calculated by column and return values for each column in the results.  This is the default arrangement of time series data in \code{xts}.

See function \code{\LinkA{Return.calculate}{Return.calculate}} for calculating returns from prices, and be aware that the \code{\LinkA{aggregate}{aggregate}} function has methods for \code{tseries} and \code{zoo} timeseries data classes to rationally coerce irregular data into regular data of the correct periodicity.
\end{Section}
\begin{Section}{Performance Analysis}
Performance measurement is the first step down a longer road.  When discussing performance at an abstract level, terms such as \dQuote{return} and \dQuote{risk} are deliberately vague because they help to disguise some (usually unnecessary) complexity.  Scratch the surface to answer more complicated questions, and that complexity is necessarily uncovered again.  Indeed, the literature around the subject of performance analysis seems to have exploded with the popularity of alternative assets such as hedge funds, managed futures, commodities, and structured products. Simpler tools that seemed appropriate in a relative investment world seem inappropriate for an absolute return world.  Risk measurement, which is nearly inseparable from performance assessment, has been on a long march to become multi-dimensional and multi-moment while trying to answer the question: \dQuote{How much could I lose?}  Portfolio construction and risk budgeting are two sides of the same coin: \dQuote{How do I maximize my expected gain and avoid going broke?}  But before we can approach those questions we first have to ask: \dQuote{Is this something I might want in my portfolio?}

With the the increasing availability of complicated alternative investment strategies to both retail and institutional investors, and the broad availability of financial data, an engaging debate about performance analysis and evaluation is as important as ever.  There won't be one \emph{right} answer delivered in these metrics and charts.  What there will be is an accretion of evidence, organized to \emph{assist} a decision maker in answering a specific question that is pertinent to the decision at hand.  Using such tools to uncover information and ask better questions will, in turn, create a more informed investor.

Performance measurement starts with returns.  Traders may object, complaining that \dQuote{You can't eat returns,} and will prefer to look for numbers with currency signs.  To some extent, they have a point - the normalization inherent in calculating returns can be deceiving.  Most of the recent work in performance analysis, however, is focused on returns rather than prices and sometimes called "returns-based analysis" or RBA.  This \dQuote{price per unit of investment} standardization is important for two reasons - first, it helps the decision maker to compare opportunities, and second, it has some useful statistical qualities.  As a result, the \kbd{PerformanceAnalytics} library focuses on returns.  See \code{\LinkA{Return.calculate}{Return.calculate}} for converting net asset values or prices into returns, either discrete or continuous.  Many papers and theories refer to \dQuote{excess returns}: we implement a simple function for aligning time series and calculating excess returns in \code{\LinkA{Return.excess}{Return.excess}}.

We provide two functions to calculate weighted returns for a portfolio of assets.  If you have a single weighting vector, or want the equal weighted portfolio, use \code{Return.portfolio}.  If you have a portfolio that is periodically rebalanced, and multiple time periods with different weights, use \code{Return.rebalancing}.  Both functions will subset the return series to only include returns for assets for which \code{weight} is provided.

Returns and risk may be annualized as a way to simplify comparison over longer time periods.  Although it requires a bit of estimating, such aggregation is popular because it offers a reference point for easy comparison.  Examples are in \code{\LinkA{Return.annualized}{Return.annualized}}, \code{\LinkA{sd.annualized}{sd.annualized}}, and \code{\LinkA{SharpeRatio.annualized}{SharpeRatio.annualized}}.

Basic measures of performance tend to treat returns as independent observations.  In this case, the entirety of R's base is applicable to such analysis.  Some basic statistics we have collected in \code{\LinkA{table.MonthlyReturns}{table.MonthlyReturns}} include:
\\
\Tabular{ll}{
\code{\LinkA{mean}{mean}}  &  arithmetic mean \\
\code{\LinkA{mean.geometric}{mean.geometric}} & geometric mean \\
\code{\LinkA{mean.stderr}{mean.stderr}} & standard error of the mean (S.E. mean) \\
\code{\LinkA{mean.LCL}{mean.LCL}} & lower confidence level (LCL) of the mean \\
\code{\LinkA{mean.UCL}{mean.UCL}} & upper confidence level (UCL) of the mean \\
\code{\LinkA{quantile}{quantile}}  & for calculating various quantiles of the distribution \\
\code{\LinkA{min}{min}}  & minimum return \\
\code{\LinkA{max}{max}}  & maximum return \\
\code{\LinkA{range}{range}} & range of returns \\
\code{length(R)}  & number of observations \\
\code{sum(is.na(R))} & number of NA's \\
}

It is often valuable when evaluating an investment to know whether the instrument that you are examining follows a normal distribution.  One of the first methods to determine how close the asset is to a normal or log-normal distribution is to visually look at your data.  Both \code{\LinkA{chart.QQPlot}{chart.QQPlot}} and \code{\LinkA{chart.Histogram}{chart.Histogram}} will quickly give you a feel for whether or not you are looking at a normally distributed return history.  Differences between \code{\LinkA{var}{var}} and \code{\LinkA{SemiVariance}{SemiVariance}} will help you identify \code{\LinkA{skewness}{skewness}} in the returns.  Skewness measures the degree of asymmetry in the return distribution.  Positive Skewness indicates that more of the returns are positive, negative skewness indicates that more of the returns are negative.  An investor should in most cases prefer a positively skewed asset to a similar (style, industry, region) asset that has a negative skewness. 

Kurtosis measures the concentration of the returns in any given part of the distribution (as you should see visually in a histogram).  The \code{\LinkA{kurtosis}{kurtosis}} function will by default return what is referred to as \dQuote{excess kurtosis}, where 0 is a normal distribution, other methods of calculating kurtosis than \code{method="excess"} will set the normal distribution at a value of 3.  In general a rational investor should prefer an asset with a low to negative excess kurtosis, as this will indicate more predictable returns (the major exception is generally a combination of high positive skewness and high excess kurtosis).  If you find yourself needing to analyze the distribution of complex or non-smooth asset distributions, the \code{nortest} package has several advanced statistical tests for analyzing the normality of a distribution.

\emph{Modern Portfolio Theory (MPT)} is the collection of tools and techniques by which a risk-averse investor may construct an \dQuote{optimal} portfolio.  It was pioneered by Markowitz's ground-breaking 1952 paper \Cite{Portfolio Selection}.  It also encompasses CAPM, below, the efficient market hypothesis, and all forms of quantitative portfolio construction and optimization.

\emph{The Capital Asset Pricing Model (CAPM)}, initially developed by William Sharpe in 1964, provides a justification for passive or index investing by positing that assets that are not on the efficient frontier will either rise or fall in price until they are. The \code{\LinkA{CAPM.RiskPremium}{CAPM.RiskPremium}} is the measure of how much the asset's performance differs from the risk free rate.  Negative Risk Premium generally indicates that the investment is a bad investment, and the money should be allocated to the risk free asset or to a different asset with a higher risk premium.  \code{\LinkA{CAPM.alpha}{CAPM.alpha}} is the degree to which the assets returns are not due to the return that could be captured from the market. Conversely, \code{\LinkA{CAPM.beta}{CAPM.beta}} describes the portions of the returns of the asset that could be directly attributed to the returns of a passive investment in the benchmark asset. 

The Capital Market Line \code{\LinkA{CAPM.CML}{CAPM.CML}} relates the excess expected return on an efficient market portfolio to its risk (represented in CAPM by \code{\LinkA{sd}{sd}}).  The slope of the CML, \code{\LinkA{CAPM.CML.slope}{CAPM.CML.slope}}, is the Sharpe Ratio for the market portfolio. The Security Market Line is constructed by calculating the line of \code{\LinkA{CAPM.RiskPremium}{CAPM.RiskPremium}} over \code{\LinkA{CAPM.beta}{CAPM.beta}}.  For the benchmark asset this will be 1 over the risk premium of the benchmark asset. The slope of the SML, primarily for plotting purposes, is given by \code{\LinkA{CAPM.SML.slope}{CAPM.SML.slope}}. CAPM is a market equilibrium model or a general equilibrium theory of the relation of prices to risk, but it is usually applied to partial equilibrium portfolios, which can create (sometimes serious) problems in valuation.

One extension to the CAPM contemplates evaluating an active manager's ability to time the market.  Two other functions apply the same notion of best fit to positive and negative market returns, separately.  The \code{CAPM.beta.bull} is a regression for only positive market returns, which can be used to understand the behavior of the asset or portfolio in positive or 'bull' markets.  Alternatively, \code{CAPM.beta.bear} provides the calculation on negative market returns. The \code{TimingRatio} uses the ratio of those to help assess whether the manager has shown evidence that of timing skill.

The performance premium provided by an investment over a passive strategy (the benchmark) is provided by \code{\LinkA{ActivePremium}{ActivePremium}}, which is the investment's annualized return minus the benchmark's annualized return. A closely related measure is the \code{\LinkA{TrackingError}{TrackingError}}, which  measures the unexplained portion of the investment's performance relative to a benchmark. The \code{\LinkA{InformationRatio}{InformationRatio}} of an Investment in a MPT or CAPM framework is the Active Premium divided by the Tracking Error.  Information Ratio may be used to rank investments in a relative fashion.

We have also included a function to compute the \code{\LinkA{KellyRatio}{KellyRatio}}.  The Kelly criterion, properly applied, will maximize log-utility of returns and avoid risk of ruin.  Utilizing the Kelly Criterion to determine leverage or investment size on a strategy is guaranteed to avoid risk of ruin and eventually (over a long enough time horizon) create wealth, but it may be incredibly volatile, with a N\% chance of being down N\% at some point in time. Even when an investor or analyst does not intend to utilize the Kelly criterion as part of the investment sizing strategy, it can be used as a stack-ranking method like \code{\LinkA{InformationRatio}{InformationRatio}} to describe the \dQuote{edge} an investment would have over a random strategy or distribution.

\code{\LinkA{InformationRatio}{InformationRatio}}, \code{\LinkA{KellyRatio}{KellyRatio}}, \code{\LinkA{SharpeRatio}{SharpeRatio}}, \code{\LinkA{SortinoRatio}{SortinoRatio}}, \code{\LinkA{UpsidePotentialRatio}{UpsidePotentialRatio}}, Spearman Rank Correlation provided by \code{\LinkA{rcorr}{rcorr}} and other methods discussed here are all methods of rank-ordering relative performance. \Cite{Alexander and Dimitriu(2004) in \dQuote{The Art of Investing in Hedge Funds}} show that relative rankings across multiple pricing methodologies may be positively correlated with each other and with expected returns.  This is quite an important finding because it shows that multiple methods of predicting returns and risk which have underlying measures and factors that are not directly correlated to another measure or factor will still produce widely similar quantile rankings, so that the \dQuote{buckets} of target instruments will have significant overlap.  This observation specifically supports the point made early in this document regarding \dQuote{accretion of the evidence} for a positive or negative investment decision.
\end{Section}
\begin{Section}{Style Analysis}
Style analysis of fund managers is another aspect of performance attribution. We have added a four functions to \kbd{PerformanceAnalytics} which begin to address the need for doing style analysis of fund managers or other fund-like products or indexes:

\Tabular{rl}{
\code{\LinkA{chart.RollingStyle}{chart.RollingStyle}} & display style weightings over rolling periods calculated by \code{\LinkA{style.fit}{style.fit}} \\
\code{\LinkA{chart.Style}{chart.Style}} & display style weightings calculated by \code{\LinkA{style.fit}{style.fit}} \\
\code{\LinkA{style.fit}{style.fit}} & calculate and display effective style weights  \\
\code{\LinkA{style.QPfit}{style.QPfit}} & calculate and display effective style weights using quadratic programming \\
}

These functions calculate style weights using an asset class style model as described in detail in Sharpe (1992).  The use of quadratic programming to determine a fund's exposures to the changes in returns of major asset classes is usually refered to as "style analysis".

The following functions calculate effective style weights and display the results in a bar chart.  'chart.Style' calculates and displays style weights calculated over a single period. 'chart.RollingStyle' calculates and displays those weights in rolling windows through time.  'style.fit' manages the calculation of the weights by method.  'style.QPfit' calculates the specific constraint case that requires quadratic programming.

There is a significant amount of academic literature on identifying and attributing sources of risk or returns.  Much of it falls into the field of \dQuote{factor analysis} where \dQuote{risk factors} are used to retrospectively explain sources of risk, and through regression and other analytical methods \emph{predict} future period returns and risk based on factor drivers.  These are well covered in chapters on factor analysis in \Cite{Zivot and Wang(2006)} and also in the \R{} functions \code{\LinkA{factanal}{factanal}} for basic factor analysis and \code{\LinkA{princomp}{princomp}} for Principal Component Analysis.  The authors feel that financial engineers and analysts would benefit from some wrapping of this functionality focused on finance, but the capabilities already available from the base functions are quite powerful.
\end{Section}
\begin{Section}{Risk Analysis}
Many methods have been proposed to measure, monitor, and control the risks of a diversified portfolio. Perhaps a few definitions are in order on how different risks are generally classified. \emph{Market Risk} is the risk to the portfolio from a decline in the market price of instruments in the portfolio.  \emph{Liquidity Risk} is the risk that the holder of an instrument will find that a position is illiquid, and will incur extra costs in unwinding the position resulting in a less favorable price for the instrument. In  extreme cases of liquidity risk, the seller may be unable to find a buyer for the instrument at all, making the value unknowable or zero.  \emph{Credit Risk} encompasses \emph{Default Risk}, or the risk that promised payments on a loan or bond will not be made, or that a convertible instrument will not be converted in a timely manner or at all.  There are also \emph{Counterparty Risks} over the counter markets, such as those for complex derivatives.  Tools have evolved to measure all these different components of risk.  Processes must be put into place inside a firm to monitor the changing risks in a portfolio, and to control the magnitude of risks.  For an extensive treatment of these topics, see Litterman, Gumerlock, et. al.(1998).

The simplest risk measure in common use is volatility, usually modeled quantitatively with a univariate standard deviation on a portfolio.  See \code{\LinkA{sd}{sd}} .  Volatility or Standard Deviation is an appropriate risk measure when the distribution of returns is normal or resembles a random walk, and may be annualized using \code{\LinkA{sd.annualized}{sd.annualized}}, or the equivalent function \code{\LinkA{sd.multiperiod}{sd.multiperiod}} for scaling to an arbitrary number of periods.  Many assets, including hedge funds, commodities, options, and even most common stocks over a sufficiently long period, do not follow a normal distribution.  For such common but non-normally distributed assets, a more sophisticated approach than standard deviation/volatility is required to adequately model the risk.

Markowitz, in his Nobel acceptance speech and in several papers, proposed that \code{\LinkA{SemiVariance}{SemiVariance}} would be a better measure of risk than variance.  See \Cite{Zin, Markowitz, Zhao(2006)} \url{http://papers.ssrn.com/sol3/papers.cfm?abstract_id=910640}.  This measure is also called \code{\LinkA{SemiDeviation}{SemiDeviation}}.  The more general case of downside deviation is implemented in the function \code{\LinkA{DownsideDeviation}{DownsideDeviation}}, as proposed by \Cite{Sortino and Price(1994)}, where the minimum acceptable return (MAR) is a parameter to the function.  It is interesting to note that variance and mean return can produce a smoothly elliptical efficient frontier for portfolio optimization utilizing \code{\LinkA{solve.QP}{solve.QP}} or \code{\LinkA{portfolio.optim}{portfolio.optim}} or \code{\LinkA{MarkowitzPortfolio}{MarkowitzPortfolio}}. Use of semivariance or many other risk measures will not necessarily create a smooth ellipse, causing significant additional difficulties for the portfolio manager trying to build an optimal portfolio.  We'll leave a more complete treatment and implementation of portfolio optimization techniques for another time.

Another very widely used downside risk measures is analysis of drawdowns, or loss from peak value achieved. The simplest method is to check the \code{\LinkA{maxDrawdown}{maxDrawdown}}, as this will tell you the worst cumulative loss ever sustained by the asset.  If you want to look at all the drawdowns, you can \code{\LinkA{findDrawdowns}{findDrawdowns}} and \code{\LinkA{sortDrawdowns}{sortDrawdowns}} in order from worst/major to smallest/minor. The \code{\LinkA{UpDownRatios}{UpDownRatios}} function will give you some insight into the impacts of the skewness and kurtosis of the returns, and letting you know how length and magnitude of up or down moves compare to each other.  You can also plot drawdowns with \code{\LinkA{chart.Drawdown}{chart.Drawdown}}.

One of the most commonly used and cited measures of the risk/reward tradeoff of an investment or portfolio is the \code{\LinkA{SharpeRatio}{SharpeRatio}}, which measures return over standard deviation.  If you are comparing multiple assets using Sharpe, you should use \code{\LinkA{SharpeRatio.annualized}{SharpeRatio.annualized}}. It is important to note that William Sharpe now recommends \code{\LinkA{InformationRatio}{InformationRatio}} preferentially to the original Sharpe Ratio. The \code{\LinkA{SortinoRatio}{SortinoRatio}} utilizes mean return over \code{\LinkA{DownsideDeviation}{DownsideDeviation}} below the MAR as the risk measure to produce a similar ratio that is more sensitive to downside risk. Sortino later enhanced his ideas to utilize upside returns for the numerator and \code{\LinkA{DownsideDeviation}{DownsideDeviation}} as the denominator in \code{\LinkA{UpsidePotentialRatio}{UpsidePotentialRatio}}. \Cite{Favre and Galeano(2002)} propose utilizing the ratio of expected excess return over the Cornish-Fisher \code{\LinkA{VaR}{VaR}} to produce \code{\LinkA{SharpeRatio.modified}{SharpeRatio.modified}}. \code{\LinkA{TreynorRatio}{TreynorRatio}} is also similar to the Sharpe Ratio, except it uses \code{\LinkA{CAPM.beta}{CAPM.beta}} in place of the volatility measure to produce the ratio of the investment's excess return over the beta.

One of the newer statistical methods developed for analyzing the risk of financial instruments is \code{\LinkA{Omega}{Omega}}.  Omega analytically constructs a cumulative distribution function, in a manner similar to \code{\LinkA{chart.QQPlot}{chart.QQPlot}}, but then extracts additional information from the location and slope of the derived function at the point indicated by the risk quantile that the researcher is interested in.  Omega seeks to combine a large amount of data about the shape, magnitude, and slope of the distribution into one method.  The academic literature is still exploring the best manner to utilize Omega in a risk measurement and control process, or in portfolio construction.

Any risk measure should be viewed with suspicion if there are not a large number of historical observations of returns for the asset in question available.  Depending on the measure, how many observations are required will vary greatly from a statistical standpoint.  As a heuristic rule, ideally you will have data available on how the instrument performed through several economic cycles and shocks.  When such a long history is not available, the investor or researcher has several options.  A full discussion of the various approaches is beyond the scope of this introduction, so we will merely touch on several areas that an interested party may wish to explore in additional detail. Examining the returns of assets with a similar style, industry, or asset class to which the asset in question is highly correlated and shares other characteristics can be quite informative.  Factor analysis may be utilized to uncover specific risk factors where transparency is not available. Various resampling (see \code{\LinkA{tsbootstrap}{tsbootstrap}}) and simulation methods are available in \R{} to construct an artificially long distribution for testing.  If you use a method such as Monte Carlo simulation or the bootstrap, it is often valuable to use \code{\LinkA{chart.Boxplot}{chart.Boxplot}} to visualize the different estimates of the risk measure produced by the simulation, to see how small (or wide) a range the estimates cover, and thus gain a level of confidence with the results.  Proceed with extreme caution when your historical data is lacking.  Problems with lack of historical data are a major reason why many institutional investors will not invest in an alternative asset without several years of historical return data available.
\end{Section}
\begin{Section}{Value at Risk - VaR}
\emph{Traditional mean-VaR}:
In the early 90's, academic literature started referring to \dQuote{value at risk}, typically written as VaR. Take care to capitalize VaR in the commonly accepted manner, to avoid confusion with var (variance) and VAR (vector auto-regression).  With a sufficiently large data set, you may choose to utilize a non-parametric VaR estimation method using the historical distribution and the probability quantile of the distribution calculated using \code{\LinkA{qnorm}{qnorm}}. The negative return at the correct quantile (usually 95\% or 99\%), is the non-parametric VaR estimate.  J.P. Morgan's RiskMetrics parametric mean-VaR was published in 1994 and this methodology for estimating parametric mean-VaR has become what people are generally referring to as \dQuote{VaR} and what we have implemented as \code{\LinkA{VaR}{VaR}}.  See \Cite{Return to RiskMetrics: Evolution of a Standard}\url{http://www.riskmetrics.com/r2rovv.html}, Parametric traditional VaR does a better job of accounting for the tails of the distribution by more precisely estimating the tails below the risk quantile.  It is still insufficient if the assets have a distribution that varies widely from normality.

The \R{} package \code{VaR} contains methods for simulating and estimating lognormal \code{\LinkA{VaR.norm}{VaR.norm}} and generalized Pareto \code{\LinkA{VaR.gpd}{VaR.gpd}} distributions to overcome some of the problems with nonparametric or parametric mean-VaR calculations on a limited sample size.  There is also a \code{\LinkA{VaR.backtest}{VaR.backtest}} function to apply simulation methods to create a more robust estimate of the potential distribution of losses.  The VaR package also provides plots for its functions.

\emph{Modified Cornish-Fisher VaR}:
The limitations of traditional mean-VaR are all related to the use of a symmetrical distribution function.  Use of simulations, resampling, or Pareto distributions all help in making a more accurate prediction, but they are still flawed for assets with significantly non-normal (skewed and/or kurtotic) distributions. \Cite{Huisman(1999)} and \Cite{Favre and Galleano(2002)} propose to overcome this extensively documented failing of traditional VaR by directly incorporating the higher moments of the return distribution into the VaR calculation.  This new VaR measure incorporates skewness and kurtosis via an analytical estimation using a Cornish-Fisher (special case of a Taylor) expansion. The resulting measure is referred to variously as \dQuote{Cornish-Fisher VaR} or \dQuote{Modified VaR}.  We provide this measure in function \code{\LinkA{VaR}{VaR}}.  Modified VaR produces the same results as traditional mean-VaR when the return distribution is normal, so it may be used as a direct replacement.  Many papers in the finance literature have reached the conclusion that Modified VaR is a superior measure, and may be substituted in any case where mean-VaR would previously have been utilized.  

The \code{\LinkA{VaR}{VaR}} function provides traditional historical, Gaussian and modified Cornish-Fisher measures of VaR by using \code{method="historical"}, \code{method="gaussian"} or \code{method="modified"}.

\emph{Conditional VaR and Expected Shortfall}:
We have implemented Conditional Value at Risk, also called Expected Shortfall (not to be confused with shortfall probability, which is much less useful), in function \code{\LinkA{ES}{ES}}.  Expected Shortfall attempts to measure the magnitude of the average loss exceeding the traditional mean-VaR. Expected Shortfall has proven to be a reasonable risk predictor for many asset classes.  We have provided traditional historical, Gaussian and modified Cornish-Fisher measures of Expected Shortfall by using \code{method="historical"}, \code{method="gaussian"} or \code{method="modified"}. See \Cite{Uryasev(2000)} and \Cite{Sherer and Martin(2005)} for more information on Conditional Value at Risk and Expected Shortfall.  Please note that your milage will vary; expect that values obtained from the normal distribution may differ radically from the real situation, depending on the assets under analysis.

\emph{Multivariate extensions to risk measures}:
We have extened all moments calculations to woork in a multivariate portfolio context.  In a portfolio context the multivariate moments are generally to be preferred to their univariate counterparts, so that all information is available to subsequent calculations.  Both the \code{\LinkA{VaR}{VaR}} and \code{\LinkA{ES}{ES}} functions allow calculation of metrics in a portfolio context is \code{weights} and a \code{portfolio\_method} are passed into the function call.

\emph{Marginal, Incremental, and Component VaR}:
Marginal VaR is the difference between the VaR of the portfolio without the asset in question and the entire portfolio.  The \code{\LinkA{VaR}{VaR}} function calculates Marginal VaR for all instruments in the portfolio if you set \code{method="marginal"}. Marginal VaR as provided here may use traditional mean-VaR or Modified VaR for the calculation. Per \Cite{Artzner,et.al.(1997)} properties of a coherent risk measure include subadditivity (risks of the portfolio should not exceed the sum of the risks of individual components) as a significantly desirable trait.  VaR measures, including Marginal VaR, on individual components of a portfolio are \emph{not} subadditive. Clearly, a general subbadditive risk measure for downside risk is required.  Incremental or Component VaR attempt to provide just such a measure.  In Incremental or Component VaR, the Component VaR value for each element of the portfolio will sum to the total VaR of the portfolio.  Several EDHEC papers suggest utilizing Modified VaR instead of mean-VaR in the Incremental and Component VaR calculation.  We have succeeded in implementing Component VaR and ES calculations that utilize Modified Cornish-Fisher VaR, historical decomposition, and kernel estimators.  You may access these with \code{\LinkA{VaR}{VaR}} or \code{\LinkA{ES}{ES}} by setting the appropriate \code{portfolio\_method} and \code{method} arguments.


\code{\LinkA{chart.VaRSensitivity}{chart.VaRSensitivity}} Creates a chart of Value-at-Risk or Expected Shortfall estimates by confidence interval for multiple methods. Useful for comparing a calculated VaR or ES method to the historical VaR or ES, it may also be used to visually examine whether the VaR method \dQuote{breaks down} or gives nonsense results at a certain threshold.

Which VaR measure to use will depend greatly on the portfolio and instruments being analyzed.  If there is any generalization to be made on VaR measures, this author will agree with \Cite{Bali and Gokcan(2004)} who conclude that \dQuote{the VaR estimations based on the generalized Pareto distribution and the Cornish-Fisher approximation perform best}.
\end{Section}
\begin{Section}{Moments and Co-moments}
Analysis of financial time series often involves evaluating their mathematical moments.  While \code{\LinkA{var}{var}} and \code{\LinkA{cov}{cov}} for variance has always been available, and \code{\LinkA{fBasics}{fBasics}} in Rmetrics provided functions for skewness and kurtosis (which we have extended to make multivariate and multi-column aware), a larger suite of multivariate moments calculations was not available in \R{} .    We have now implemented multivariate moments and co-moments and their beta or systematic comoments in \kbd{PerformanceAnalytics}.

Ranaldo and Favre (2005) define coskewness and cokurtosis as the skewness and kurtosis of a given asset analysed with the skewness and kurtosis of the reference asset or portfolio.  The co-moments are useful for measuring the marginal contribution of each asset to the portfolio's resulting risk.  As such, comoments of an asset return distribution should be useful as inputs for portfolio optimization in addition to the covariance matrix.  Functions include \code{\LinkA{CoVariance}{CoVariance}}, \code{\LinkA{CoSkewness}{CoSkewness}}, \code{\LinkA{CoKurtosis}{CoKurtosis}}.

Measuring the co-moments should be useful for evaluating whether or not an asset is likely to provide diversification potential to a portfolio.  But the co-moments do not allow the marginal impact of an asset on a portfolio to be directly measured.  Instead, Martellini and Zieman (2007) develop a framework that assesses the potential diversification of an asset relative to a portfolio. They use higher moment betas to estimate how much portfolio risk will be impacted by adding an asset.  

Higher moment betas are defined as proportional to the derivative of the covariance, coskewness and cokurtosis of the second, third and fourth portfolio moment with respect to the portfolio weights.  A beta that is less than 1 indicates that adding the new asset should reduce the resulting portfolio's volatility and kurtosis, and to an increase in skewness. More specifically, the lower the beta the higher the diversification effect, not only in terms of normal risk (i.e. volatility) but also the risk of assymetry (skewness) and extreme events (kurtosis).  See the functions for \code{\LinkA{BetaCoVariance}{BetaCoVariance}}, \code{\LinkA{BetaCoSkewness}{BetaCoSkewness}}, and \code{\LinkA{BetaCoKurtosis}{BetaCoKurtosis}}.
\end{Section}
\begin{Section}{Robust Data Cleaning}
The functions \code{\LinkA{Return.clean}{Return.clean}} and \code{\LinkA{clean.boudt}{clean.boudt}} implement statistically robust data cleaning methods tuned to portfolio construction and risk analysis and prediction in financial time series while trying to avoid some of the pitfalls of standard robust statistical methods.

The primary value of data cleaning lies in creating a more
robust and stable estimation of the distribution generating the
large majority of the return data. The increased robustness and
stability of the estimated moments using cleaned data should be
used for portfolio construction. If an investor wishes to
have a more conservative risk estimate, cleaning may not be
indicated for risk monitoring. 

In actual practice, it is probably best to back-test the out-of-sample results of
both cleaned and uncleaned series to see what works best when forecasting risk with the
particular combination of assets under consideration.
\end{Section}
\begin{Section}{Summary Tabular Data}
Summary statistics are then the necessary aggregation and reduction of (potentially thousands) of periodic return numbers. Usually these statistics are most palatable when organized into a table of related statistics, assembled for a particular purpose.  A common offering of past returns organized by month and cumulated by calendar year is usually presented as a table, such as in \code{\LinkA{table.CalendarReturns}{table.CalendarReturns}}.  Adding benchmarks or peers alongside the annualized data is helpful for comparing returns in calendar years.

When we started this project, we debated whether such tables would be broadly useful or not.  No reader is likely to think that we captured the precise statistics to help their decision. We merely offer these as a starting point for creating your own.  Add, subtract, do whatever seems useful to you.  If you think that your work may be useful to others, please consider sharing it so that we may include it in a future version of this package.

Other tables for comparison of related groupings of statistics discussed elsewhere:
\Tabular{rl}{

\code{\LinkA{table.Stats}{table.Stats}} & Basic statistics and stylized facts \\
\code{\LinkA{table.TrailingPeriods}{table.TrailingPeriods}} & Statistics and stylized facts compared over different trailing periods \\
\code{\LinkA{table.AnnualizedReturns}{table.AnnualizedReturns}} & Annualized return, standard deviation, and Sharpe ratio \\
\code{\LinkA{table.CalendarReturns}{table.CalendarReturns}} & Monthly and calendar year return table \\
\code{\LinkA{table.CAPM}{table.CAPM}} & CAPM-related measures \\
\code{\LinkA{table.Correlation}{table.Correlation}} & Comparison of correlalations and significance statistics \\
\code{\LinkA{table.DownsideRisk}{table.DownsideRisk}} & Downside risk metrics and statistics \\
\code{\LinkA{table.Drawdowns}{table.Drawdowns}} & Ordered list of drawdowns and when they occurred \\
\code{\LinkA{table.Autocorrelation}{table.Autocorrelation}} & The first six autocorrelation coefficients and significance \\
\code{\LinkA{table.HigherMoments}{table.HigherMoments}} & Higher comoments and beta comoments \\
\code{\LinkA{table.Arbitrary}{table.Arbitrary}} & Combines a function list into a table \\
}
\end{Section}
\begin{Section}{Charts and Graphs}
Graphs and charts can also help to organize the information visually. Our goal in creating these charts was to simplify the process of creating well-formatted charts that are used often in portfolio analysis, and to create print-quality graphics that may be used in documents for consumption by non-analysts or researchers. \R's graphics capabilities are substantial, but the simplicity of the output of \R{} default graphics functions such as \code{\LinkA{plot}{plot}} does not always compare well against graphics delivered with commercial asset or portfolio analysis from places such as MorningStar or PerTrac.

The cumulative returns or wealth index is usually the first thing displayed, even though neither conveys much information.  See \code{\LinkA{chart.CumReturns}{chart.CumReturns}}.  Individual period returns may be helpful for identifying problematic periods, such as in \code{\LinkA{chart.Bar}{chart.Bar}}.  Risk measures can be helpful when overlaid on the period returns, to display the bounds at which losses may be expected.  See \code{\LinkA{chart.BarVaR}{chart.BarVaR}} and the following section on Risk Analysis.  More information can be conveyed when such charts are displayed together, as in \code{\LinkA{charts.PerformanceSummary}{charts.PerformanceSummary}}, which combines the performance data with detail on downside risk (see \code{\LinkA{chart.Drawdown}{chart.Drawdown}}).

Two-dimensional charts can also be useful while remaining easy to understand.  \code{\LinkA{chart.Scatter}{chart.Scatter}} is a utility scatter chart with some additional attributes that are used in \code{\LinkA{chart.RiskReturnScatter}{chart.RiskReturnScatter}}.  Overlaying Sharpe ratio lines or boxplots helps to add information about relative performance along those dimensions. The relative performance through time of two assets can be plotted with \code{\LinkA{chart.RelativePerformance}{chart.RelativePerformance}}.  This plot displays the ratio of the cumulative performance at each point in time and makes periods of under- or out-performance easy to see.  The value of the chart is less important than the slope of the line.  If the slope is positive, the first asset is outperforming the second, and vice verse.  Affectionately known as the Canto chart, it was used effectively in Canto (2006).

For distributional analysis, a few graphics may be useful.  \code{\LinkA{chart.Boxplot}{chart.Boxplot}} is an example of a graphic that is difficult to create in Excel and is under-utilized as a result.  A boxplot of returns is, however, a very useful way to instantly observe the shape of large collections of asset returns in a manner that makes them easy to compare to one another.  \code{\LinkA{chart.Histogram}{chart.Histogram}} and \code{\LinkA{chart.QQPlot}{chart.QQPlot}} are two charts originally ported from Rmetrics and now substantially expanded in PerformanceAnalytics.

Rolling performance is typically used as a way to assess stability of a return stream.  Although perhaps it doesn't get much credence in the financial literature as it derives from work in digital signal processing, many practitioners find it a useful way to examine and segment performance and risk periods.  See \code{\LinkA{chart.RollingPerformance}{chart.RollingPerformance}}, which is a way to display different metrics over rolling time periods.  \code{\LinkA{chart.RollingMean}{chart.RollingMean}} is a specific example of a rolling mean and one standard deviation bands.  A group of related metrics is offered in \code{\LinkA{charts.RollingPerformance}{charts.RollingPerformance}}.  These charts use utility functions such as \code{\LinkA{rollapply}{rollapply}}, \code{\LinkA{aggregate}{aggregate}}, and \code{\LinkA{apply.rolling}{apply.rolling}}.

\code{\LinkA{chart.SnailTrail}{chart.SnailTrail}} is a scatter chart that shows how rolling calculations of annualized return and annualized standard deviation have proceeded through time where the color of lines and dots on the chart diminishes with respect to time. \code{\LinkA{chart.RollingCorrelation}{chart.RollingCorrelation}} shows how correlations change over rolling periods.  \code{\LinkA{chart.RollingRegression}{chart.RollingRegression}} displays the coefficients of a linear model fitted over rolling periods.  A group of charts in \code{\LinkA{charts.RollingRegression}{charts.RollingRegression}} displays alpha, beta, and R-squared estimates in three aligned charts in a single device.

\code{\LinkA{chart.StackedBar}{chart.StackedBar}} creates a stacked column chart with time on the horizontal axis and values in categories.  This kind of chart is commonly used for showing portfolio 'weights' through time, although the function will plot any values by category. 

We have been greatly inspired by other peoples' work, some of which is on display at \url{http://addictedtor.free.fr/}.  Particular inspiration came from Dirk Eddelbuettel and John Bollinger for their work at \url{http://addictedtor.free.fr/graphiques/RGraphGallery.php?graph=65}. Those interested in price charting in \R{} should also look at the \code{quantmod} package.
\end{Section}
\begin{Section}{Wrapper and Utility Functions}
\R{} is a very powerful environment for manipulating data.  It can also be quite confusing to a user more accustomed to Excel or even MatLAB.  As such, we have written some wrapper functions that may aid you in coercing data into the correct forms or finding data that you need to use regularly.  To simplify the management of multiple-source data stored in \R{} in multiple data formats, we have provided \code{\LinkA{checkData}{checkData}}.  This function will attempt to coerce data in and out of \R's multitude of mostly fungible data classes into the class required for a particular analysis.  In general, the use of the data-coercion function has been hidden inside the business functions provided.  \code{\LinkA{checkData}{checkData}} may also save you time and trouble in your own code and functions outside of the functionality provided by the \kbd{PerformanceAnalytics} library.

When you are analyzing relative or absolute performance of investments, you need to analyze returns, but much data is available only as prices.  We have provided the simple wrapper function \code{\LinkA{CalculateReturns}{CalculateReturns}} to address this by taking a stream of prices and calculating simple or compounded returns from the price vector. The excellent \code{tseries} library includes the function \code{\LinkA{get.hist.quote}{get.hist.quote}} for retrieving market data from online sources.  Many of the functions in PerformanceAnalytics require either a benchmark or a risk free rate, and many practitioners will not have access to a formal database of historical returns. we have provided some sample historical data in the \code{managers} dataset.

\R's built-in \code{\LinkA{apply}{apply}} function in enormously powerful, but is can be tricky to use with timeseries data, so we have provided wrapper functions to \code{\LinkA{apply.fromstart}{apply.fromstart}} and \code{\LinkA{apply.rolling}{apply.rolling}} to make handling of \dQuote{from inception} and \dQuote{rolling window} calculations easier.
\end{Section}
\begin{Section}{Further Work}
We have attempted to standardize function parameters and variable names, but more work exists to be done here.

Any comments, suggestions, or code patches are invited.

If you've implemented anything that you think would be generally useful to include, please consider donating it for inclusion in a later version of this package.
\end{Section}
\begin{Section}{Acknowledgments}
Data series \code{\LinkA{edhec}{edhec}} used in \kbd{PerformanceAnalytics} and related publications with the kind permission of the EDHEC Risk and Asset Management Research Center. \\
\url{http://www.edhec-risk.com/indexes/pure_style}

Kris Boudt was instrumental in our research on component risk for portfolios with non-normal distributions, and is responsible for much of the code for multivariate moments and comoments.

Jeff Ryan, as the primary author of xts, is owed a huge debt (which he would be happy to collect over a pint) by the entire R finance community for creating xts, upon which much of PerformanceAnalytics depends.

Prototypes of the drawdowns functionality were provided by Sankalp Upadhyay, and modified with permission. Stephan Albrecht provided detailed feedback on the Getmansky/Lo Smoothing Index.  Diethelm Wuertz provided prototypes of modified VaR and skewness and kurtosis functions (and is of course the maintainer of the RMetrics suite of pricing and optimization functions)

Thanks to Joe Wayne Byers and Dirk Eddelbuettel for comments on early versions of these functions, and to Khanh Nguyen and Ryan Sheftel for careful testing and detailed problem reports.

Thanks to the R-SIG-Finance community without whom this package would not be possible.  We are indebted to the R-SIG-Finance community for many helpful suggestions, bugfixes, and requests.
\end{Section}
\begin{Author}\relax
Brian G. Peterson \\
Peter Carl \\

Maintainer: Brian G. Peterson \email{brian@braverock.com}
\end{Author}
\begin{References}\relax
Amenc, N. and Le Sourd, V. \emph{Portfolio Theory and Performance Analysis}. Wiley. 2003. \\ 
Bacon, C. \emph{Practical Portfolio Performance Measurement and Attribution}. Wiley. 2004. \\
Canto, V. \emph{Understanding Asset Allocation}. FT Prentice Hall. 2006. \\
Lhabitant, F. \emph{Hedge Funds: Quantitative Insights}. Wiley. 2004. \\
Litterman, R., Gumerlock R., et. al. \emph{The Practice of Risk Management: Implementing Processes for Managing Firm-Wide Market Risk}. Euromoney. 1998. \\
Murrel, P. \emph{R Graphics}. Chapman and Hall. 2006.  \\
Ruppert, D. \emph{Statistics and Finance, an Introduction}. Springer. 2004. \\
Scherer, B. and Martin, D. \emph{Modern Portfolio Optimization}. Springer. 2005. \\
Shumway, R. and Stoffer, D. \emph{Time Series Analysis and it's Applications, with R examples}, Springer, 2006. \\
Tsay, R. \emph{Analysis of Financial Time Series}. Wiley. 2001. \\
Zivot, E. and Wang, Z. \emph{Modeling Financial Time Series with S-Plus: second edition}. Springer. 2006. \\
\end{References}
\begin{SeeAlso}\relax
CRAN task view on Empirical Finance \\ \url{http://cran.r-project.org/src/contrib/Views/Econometrics.html}

Grant Farnsworth's Econometrics in R \\ \url{http://cran.r-project.org/doc/contrib/Farnsworth-EconometricsInR.pdf}

Collection of R charts and graphs \\ \url{http://addictedtor.free.fr/graphiques/}
\end{SeeAlso}

