Package 'PerformanceAnalytics'

Econometric tools for performance and risk analysis.

Description

PerformanceAnalytics provides an package of econometric functions for performance and risk analysis of financial instruments or portfolios. This package aims to aid practitioners and researchers in using the latest research for analysis of both normally and non-normally distributed return streams.

Details

We created this package 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 . In doing so, we also found it valuable to have wrappers for some functionality with good defaults and naming consistent with common usage in the finance literature.

In general, this package 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, either regular or irregular.

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.

In this summary, we attempt to provide an overview of the capabilities provided by PerformanceAnalytics and pointers to other literature and resources in 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.

Time Series Data

Not all, but many of the measures in this package require time series data. PerformanceAnalytics uses the xts package for managing time series data for several reasons. Besides being fast and efficient, xts includes functions that test the data for periodicity and draw attractive and readable time-based axes on charts. Another benefit is that xts provides compatability with Rmetrics' timeSeries, zoo and other time series classes, such that 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 Joshua Ulrich, the authors of xts, have been extraordinarily helpful to the development of PerformanceAnalytics and we are very grateful for their contributions to the community. The xts package extends the excellent zoo package written by Achim Zeileis and Gabor Grothendieck. zoo provides more general time series support, whereas xts provides functionality that is specifically aimed at users in finance.

Users can easily load returns data as time series for analysis with PerformanceAnalytics by using the Return.read function. The 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 read.zoo and 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 PerformanceAnalytics are calculated by column and return values for each column in the results. This is the default arrangement of time series data in xts.

Some sample data is available in the managers dataset. It is an xts object that contains columns of monthly returns for six hypothetical asset managers (HAM1 through HAM6), the EDHEC Long-Short Equity hedge fund index, the S&P 500 total returns, and total return series for the US Treasury 10-year bond and 3-month bill. Monthly returns for all series end in December 2006 and begin at different periods starting from January 1996. That data set is used extensively in our examples and should serve as a model for formatting your data.

For retrieving market data from online sources, see quantmod's getSymbols function for downloading prices and chartSeries for graphing price data. Also see the tseries package for the function get.hist.quote. Look at xts's to.period function to rationally coerce irregular price data into regular data of a specified periodicity. The aggregate function has methods for tseries and zoo timeseries data classes to rationally coerce irregular data into regular data of the correct periodicity.

Finally, see the function Return.calculate for calculating returns from prices.

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. Market Risk is the risk to the portfolio from a decline in the market price of instruments in the portfolio. 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. Credit Risk encompasses 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 Counterparty Risks in 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). For our purposes, PerformanceAnalytics tends to focus on market and liquidity risk.

The simplest risk measure in common use is volatility, usually modeled quantitatively with a univariate standard deviation on a portfolio. See 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 sd.annualized, or the equivalent function 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 SemiVariance would be a better measure of risk than variance. See Zin, Markowitz, Zhao (2006). This measure is also called SemiDeviation. The more general case is DownsideDeviation, as proposed by 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 using solve.QP or portfolio.optim or fPortfolio. 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 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 findDrawdowns and sortDrawdowns in order from worst/major to smallest/minor. The 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 chart.Drawdown.

One of the newer statistical methods developed for analyzing the risk of financial instruments is Omega. Omega analytically constructs a cumulative distribution function, in a manner similar to 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 use 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, the number of observations 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 used to uncover specific risk factors where transparency is not available. Various resampling (see 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 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.

Value at Risk (VaR) and Expected Shortfall (ES, ETL, CVaR)

Traditional mean-VaR: In the early 90's, academic literature started referring to “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 use a non-parametric VaR estimation method using the historical distribution and the probability quantile of the distribution calculated using 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 “VaR” and what we have implemented as VaR with method="historical". See Return to RiskMetrics: Evolution of a Standard at https://www.msci.com/documents/10199/dbb975aa-5dc2-4441-aa2d-ae34ab5f0945. 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. That is available in VaR with method="gaussian".

The R package VaR, now orphaned, contains methods for simulating and estimating lognormal VaR.norm and generalized Pareto 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 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. We will attempt to incorporate this orphaned functionality in PerformanceAnalytics in an upcoming release, and would welcome patches or pull requests in this direction.

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. Huisman (1999) and 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 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 “Cornish-Fisher VaR” or “Modified VaR”. We provide this measure in function VaR with method="modified". 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 used. Note that estimates for Cornish Fisher modified VaR and ES may be unstable with small sample sizes. See Martin and Arora (2017) for more details.

Conditional VaR and Expected Shortfall: We have implemented Conditional Value at Risk, also called Expected Tail Loss or Expected Shortfall (not to be confused with shortfall probability, which is much less useful), in function 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 method="historical", method="gaussian" or method="modified". See Uryasev(2000) and Sherer and Martin(2005) for more information on Conditional Value at Risk and Expected Shortfall. Please note that your mileage will vary; expect that values obtained from the normal distribution may differ radically from the real situation, depending on the assets under analysis.

Multivariate extensions to risk measures: We have extended all moments calculations to work 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 VaR and ES functions allow calculation of metrics in a portfolio context when weights and a portfolio_method are passed into the function call.

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 VaR function calculates Marginal VaR for all instruments in the portfolio if you set method="marginal". Marginal VaR as provided here may use traditional mean-VaR or Modified VaR for the calculation. Per 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 not subadditive.

Clearly, a general subadditive risk measure for downside risk is required. 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 using Modified VaR instead of mean-VaR in the Incremental and Component VaR calculation. We have succeeded in implementing Component VaR and ES calculations that use Modified Cornish-Fisher VaR, historical decomposition, and kernel estimators. You may access these with VaR or ES by setting the appropriate portfolio_method and method arguments.

The chart.VaRSensitivity function 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 “breaks down” or gives nonsense results at a certain threshold.

Which VaR or ES measure to use will depend greatly on the portfolio and instruments being analyzed. If there is any generalization to be made on VaR measures, we agree with Bali and Gokcan(2004) who conclude that “the VaR estimations based on the generalized Pareto distribution and the Cornish-Fisher approximation perform best”.

Most risk professionals are moving from using VaR to using Expected Shortfall preferentially. This preference has been endorsed by the Bank of International Settlements (BIS) and the Basel accord risk committee. In most cases, an ES measure with an appropriate probability target for your asset horizin will be more appropriate than a VaR measure.

Performance Analysis

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 may have seemed appropriate in a relative investment world seem inappropriate for an absolute return world. Risk measurement, which is nearly inseparable from performance assessment, has become multi-dimensional and multi-moment while trying to answer a simple question: “How much could I lose?” Portfolio construction and risk budgeting are two sides of the same coin: “How do I maximize my expected gain and avoid going broke?” But before we can approach those questions we first have to ask: “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 right answer delivered in these metrics and charts. What there will be is an accretion of evidence, organized to 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 “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 “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 PerformanceAnalytics package focuses on returns. See Return.calculate for converting net asset values or prices into returns, either discrete or continuous. Many papers and theories refer to “excess returns”: we implement a simple function for aligning time series and calculating excess returns in Return.excess.

Return.portfolio can be used to calculate weighted returns for a portfolio of assets. The function was recently changed to support several use-cases: a single weighting vector, an equal weighted portfolio, periodic rebalancing, or irregular rebalancing. That replaces functionality that had been split between that function and Return.rebalancing. The function will subset the return series to only include returns for assets for which weights are 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 Return.annualized, sd.annualized, and 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 table.Stats include:

mean	arithmetic mean
mean.geometric	geometric mean
mean.stderr	standard error of the mean (S.E. mean)
mean.LCL	lower confidence level (LCL) of the mean
mean.UCL	upper confidence level (UCL) of the mean
quantile	for calculating various quantiles of the distribution
min	minimum return
max	maximum return
range	range of returns
length(R)	number of observations
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 chart.QQPlot and chart.Histogram will quickly give you a feel for whether or not you are looking at a normally distributed return history. Differences between var and SemiVariance will help you identify 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 kurtosis function will by default return what is referred to as “excess kurtosis”, where 0 is a normal distribution, other methods of calculating kurtosis than 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 nortest package has several advanced statistical tests for analyzing the normality of a distribution.

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

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 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. CAPM.alpha is the degree to which the assets returns are not due to the return that could be captured from the market. Conversely, 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 CAPM.CML relates the excess expected return on an efficient market portfolio to its risk (represented in CAPM by sd). The slope of the CML, CAPM.CML.slope, is the Sharpe Ratio for the market portfolio. The Security Market Line is constructed by calculating the line of CAPM.RiskPremium over 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 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 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, CAPM.beta.bear provides the calculation on negative market returns. The TimingRatio uses the ratio of those to help assess whether the manager has shown evidence that of timing skill.

Performance/Risk Ratios:

In many cases, an analyst will be looking to find a measure or performance relative to the risk of the asset under study. PerformanceAnalytics has many functions of this type.

One of the most commonly used and cited measures of the risk/reward tradeoff of an investment or portfolio is the SharpeRatio, which measures return over standard deviation. If you are comparing multiple assets using Sharpe, you should use SharpeRatio.annualized. It is important to note that William Sharpe now recommends InformationRatio preferentially to the original Sharpe Ratio. The SortinoRatio uses mean return over 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 use upside returns for the numerator and DownsideDeviation as the denominator in UpsidePotentialRatio. Favre and Galeano(2002) propose using the ratio of expected excess return over the Cornish-Fisher VaR to produce SharpeRatio.modified. TreynorRatio is also similar to the Sharpe Ratio, except it uses CAPM.beta in place of the volatility measure to produce the ratio of the investment's excess return over the beta. Use of the downside semivariance as the denominator creates the . Use of the upside expected tail return over the ETL creates the RachevRatio. Utilizing the downside semivariance as the denominator produces the Downside Sharpe Ratio.

The performance premium provided by an investment over a passive strategy (the benchmark) is provided by ActivePremium, which is the investment's annualized return minus the benchmark's annualized return. A closely related measure is the TrackingError, which measures the unexplained portion of the investment's performance relative to a benchmark. The 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 KellyRatio. The Kelly criterion applied to position sizing will maximize log-utility of returns and avoid risk of ruin. For our purposes, it can also be used as a stack-ranking method like InformationRatio to describe the “edge” an investment would have over a random strategy or distribution.

These metrics and others such as SharpeRatio, SortinoRatio, UpsidePotentialRatio, Spearman rank correlation (see rcorr), etc., are all methods of rank-ordering relative performance. Alexander and Dimitriu (2004) in “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 “buckets” of target instruments will have significant overlap. This observation specifically supports the point made early in this document regarding “accretion of the evidence” for a positive or negative investment decision.

Standard Errors for Risk and Performance Estimators

While PerformanceAnalytics contains many functions for computing returns based risk and performance estimators, until now there has been no convenient way to accurately compute standard errors of the estimates for independent and identically distributed (i.i.d.) returns, and no way at all to do so for returns that are serially correlated. This is no longer the case due to the existence of a new frequency domain method of accurately computing standard errors when returns are serially dependent as well as when returns are independent and identically distributed. Details are provided in Xin and Martin (2019) at https://ssrn.com/abstract=3085672, and to appear in December 2020 issue of Journal of Risk. The new method makes novel use of statistical influence functions borrowed from robust statistics, combined with periodogram based regularized generalized linear polynomial model (GLM) fitting for exponential distributions. Influence function for risk and performance estimators are described in Zhang, Martin and Christidis (2020) available at SSRN https://ssrn.com/abstract=3415903. The new method has been implemented in the RPESE package available at CRAN. The RPESE package has been integrated into PerformanceAnalytics.

Standard errors can be easily computed using the PerformanceAnalytics risk estimator functions

StdDev	Sample standard deviation
SemiSD	Semi-standard deviation
lpm with argument n=1 or n=2	Lower partial moment of order 1 or 2
ES	Expected shortfall with tail probability $\alpha$
VaR	Value-at-risk with tail probability $\alpha$

and performance estimator functions

mean.arithmetic	Sample mean
SharpeRatio with argument FUN="StdDev"	Sharpe ratio
DownsideSharpeRatio or SharpeRatio with argument FUN="SemiSD"	Downside Sharpe ratio
SortinoRatio	Sortino ratio with threshold MAR
SharpeRatio with argument FUN="ES"	Mean excess return to ES ratio with tail probability $\alpha$
SharpeRatio with argument FUN="VaR"	Mean excess return to VaR ratio with tail probability $\alpha$
RachevRatio	Rachev ratio with lower upper tail probabilities $\alpha$ and $\beta$
Omega	Omega ratio with threshold $c$

where the first columns gives the names of the functions in the PerformanceAnalytics package to compute the estimate and its standard error.

Each of the PerformanceAnalytics functions listed above have an optional argument with default SE = FALSE. By changing this default to SE = TRUE, the user obtains not only risk or performance estimate, but also a standard error for the esimate. Further details concerning the computation of standard errors for the risk and performance estimators in PerformanceAnalytics can be found in the Vignette "Standard Errors for Risk and Performance Estimators in PerformanceAnalytics" available at CRAN, where a reference to the underlying theory due to Chen and Martin (2020) may be found.

Moments and Co-moments

Analysis of financial time series often involves evaluating their mathematical moments. While var and cov for variance has always been available, as well as 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 co-moments in 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, co-moments of an asset return distribution should be useful as inputs for portfolio optimization in addition to the covariance matrix. Functions include CoVariance, CoSkewness, 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 BetaCoVariance, BetaCoSkewness, and BetaCoKurtosis.

Robust Data Cleaning

The functions Return.clean and 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.

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 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:

table.Stats	Basic statistics and stylized facts
table.TrailingPeriods	Statistics and stylized facts compared over different trailing periods
table.AnnualizedReturns	Annualized return, standard deviation, and Sharpe ratio
table.CalendarReturns	Monthly and calendar year return table
table.CAPM	CAPM-related measures
table.Correlation	Comparison of correlalations and significance statistics
table.DownsideRisk	Downside risk metrics and statistics
table.Drawdowns	Ordered list of drawdowns and when they occurred
table.Autocorrelation	The first six autocorrelation coefficients and significance
table.HigherMoments	Higher co-moments and beta co-moments
table.Arbitrary	Combines a function list into a table

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 performance analysis, and to create high-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 plot does not always compare well against graphics delivered with commercial asset or performance 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 chart.CumReturns. Individual period returns may be helpful for identifying problematic periods, such as in chart.Bar. Risk measures can be helpful when overlaid on the period returns, to display the bounds at which losses may be expected. See chart.BarVaR and the prior section on Risk Analysis. More information can be conveyed when such charts are displayed together, as in charts.PerformanceSummary, which combines the performance data with detail on downside risk (see chart.Drawdown).

chart.RelativePerformance can plot the relative performance through time of two assets. 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).

Two-dimensional charts can also be useful while remaining easy to understand. chart.Scatter is a utility scatter chart with some additional attributes that are used in chart.RiskReturnScatter. Overlaying Sharpe ratio lines or boxplots helps to add information about relative performance along those dimensions.

For distributional analysis, a few graphics may be useful. 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. chart.Histogram and chart.QQPlot are two charts originally found elsewhere 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 chart.RollingPerformance, which is a way to display different metrics over rolling time periods. chart.RollingMean is a specific example of a rolling mean and standard error bands. A group of related metrics is offered in charts.RollingPerformance. These charts use utility functions such as rollapply.

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. chart.RollingCorrelation shows how correlations change over rolling periods. chart.RollingRegression displays the coefficients of a linear model fitted over rolling periods. A group of charts in charts.RollingRegression displays alpha, beta, and R-squared estimates in three aligned charts in a single device.

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 addictedtor.free.fr. Particular inspiration came from Dirk Eddelbuettel and John Bollinger for their work at http://addictedtor.free.fr/graphiques/RGraphGallery.php?graph=65. Those interested in price charting in R should also look at the quantmod package.

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 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. The data-coercion function has been hidden inside the functions here, but it may also save you time and trouble in your own code and functions as well.

R's built-in apply function in enormously powerful, but is can be tricky to use with timeseries data, so we have provided wrapper functions to apply.fromstart and apply.rolling to make handling of “from inception” and “rolling window” calculations easier.

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.

Acknowledgments

Data series edhec used in PerformanceAnalytics and related publications with the kind permission of the EDHEC Risk and Asset Management Research Center.
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 co-moments. This works was later extended and made faster and more robust by Dries Cornilly

Jeff Ryan and Joshua Ulrich are active participants in the R finance community and created 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. The late Diethelm Wuertz provided prototypes of modified VaR and skewness and kurtosis functions (and was of course the maintainer of the RMetrics suite of pricing and optimization functions). Diethelm also contributed prototypes for many other functions from Bacon's book that were incorporated into PerformanceAnalytics by Matthieu Lestel.

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

Thanks also to our Google Summer of Code students through the years for their contributions. Significant contributions from GSOC students to this package have come from Dries Cornilly, Anthony-Alexander Cristidis, Zenith "Ziheng" Zhou, Matthieu Lestel and Andrii Babii so far. We expect to eventually incorporate contributions from Pulkit Mehrotra and Shubhankit Mohan, who worked with us during the summer of 2013.

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.

Any errors are, of course, our own.

References

Amenc, N. and Le Sourd, V. Portfolio Theory and Performance Analysis. Wiley. 2003.

Pfaff, B. Financial Risk Modeling and Portfolio Optimization with R, Second Edition. Wiley. 2016.

Bacon, C. Practical Portfolio Performance Measurement and Attribution. Wiley. 2004.

Canto, V. Understanding Asset Allocation. FT Prentice Hall. 2006.

Chen, X. and Martin, R. D. Standard Errors of Risk and Performance Measure Estimators for Serially Correlated Returns. SSRN eLibrary. 2019.

Lhabitant, F. Hedge Funds: Quantitative Insights. Wiley. 2004.

Litterman, R., Gumerlock R., et. al. The Practice of Risk Management: Implementing Processes for Managing Firm-Wide Market Risk. Euromoney. 1998.

Martellini, L., and Volker, Z. Improved Forecasts of Higher-Order Comoments and Implications for Portfolio Selection. EDHEC Risk and Asset Management Research Centre working paper. 2007.

Martin, R. Douglas, and Arora, Rohit. Inefficiency and bias of modified value-at-risk and expected shortfall. 2017. Journal of Risk 19(6), 59–84

Ranaldo, A., and Laurent Favre Sr. How to Price Hedge Funds: From Two- to Four-Moment CAPM. SSRN eLibrary. 2005.

Murrel, P. R Graphics. Chapman and Hall. 2006.

Ruppert, D., and Matteson, D Statistics and Data Analysis for Financial Engineering, with R Examples. Second Edition. Springer. 2015.

Scherer, B. and Martin, D. Modern Portfolio Optimization. Springer. 2005.

Shumway, R. and Stoffer, D. Time Series Analysis and it's Applications, with R examples, Springer, 2006.

Tsay, R. Analysis of Financial Time Series. Wiley. 2001.

Chen, X. and Martin, R. D. Standard Errors of Risk and Performance Measure Estimators for Serially Correlated Returns. SSRN eLibrary. 2019.

Zhang, S., Martin, R. Douglas., and Christidis, A. Influence Functions for Risk and Performance Estimators. SSRN eLibrary. 2020.

Zin, M., Zhao. A Note on Semivariance. Mathematical Finance, Vol. 16, No. 1, pp. 53-61, January 2006

Zivot, E. and Wang, Z. Modeling Financial Time Series with S-Plus: second edition. Springer. 2006.

See Also

CRAN task view on Empirical Finance
https://CRAN.R-project.org/view=Econometrics

Grant Farnsworth's Econometrics in R
https://cran.r-project.org/doc/contrib/Farnsworth-EconometricsInR.pdf

---

Wrapper for SFM's regression models.

Description

This is intended to be called using SFM.coefficients function, and not directly.

Usage

.coefficients(xRa, xRb, subset, ..., method = "LS", family = "mopt")

Arguments

xRa	an xts, vector, matrix, data frame, timeSeries or zoo object of excess asset returns
xRb	excess return vector of the benchmark asset
subset	a logical vector
...	arguments passed to other methods
method	Which linear model to use for SFM regression
family	If method is "Rob", then this is a string specifying the name of the family of loss function to be used (current valid options are "bisquare", "opt" and "mopt"). Incomplete entries will be matched to the current valid options. Defaults to "mopt".

Author(s)

Dhairya Jain

---

Active Premium or Active Return

Description

The return on an investment's annualized return minus the benchmark's annualized return.

Usage

ActiveReturn(Ra, Rb, scale = NA, ...)

Arguments

Ra	return vector of the portfolio
Rb	return vector of the benchmark asset
scale	number of periods in a year (daily scale = 252, monthly scale = 12, quarterly scale = 4)
...	any other passthru parameters to Return.annualized (e.g., geometric=FALSE)

Details

Active Premium = Investment's annualized return - Benchmark's annualized return

Also commonly referred to as 'active return'.

Author(s)

Peter Carl

References

Sharpe, W.F. The Sharpe Ratio,Journal of Portfolio Management, Fall 1994, 49-58.

See Also

InformationRatio TrackingError Return.annualized

Examples

data(managers)
    ActivePremium(managers[, "HAM1", drop=FALSE], managers[, "SP500 TR", drop=FALSE])
    ActivePremium(managers[,1,drop=FALSE], managers[,8,drop=FALSE])
    ActivePremium(managers[,1:6], managers[,8,drop=FALSE])
    ActivePremium(managers[,1:6], managers[,8:7,drop=FALSE])

---

Adjusted Sharpe ratio of the return distribution

Description

Adjusted Sharpe ratio was introduced by Pezier and White (2006) to adjusts for skewness and kurtosis by incorporating a penalty factor for negative skewness and excess kurtosis.

Usage

AdjustedSharpeRatio(R, Rf = 0, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
Rf	the risk free rate
...	any other passthru parameters

Details

$Adjusted Sharpe Ratio = SR * [1 + (\frac{S}{6}) * SR - (\frac{K - 3}{24}) * SR^2]$

where $SR$ is the sharpe ratio with data annualized, $S$ is the skewness and $K$ is the kurtosis

Author(s)

Matthieu Lestel, Brian G. Peterson

References

Carl Bacon, Practical portfolio performance measurement and attribution, second edition 2008 p.99

Pezier, Jaques and White, Anthony. 2006. The Relative Merits of Investable Hedge Fund Indices and of Funds of Hedge Funds in Optimal Passive Portfolios. http://econpapers.repec.org/paper/rdgicmadp/icma-dp2006-10.htm

See Also

SharpeRatio.annualized

Examples

data(portfolio_bacon)
print(AdjustedSharpeRatio(portfolio_bacon[,1])) #expected 0.7591435

data(managers)
print(AdjustedSharpeRatio(managers['1996']))

---

calculate a function over an expanding window always starting from the beginning of the series

Description

A function to calculate a function over an expanding window from the start of the timeseries. This wrapper allows easy calculation of “from inception” statistics.

Usage

apply.fromstart(R, FUN = "mean", gap = 1, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
FUN	any function that can be evaluated using a single set of returns (e.g., rolling beta won't work, but Return.annualized will)
gap	the number of data points from the beginning of the series required to “train” the calculation
...	any other passthru parameters

Author(s)

Peter Carl

See Also

rollapply

Examples

data(managers)
apply.fromstart(managers[,1,drop=FALSE], FUN="mean", width=36)

---

calculate a function over a rolling window

Description

Creates a results timeseries of a function applied over a rolling window.

Usage

apply.rolling(R, width, trim = TRUE, gap = 12, by = 1, FUN = "mean", ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
width	number of periods to apply rolling function window over
trim	TRUE/FALSE, whether to keep alignment caused by NA's
gap	numeric number of periods from start of series to use to train risk calculation
by	calculate FUN for trailing width points at every by-th time point.
FUN	any function that can be evaluated using a single set of returns (e.g., rolling beta won't work, but Return.annualized will)
...	any other passthru parameters

Details

Wrapper function for rollapply to hide some of the complexity of managing single-column zoo objects.

Value

A timeseries in a zoo object of the calculation results

Author(s)

Peter Carl

See Also

apply
rollapply

Examples

data(managers)
apply.rolling(managers[,1,drop=FALSE], FUN="mean", width=36)

---

Appraisal ratio of the return distribution

Description

Appraisal ratio is the Jensen's alpha adjusted for specific risk. The numerator is divided by specific risk instead of total risk.

Usage

AppraisalRatio(
  Ra,
  Rb,
  Rf = 0,
  method = c("appraisal", "modified", "alternative"),
  ...
)

Arguments

Ra	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
Rb	return vector of the benchmark asset
Rf	risk free rate, in same period as your returns
method	is one of "appraisal" to calculate appraisal ratio, "modified" to calculate modified Jensen's alpha or "alternative" to calculate alternative Jensen's alpha.
...	any other passthru parameters

Details

Modified Jensen's alpha is Jensen's alpha divided by beta.

Alternative Jensen's alpha is Jensen's alpha divided by systematic risk.

$Appraisal ratio = \frac{\alpha}{\sigma_{\epsilon}}$

$Modified Jensen's alpha = \frac{\alpha}{\beta}$

$Alternative Jensen's alpha = \frac{\alpha}{\sigma_S}$

where $alpha$ is the Jensen's alpha, $\sigma_{epsilon}$ is the specific risk, $\sigma_S$ is the systematic risk.

Author(s)

Matthieu Lestel

References

Carl Bacon, Practical portfolio performance measurement and attribution, second edition 2008 p.77

Examples

data(portfolio_bacon)
print(AppraisalRatio(portfolio_bacon[,1], portfolio_bacon[,2], method="appraisal")) #expected -0.430
print(AppraisalRatio(portfolio_bacon[,1], portfolio_bacon[,2], method="modified")) 
print(AppraisalRatio(portfolio_bacon[,1], portfolio_bacon[,2], method="alternative"))

data(managers)
print(AppraisalRatio(managers['1996',1], managers['1996',8]))
print(AppraisalRatio(managers['1996',1:5], managers['1996',8]))

---

Calculates the average depth of the observed drawdowns.

Description

ADD = abs(sum[j=1,2,...,d](D_j/d)) where D'_j = jth drawdown over entire period d = total number of drawdowns in the entire period

Usage

AverageDrawdown(R, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
...	any other passthru parameters

Author(s)

Peter Carl

---

Calculates the average length (in periods) of the observed drawdowns.

Description

Similar to AverageDrawdown, which calculates the average depth of drawdown, this function calculates the average length of the drawdowns observed.

Usage

AverageLength(R, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
...	any other passthru parameters

Author(s)

Peter Carl

---

Calculates the average length (in periods) of the observed recovery period.

Description

Similar to AverageDrawdown, which calculates the average depth of drawdown, this function calculates the average length of the recovery period of the drawdowns observed.

Usage

AverageRecovery(R, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
...	any other passthru parameters

Author(s)

Peter Carl

---

Bernardo and Ledoit ratio of the return distribution

Description

To calculate Bernardo and Ledoit ratio we take the sum of the subset of returns that are above 0 and we divide it by the opposite of the sum of the subset of returns that are below 0

Usage

BernardoLedoitRatio(R, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
...	any other passthru parameters

Details

$BernardoLedoitRatio(R) = \frac{\frac{1}{n}\sum^{n}_{t=1}{max(R_{t},0)}}{\frac{1}{n}\sum^{n}_{t=1}{max(-R_{t},0)}}$

where $n$ is the number of observations of the entire series

Author(s)

Matthieu Lestel

References

Carl Bacon, Practical portfolio performance measurement and attribution, second edition 2008 p.95

Examples

data(portfolio_bacon)
print(BernardoLedoitRatio(portfolio_bacon[,1])) #expected 1.78

data(managers)
print(BernardoLedoitRatio(managers['1996']))
print(BernardoLedoitRatio(managers['1996',1])) #expected 4.598

---

Functions to calculate systematic or beta co-moments of return series

Description

calculate higher co-moment betas, or 'systematic' variance, skewness, and kurtosis

Usage

BetaCoVariance(Ra, Rb)

BetaCoSkewness(Ra, Rb, test = FALSE)

BetaCoKurtosis(Ra, Rb)

Arguments

Ra	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
Rb	an xts, vector, matrix, data frame, timeSeries or zoo object of index, benchmark, or secondary asset returns to compare against
test	condition not implemented yet

Details

The co-moments, including covariance, coskewness, and cokurtosis, 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, in terms of symmetric risk (i.e., volatility), in asymmetry risk (i.e., skewness), and extreme risks (i.e. kurtosis). That allows them to show that adding an asset to a portfolio (or benchmark) will reduce the portfolio's variance to be reduced if the second-order beta of the asset with respect to the portfolio is less than one. They develop the same concepts for the third and fourth order moments. The authors offer these higher moment betas as a measure of the diversification potential of 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. The beta co-variance is calculated as:

$BetaCoV(Ra,Rb) = \beta^{(2)}_{a,b} = \frac{CoV(R_a,R_b)}{\mu^{(2)}(R_b)}$

Beta co-skewness is given as:

$BetaCoS(Ra,Rb) = \beta^{(3)}_{a,b}= \frac{CoS(R_a,R_b)}{\mu^{(3)}(R_b)}$

Beta co-kurtosis is:

$BetaCoK(Ra,Rb)=\beta^{(4)}_{a,b} = \frac{CoK(R_a,R_b)}{\mu^{(4)}(R_b)}$

where the $n$-th centered moment is calculated as

$\mu^{(n)}(R) = E\lbrack(R-E(R))^n\rbrack$

A beta is greater than one indicates that no diversification benefits should be expected from the introduction of that asset into the portfolio. Conversely, a beta that is less than one 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 on normal risk (i.e. volatility). Similarly, since extreme risks are generally characterised by negative skewness and positive kurtosis, the lower the beta, the higher the diversification effect on extreme risks (as reflected in Modified Value-at-Risk or ER).

The addition of a small fraction of a new asset to a portfolio leads to a decrease in the portfolio's second moment (respectively, an increase in the portfolio's third moment and a decrease in the portfolio's fourth moment) if and only if the second moment (respectively, the third moment and fourth moment) beta is less than one (see Martellini and Ziemann (2007) for more details).

For skewness, the interpretation is slightly more involved. If the skewness of the portfolio is negative, we would expect an increase in portfolio skewness when the third moment beta is lower than one. When the skewness of the portfolio is positive, then the condition is that the third moment beta is greater than, as opposed to lower than, one.

Because the interpretation of beta coskewness is made difficult by the need to condition on it's skewness, we deviate from the more widely used measure slightly. To make the interpretation consistent across all three measures, the beta coskewness function tests the skewness and multiplies the result by the sign of the skewness. That allows an analyst to review the metric and interpret it without needing additional information. To use the more widely used metric, simply set the parameter test = FALSE.

Author(s)

Kris Boudt, Peter Carl, Brian Peterson

References

Boudt, Kris, Brian G. Peterson, and Christophe Croux. 2008. Estimation and Decomposition of Downside Risk for Portfolios with Non-Normal Returns. Journal of Risk. Winter.

Martellini, Lionel, and Volker Ziemann. 2007. Improved Forecasts of Higher-Order Comoments and Implications for Portfolio Selection. EDHEC Risk and Asset Management Research Centre working paper.

See Also

CoMoments

Examples

data(managers)

BetaCoVariance(managers[, "HAM2", drop=FALSE], managers[, "SP500 TR", drop=FALSE])
BetaCoSkewness(managers[, "HAM2", drop=FALSE], managers[, "SP500 TR", drop=FALSE])
BetaCoKurtosis(managers[, "HAM2", drop=FALSE], managers[, "SP500 TR", drop=FALSE])
BetaCoKurtosis(managers[,1:6], managers[,8,drop=FALSE])
BetaCoKurtosis(managers[,1:6], managers[,8:7])

---

Burke ratio of the return distribution

Description

To calculate Burke ratio we take the difference between the portfolio return and the risk free rate and we divide it by the square root of the sum of the square of the drawdowns. To calculate the modified Burke ratio we just multiply the Burke ratio by the square root of the number of datas.

Usage

BurkeRatio(R, Rf = 0, modified = FALSE, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
Rf	the risk free rate
modified	a boolean to decide which ratio to calculate between Burke ratio and modified Burke ratio.
...	any other passthru parameters

Details

$Burke Ratio = \frac{r_P - r_F}{\sqrt{\sum^{d}_{t=1}{D_t}^2}}$

$Modified Burke Ratio = \frac{r_P - r_F}{\sqrt{\sum^{d}_{t=1}\frac{{D_t}^2}{n}}}$

where $n$ is the number of observations of the entire series, $d$ is number of drawdowns, $r_P$ is the portfolio return, $r_F$ is the risk free rate and $D_t$ the $t^{th}$ drawdown.

Author(s)

Matthieu Lestel

References

Carl Bacon, Practical portfolio performance measurement and attribution, second edition 2008 p.90-91

Examples

data(portfolio_bacon)
print(BurkeRatio(portfolio_bacon[,1])) #expected 0.74
print(BurkeRatio(portfolio_bacon[,1], modified = TRUE)) #expected 3.65

data(managers)
print(BurkeRatio(managers['1996']))
print(BurkeRatio(managers['1996',1])) 
print(BurkeRatio(managers['1996'], modified = TRUE))
print(BurkeRatio(managers['1996',1], modified = TRUE))

---

calculate a Calmar or Sterling reward/risk ratio Calmar and Sterling Ratios are yet another method of creating a risk-adjusted measure for ranking investments similar to the SharpeRatio.

Description

Both the Calmar and the Sterling ratio are the ratio of annualized return over the absolute value of the maximum drawdown of an investment. The Sterling ratio adds an excess risk measure to the maximum drawdown, traditionally and defaulting to 10%.

Usage

CalmarRatio(R, scale = NA)

SterlingRatio(R, scale = NA, excess = 0.1)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
scale	number of periods in a year (daily scale = 252, monthly scale = 12, quarterly scale = 4)
excess	for Sterling Ratio, excess amount to add to the max drawdown, traditionally and default .1 (10%)

Details

It is also traditional to use a three year return series for these calculations, although the functions included here make no effort to determine the length of your series. If you want to use a subset of your series, you'll need to truncate or subset the input data to the desired length.

Many other measures have been proposed to do similar reward to risk ranking. It is the opinion of this author that newer measures such as Sortino's UpsidePotentialRatio or Favre's modified SharpeRatio are both “better” measures, and should be preferred to the Calmar or Sterling Ratio.

Author(s)

Brian G. Peterson

References

Bacon, Carl. Practical Portfolio Performance Measurement and Attribution. Wiley. 2004.

See Also

Return.annualized,
maxDrawdown,
SharpeRatio.modified,
UpsidePotentialRatio

Examples

data(managers)
    CalmarRatio(managers[,1,drop=FALSE])
    CalmarRatio(managers[,1:6]) 
    SterlingRatio(managers[,1,drop=FALSE])
    SterlingRatio(managers[,1:6])

---

utility functions for single factor (CAPM) CML, SML, and RiskPremium

Description

The Capital Asset Pricing Model, from which the popular SharpeRatio is derived, is a theory of market equilibrium. These utility functions provide values for various measures proposed in the CAPM.

Usage

CAPM.CML.slope(Rb, Rf = 0)

CAPM.CML(Ra, Rb, Rf = 0)

CAPM.RiskPremium(Ra, Rf = 0)

CAPM.SML.slope(Rb, Rf = 0)

Arguments

Rb	return vector of the benchmark asset
Rf	risk free rate, in same period as your returns
Ra	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns

Details

At it's core, the CAPM is a single factor linear model. In light of the general ustility and wide use of single factor model, all functions in the CAPM suite will also be available with SFM (single factor model) prefixes.

The CAPM provides a justification for passive or index investing by positing that assets that are not on the efficient frontier will either rise or lower in price until they are on the efficient frontier of the market portfolio.

The CAPM Risk Premium on an investment 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.

The Capital Market Line relates the excess expected return on an efficient market portfolio to it's Risk. The slope of the CML is the Sharpe Ratio for the market portfolio. The Security Market line is constructed by calculating the line of Risk Premium over CAPM.beta. For the benchmark asset this will be 1 over the risk premium of the benchmark asset. The CML also describes the only path allowed by the CAPM to a portfolio that outperforms the efficient frontier: it describes the line of reward/risk that a leveraged portfolio will occupy. So, according to CAPM, no portfolio constructed of the same assets can lie above the CML.

Probably the most complete criticism of CAPM in actual practice (as opposed to structural or theory critiques) is that it posits a market equilibrium, but is most often used only in a partial equilibrium setting, for example by using the S\&P 500 as the benchmark asset. A better method of using and testing the CAPM would be to use a general equilibrium model that took global assets from all asset classes into consideration.

Chapter 7 of Ruppert(2004) gives an extensive overview of CAPM, its assumptions and deficiencies.

SFM.RiskPremium is the premium returned to the investor over the risk free asset

$\overline{(R_{a}-R_{f})}$

SFM.CML calculates the expected return of the asset against the benchmark Capital Market Line

SFM.CML.slope calculates the slope of the Capital Market Line for looking at how a particular asset compares to the CML

SFM.SML.slope calculates the slope of the Security Market Line for looking at how a particular asset compares to the SML created by the benchmark

Author(s)

Brian G. Peterson

References

Sharpe, W.F. The Sharpe Ratio,Journal of Portfolio Management,Fall 1994, 49-58.
Sharpe, W.F. Capital Asset Prices: A theory of market equilibrium under conditions of risk. Journal of finance, vol 19, 1964, 425-442.
Ruppert, David. Statistics and Finance, an Introduction. Springer. 2004.

See Also

CAPM.beta CAPM.alpha SharpeRatio InformationRatio TrackingError ActivePremium

Examples

data(managers)
CAPM.CML.slope(managers[,"SP500 TR",drop=FALSE], managers[,10,drop=FALSE])
CAPM.CML(managers[,"HAM1",drop=FALSE], managers[,"SP500 TR",drop=FALSE], Rf=0)
CAPM.RiskPremium(managers[,"SP500 TR",drop=FALSE], Rf=0)
CAPM.RiskPremium(managers[,"HAM1",drop=FALSE], Rf=0)
CAPM.SML.slope(managers[,"SP500 TR",drop=FALSE], Rf=0)
# should create plots like in Ruppert 7.1 7.2

---

Time-varying conditional single factor model beta

Description

CAPM is estimated assuming that betas and alphas change over time. It is assumed that the market prices of securities fully reflect readily available and public information. A matrix of market information variables, $Z$ measures this information. Possible variables in $Z$ could be the divident yield, Tresaury yield, etc. The betas of stocks and managed portfolios are allowed to change with market conditions:

Usage

CAPM.dynamic(Ra, Rb, Rf = 0, Z, lags = 1, ...)

Arguments

Ra	an xts, vector, matrix, data frame, timeSeries or zoo object of the asset returns
Rb	an xts, vector, matrix, data frame, timeSeries or zoo object of the benchmark asset return
Rf	risk free rate, in same period as your returns
Z	an xts, vector, matrix, data frame, timeSeries or zoo object of k variables that reflect public information
lags	number of lags before the current period on which the alpha and beta are conditioned
...	any other passthrough parameters

Details

$\beta_{p}(z_{t})=b_{0p}+B_{p}'z_{t}$

where $z_{t}=Z_{t}-E[Z]$

- a normalized vector of the deviations of $Z_{t}$, $B_{p}$

- a vector with the same dimension as $Z_{t}$.

The coefficient $b_{0p}$ can be interpreted as the "average beta" or the beta when all infromation variables are at their means. The elements of $B_{p}$ measure the sensitivity of the conditional beta to the deviations of the $Z_{t}$ from their means. In the similar way the time-varying conditional alpha is modeled:

$\alpha_{pt}=\alpha_{p}(z_{t})=\alpha_{0p}+A_{p}'z_{t}$

The modified regression is therefore:

$r_{pt+1}=\alpha_{0p}+A_{p}'z_{t}+b_{0p}r_{bt+1}+B_{p}'[z_{t}r_{bt+1}]+ \mu_{pt+1}$

Author(s)

Andrii Babii

References

J. Christopherson, D. Carino, W. Ferson. Portfolio Performance Measurement and Benchmarking. 2009. McGraw-Hill. Chapter 12.
Wayne E. Ferson and Rudi Schadt, "Measuring Fund Strategy and Performance in Changing Economic Conditions," Journal of Finance, vol. 51, 1996, pp.425-462

See Also

CAPM.beta

Examples

data(managers)
CAPM.dynamic(managers[,1,drop=FALSE], managers[,8,drop=FALSE], 
             Rf=.035/12, Z=managers[, 9:10])

CAPM.dynamic(managers[80:120,1:6], managers[80:120,7,drop=FALSE], 
             Rf=managers[80:120,10,drop=FALSE], Z=managers[80:120, 9:10])
             
CAPM.dynamic(managers[80:120,1:6], managers[80:120,8:7],
              managers[80:120,10,drop=FALSE], Z=managers[80:120, 9:10])

---

Regression epsilon of the return distribution

Description

The regression epsilon is an error term measuring the vertical distance between the return predicted by the equation and the real result.

Usage

CAPM.epsilon(Ra, Rb, Rf = 0, ...)

Arguments

Ra	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
Rb	return vector of the benchmark asset
Rf	risk free rate, in same period as your returns
...	any other passthru parameters

Details

$\epsilon_r = r_p - \alpha_r - \beta_r * b$

where $\alpha_r$ is the regression alpha, $\beta_r$ is the regression beta, $r_p$ is the portfolio return and b is the benchmark return

Author(s)

Matthieu Lestel

References

Carl Bacon, Practical portfolio performance measurement and attribution, second edition 2008 p.71

Examples

data(portfolio_bacon)
print(SFM.epsilon(portfolio_bacon[,1], portfolio_bacon[,2])) #expected -0.013

data(managers)
print(SFM.epsilon(managers['1996',1], managers['1996',8]))
print(SFM.epsilon(managers['1996',1:5], managers['1996',8]))

---

Jensen's alpha of the return distribution

Description

The Jensen's alpha is the intercept of the regression equation in the Capital Asset Pricing Model and is in effect the exess return adjusted for systematic risk.

Usage

CAPM.jensenAlpha(Ra, Rb, Rf = 0, ..., method = "LS", family = "mopt")

Arguments

Ra	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
Rb	return vector of the benchmark asset
Rf	risk free rate, in same period as your returns
...	any other pass thru parameters
method	(Optional): string representing linear regression model, "LS" for Least Squares and "Rob" for robust
family	(Optional): If method == "Rob": This is a string specifying the name of the family of loss function to be used (current valid options are "bisquare", "opt" and "mopt"). Incomplete entries will be matched to the current valid options. Defaults to "mopt". Else: the parameter is ignored

Details

$\alpha = r_p - r_f - \beta_p * (b - r_f)$

where $r_f$ is the risk free rate, $\beta_r$ is the regression beta, $r_p$ is the portfolio return and b is the benchmark return

Author(s)

Matthieu Lestel, Dhairya Jain

References

Carl Bacon, Practical portfolio performance measurement and attribution, second edition 2008 p.72

Examples

data(portfolio_bacon)
print(SFM.jensenAlpha(portfolio_bacon[,1], portfolio_bacon[,2])) #expected -0.014

data(managers)
print(SFM.jensenAlpha(managers['1996',1], managers['1996',8]))
print(SFM.jensenAlpha(managers['1996',1:5], managers['1996',8]))

---

Conditional Drawdown alpha

Description

The difference between the actual rate of return and the rate of return of the instrument estimated via the conditional drawdown beta is called $CDaR.alpha$ and it is the equivalent of the typical CAPM alpha but focusing on market drawdowns.

Positive $CDaR.alpha$ implies that the instrument performed better than it was predicted, and consequently, $CDaR.alpha$ can be used as a performance measure to rank instrument who overperform under market drawdowns.

Usage

CDaR.alpha(R, Rm, p = 0.95, weights = NULL, geometric = TRUE, type = NULL, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
Rm	an xts, vector, matrix, data frame, timeSeries or zoo object of benchmark returns
p	confidence level for calculation ,default(p=0.95)
weights	portfolio weighting vector, default NULL
geometric	utilize geometric chaining (TRUE) or simple/arithmetic chaining (FALSE) to aggregate returns, default TRUE
type	(Optional) Overrides the p parameter. If "average" then p = 0 and if "max" then p = 1
...	any passthru variable

Value

The annualized alpha (input data are assumed to be of monthly frequency)

Author(s)

Tasos Grivas <[email protected]>, Pulkit Mehrotra

References

Zabarankin, M., Pavlikov, K., and S. Uryasev. Capital Asset Pricing Model (CAPM) with Drawdown Measure.Research Report 2012-9, ISE Dept., University of Florida,September 2012.

See Also

CDaR CDaR.beta

Examples

data(edhec)
CDaR.alpha(edhec[,1],edhec[,2])

CDaR.alpha(edhec[,1],edhec[,2],type="max")

CDaR.alpha(edhec[,1],edhec[,2],type="average")

---

Conditional Drawdown beta

Description

The conditional drawdown beta is a measure of capturing performance under market drawdowns and it is given by the ratio of the average rate of return of the instrument over time periods corresponding to the $(1-p)T$ largest drawdowns of the benchmark portfolio.

The difference in CDaR and standard beta boils down to the fact that the standard beta accounts for the fund returns over the whole return history, including the upside while CDaR beta focuses only on market drawdowns.

Usage

CDaR.beta(R, Rm, p = 0.95, weights = NULL, geometric = TRUE, type = NULL, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
Rm	an xts, vector, matrix, data frame, timeSeries or zoo object of benchmark returns
p	confidence level for calculation ,default(p=0.95)
weights	portfolio weighting vector, default NULL, see Details
geometric	utilize geometric chaining (TRUE) or simple/arithmetic chaining (FALSE) to aggregate returns, default TRUE
type	(Optional) Overrides the p parameter. If "average" then p = 0 and if "max" then p = 1
...	any passthru variable.

Author(s)

Tasos Grivas <[email protected]>,Pulkit Mehrotra

References

Zabarankin, M., Pavlikov, K., and S. Uryasev. Capital Asset Pricing Model (CAPM) with Drawdown Measure.Research Report 2012-9, ISE Dept., University of Florida,September 2012.

See Also

CDaR.alpha CDaR

Examples

data(edhec)
CDaR.beta(edhec[,1],edhec[,2]) 
CDaR.beta(edhec[,1],edhec[,2],type="max")
CDaR.beta(edhec[,1],edhec[,2],type="average")

---

Calculate Uryasev's proposed Conditional Drawdown at Risk (CDD or CDaR) measure

Description

For some confidence level $p$, the conditional drawdown is the the mean of the worst $p\%$ drawdowns.

Usage

CDD(R, weights = NULL, geometric = TRUE, invert = TRUE, p = 0.95, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
weights	portfolio weighting vector, default NULL, see Details
geometric	utilize geometric chaining (TRUE) or simple/arithmetic chaining (FALSE) to aggregate returns, default TRUE
invert	TRUE/FALSE whether to invert the drawdown measure. see Details.
p	confidence level for calculation, default p=0.95
...	any other passthru parameters

Author(s)

Brian G. Peterson

References

Chekhlov, A., Uryasev, S., and M. Zabarankin. Portfolio Optimization With Drawdown Constraints. B. Scherer (Ed.) Asset and Liability Management Tools, Risk Books, London, 2003 http://www.ise.ufl.edu/uryasev/drawdown.pdf

See Also

ES maxDrawdown

Examples

data(edhec)
t(round(CDD(edhec),4))

---

Create ACF chart or ACF with PACF two-panel chart

Description

Creates an ACF chart or a two-panel plot with the ACF and PACF set to some specific defaults.

Usage

chart.ACF(R, maxlag = NULL, elementcolor = "gray", main = NULL, ...)

chart.ACFplus(R, maxlag = NULL, elementcolor = "gray", main = NULL, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
maxlag	the number of lags to calculate for, optional
elementcolor	the color to use for chart elements, defaults to "gray"
main	title of the plot; uses the column name by default.
...	any other passthru parameters

Note

Inspired by the website: http://www.stat.pitt.edu/stoffer/tsa2/Rcode/acf2.R "...here's an R function that will plot the ACF and PACF of a time series at the same time on the SAME SCALE, and it leaves out the zero lag in the ACF: acf2.R. If your time series is in x and you want the ACF and PACF of x to lag 50, the call to the function is acf2(x,50). The number of lags is optional, so acf2(x) will use a default number of lags [sqrt(n) + 10, where n is the number of observations]."

That description made a lot of sense, so it's implemented here for both the ACF alone and the ACF with the PACF.

Author(s)

Peter Carl

See Also

plot

Examples

data(edhec)
chart.ACFplus(edhec[,1,drop=FALSE])

---

wrapper for barchart of returns

Description

A wrapper to create a chart of periodic returns in a bar chart. This is a difficult enough graph to read that it doesn't get much use. Still, it is useful for viewing a single set of data.

Usage

chart.Bar(R, legend.loc = NULL, colorset = (1:12), ...)

charts.Bar(R, main = "Returns", cex.legend = 0.8, cex.main = 1, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
legend.loc	places a legend into one of nine locations on the chart: bottomright, bottom, bottomleft, left, topleft, top, topright, right, or center
colorset	color palette to use, set by default to rational choices
...	any other passthru parameters, see plot
main	sets the title text, such as in chart.TimeSeries
cex.legend	sets the legend text size, such as in chart.TimeSeries
cex.main	sets the title text size, such as in chart.TimeSeries

Details

This is really a wrapper for chart.TimeSeries, so several other attributes can also be passed.

Creates a plot of time on the x-axis and vertical lines for each period to indicate value on the y-axis.

Author(s)

Peter Carl

See Also

chart.TimeSeries
plot

Examples

data(edhec)
chart.Bar(edhec[,"Funds of Funds"], main="Monthly Returns")

---

Periodic returns in a bar chart with risk metric overlay

Description

Plots the periodic returns as a bar chart overlayed with a risk metric calculation.

Usage

chart.BarVaR(
  R,
  width = 0,
  gap = 12,
  methods = c("none", "ModifiedVaR", "GaussianVaR", "HistoricalVaR", "StdDev",
    "ModifiedES", "GaussianES", "HistoricalES"),
  p = 0.95,
  clean = c("none", "boudt", "geltner"),
  all = FALSE,
  ...,
  show.clean = FALSE,
  show.horizontal = FALSE,
  show.symmetric = FALSE,
  show.endvalue = FALSE,
  show.greenredbars = FALSE,
  legend.loc = "bottomleft",
  ylim = NA,
  lwd = 2,
  colorset = 1:12,
  lty = c(1, 2, 4, 5, 6),
  ypad = 0,
  legend.cex = 0.8,
  plot.engine = "default"
)

charts.BarVaR(
  R,
  main = "Returns",
  cex.legend = 0.8,
  colorset = 1:12,
  ylim = NA,
  ...,
  perpanel = NULL,
  show.yaxis = c("all", "firstonly", "alternating", "none")
)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
width	periods specified for rolling-period calculations. Note that VaR, ES, and Std Dev with width=0 are calculated from the start of the timeseries
gap	numeric number of periods from start of series to use to train risk calculation
methods	Used to select the risk parameter of trailing width returns to use: May be any of: none - does not add a risk line, ModifiedVaR - uses Cornish-Fisher modified VaR, GaussianVaR - uses traditional Value at Risk, HistoricalVaR - calculates historical Value at Risk, ModifiedES - uses Cornish-Fisher modified Expected Shortfall, GaussianES - uses traditional Expected Shortfall, HistoricalES - calculates historical Expected Shortfall, StdDev - per-period standard deviation
p	confidence level for VaR or ModifiedVaR calculation, default is .99
clean	the method to use to clean outliers from return data prior to risk metric estimation. See Return.clean and VaR for more detail
all	if TRUE, calculates risk lines for each column given in R. If FALSE, only calculates the risk line for the first column
...	any other passthru parameters to chart.TimeSeries
show.clean	if TRUE and a method for 'clean' is specified, overlays the actual data with the "cleaned" data. See Return.clean for more detail
show.horizontal	if TRUE, shows a line across the timeseries at the value of the most recent VaR estimate, to help the reader evaluate the number of exceptions thus far
show.symmetric	if TRUE and the metric is symmetric, this will show the metric's positive values as well as negative values, such as for method "StdDev".
show.endvalue	if TRUE, show the final (out of sample) value
show.greenredbars	if TRUE, show the per-period returns using green and red bars for positive and negative returns
legend.loc	legend location, such as in chart.TimeSeries
ylim	set the y-axis limit, same as in plot
lwd	set the line width, same as in plot
colorset	color palette to use, such as in chart.TimeSeries
lty	set the line type, same as in plot
ypad	adds a numerical padding to the y-axis to keep the data away when legend.loc="bottom". See examples below.
legend.cex	sets the legend text size, such as in chart.TimeSeries
plot.engine	Choose the engine for plotting, including "default","dygraph","ggplot","plotly" and "googleVis"
main	sets the title text, such as in chart.TimeSeries
cex.legend	sets the legend text size, such as in chart.TimeSeries
perpanel	default NULL, controls column display
show.yaxis	one of "all", "firstonly", "alternating", or "none" to control where y axis is plotted in multipanel charts

Details

Note that StdDev and VaR are symmetric calculations, so a high and low measure will be plotted. ModifiedVaR, on the other hand, is assymetric and only a lower bound will be drawn.

Creates a plot of time on the x-axis and vertical lines for each period to indicate value on the y-axis. Overlays a line to indicate the value of a risk metric calculated at that time period.

charts.BarVaR places multile bar charts in a single graphic, with associated risk measures

Author(s)

Peter Carl

See Also

chart.TimeSeries
plot
ES
VaR
Return.clean

Examples

## Not run:  # not run on CRAN because of example time
data(managers)
# plain
chart.BarVaR(managers[,1,drop=FALSE], main="Monthly Returns")

# with risk line
chart.BarVaR(managers[,1,drop=FALSE], 
		methods="HistoricalVaR", 
		main="... with Empirical VaR from Inception")
		
# with lines for all managers in the sample
chart.BarVaR(managers[,1:6], 
		methods="GaussianVaR", 
		all=TRUE, lty=1, lwd=2, 
		colorset= c("red", rep("gray", 5)), 
		main="... with Gaussian VaR and Estimates for Peers")

# with multiple methods
chart.BarVaR(managers[,1,drop=FALSE],
		methods=c("HistoricalVaR", "ModifiedVaR", "GaussianVaR"), 
		main="... with Multiple Methods")

# cleaned up a bit
chart.BarVaR(managers[,1,drop=FALSE],
		methods=c("HistoricalVaR", "ModifiedVaR", "GaussianVaR"), 
		lwd=2, ypad=.01, 
		main="... with Padding for Bottom Legend")

# with 'cleaned' data for VaR estimates
chart.BarVaR(managers[,1,drop=FALSE],
		methods=c("HistoricalVaR", "ModifiedVaR"), 
		lwd=2, ypad=.01, clean="boudt", 
		main="... with Robust ModVaR Estimate")

# Cornish Fisher VaR estimated with cleaned data, 
# with horizontal line to show exceptions
chart.BarVaR(managers[,1,drop=FALSE],
		methods="ModifiedVaR", 
		lwd=2, ypad=.01, clean="boudt", 
		show.horizontal=TRUE, lty=2, 
		main="... with Robust ModVaR and Line for Identifying Exceptions")

## End(Not run)

---

box whiskers plot wrapper

Description

A wrapper to create box and whiskers plot with some defaults useful for comparing distributions.

Usage

chart.Boxplot(
  R,
  names = TRUE,
  as.Tufte = FALSE,
  plot.engine = "default",
  sort.by = c(NULL, "mean", "median", "variance"),
  colorset = "black",
  symbol.color = "red",
  mean.symbol = 1,
  median.symbol = "|",
  outlier.symbol = 1,
  show.data = NULL,
  add.mean = TRUE,
  sort.ascending = FALSE,
  xlab = "Return",
  main = "Return Distribution Comparison",
  element.color = "darkgray",
  ...
)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
names	logical. if TRUE, show the names of each series
as.Tufte	logical. default FALSE. if TRUE use method derived for Tufte for limiting chartjunk
plot.engine	choose the plot engine you wish to use: ggplot2, plotly, googlevis and default
sort.by	one of "NULL", "mean", "median", "variance"
colorset	color palette to use, set by default to rational choices
symbol.color	draws the symbols described in mean.symbol,median.symbol,outlier.symbol in the color specified
mean.symbol	symbol to use for the mean of the distribution
median.symbol	symbol to use for the median of the distribution
outlier.symbol	symbol to use for the outliers of the distribution
show.data	numerical vector of column numbers to display on top of boxplot, default NULL
add.mean	logical. if TRUE, show a line for the mean of all distributions plotted
sort.ascending	logical. If TRUE sort the distributions by ascending sort.by
xlab	set the x-axis label, same as in plot
main	set the chart title, same as in plot
element.color	specify the color of chart elements. Default is "darkgray"
...	any other passthru parameters

Details

We have also provided controls for all the symbols and lines in the chart. One default, set by as.Tufte=TRUE, will strip chartjunk and draw a Boxplot per recommendations by Edward Tufte. It can also be useful when comparing several series to sort them in order of ascending or descending "mean", "median", "variance" by use of sort.by and sort.ascending=TRUE.

Value

box plot of returns

Author(s)

Peter Carl

References

Tufte, Edward R. The Visual Display of Quantitative Information. Graphics Press. 1983. p. 124-129

See Also

boxplot

Examples

data(edhec)
chart.Boxplot(edhec)
chart.Boxplot(edhec,as.Tufte=TRUE)

---

Chart of Capture Ratios against a benchmark

Description

Scatter plot of Up Capture versus Down Capture against a benchmark

Usage

chart.CaptureRatios(
  Ra,
  Rb,
  main = "Capture Ratio",
  add.names = TRUE,
  xlab = "Downside Capture",
  ylab = "Upside Capture",
  colorset = 1,
  symbolset = 1,
  legend.loc = NULL,
  xlim = NULL,
  ylim = NULL,
  cex.legend = 1,
  cex.axis = 0.8,
  cex.main = 1,
  cex.lab = 1,
  element.color = "darkgray",
  benchmark.color = "darkgray",
  ...
)

Arguments

Ra	Returns to test, e.g., the asset to be examined
Rb	Returns of a benchmark to compare the asset with
main	Set the chart title, same as in plot
add.names	Plots the row name with the data point. Default TRUE. Can be removed by setting it to NULL
xlab	Set the x-axis label, as in plot
ylab	Set the y-axis label, as in plot
colorset	Color palette to use, set by default to "black"
symbolset	From pch in plot. Submit a set of symbols to be used in the same order as the data sets submitted
legend.loc	Places a legend into one of nine locations on the chart: bottomright, bottom, bottomleft, left, topleft, top, topright, right, or center.
xlim	set the x-axis limit, same as in plot
ylim	set the y-axis limit, same as in plot
cex.legend	The magnification to be used for sizing the legend relative to the current setting of 'cex'.
cex.axis	The magnification to be used for axis annotation relative to the current setting of 'cex', same as in plot.
cex.main	The magnification to be used for sizing the title relative to the current setting of 'cex'.
cex.lab	The magnification to be used for x and y labels relative to the current setting of 'cex'.
element.color	Specify the color of the box, axes, and other chart elements. Default is "darkgray"
benchmark.color	Specify the color of the benchmark reference and crosshairs. Default is "darkgray"
...	Any other passthru parameters to plot

Details

Scatter plot shows the coordinates of each set of returns' Up and Down Capture against a benchmark. The benchmark value is by definition plotted at (1,1) with solid crosshairs. A diagonal dashed line with slope equal to 1 divides the plot into two regions: above that line the UpCapture exceeds the DownCapture, and vice versa.

Author(s)

Peter Carl

See Also

plot,
par,
UpDownRatios,
table.UpDownRatios

Examples

data(managers)
    chart.CaptureRatios(managers[,1:6], managers[,7,drop=FALSE])

---

correlation matrix chart

Description

Visualization of a Correlation Matrix. On top the (absolute) value of the correlation plus the result of the cor.test as stars. On bottom, the bivariate scatterplots, with a fitted line

Usage

chart.Correlation(
  R,
  histogram = TRUE,
  method = c("pearson", "kendall", "spearman"),
  pch = 1,
  ...
)

Arguments

R	data for the x axis, can take matrix,vector, or timeseries
histogram	TRUE/FALSE whether or not to display a histogram
method	a character string indicating which correlation coefficient (or covariance) is to be computed. One of "pearson" (default), "kendall", or "spearman", can be abbreviated.
pch	See par
...	any other passthru parameters into pairs

Note

based on plot at originally found at addictedtor.free.fr/graphiques/sources/source_137.R

Author(s)

Peter Carl

See Also

table.Correlation par

Examples

data(managers)
chart.Correlation(managers[,1:8], histogram=TRUE, pch="+")

---

Cumulates and graphs a set of periodic returns

Description

Chart that cumulates the periodic returns given and draws a line graph of the results as a "wealth index".

Usage

chart.CumReturns(
  R,
  wealth.index = FALSE,
  geometric = TRUE,
  legend.loc = NULL,
  colorset = (1:12),
  begin = c("first", "axis"),
  plot.engine = "default",
  ...
)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
wealth.index	if wealth.index is TRUE, shows the "value of $1", starting the cumulation of returns at 1 rather than zero
geometric	utilize geometric chaining (TRUE) or simple/arithmetic chaining (FALSE) to aggregate returns, default TRUE
legend.loc	places a legend into one of nine locations on the chart: bottomright, bottom, bottomleft, left, topleft, top, topright, right, or center.
colorset	color palette to use, set by default to rational choices
begin	Align shorter series to: first - prior value of the first column given for the reference or longer series or, axis - the initial value (1 or zero) of the axis.
plot.engine	choose the plot engine you wish to use" ggplot2, plotly,dygraph,googlevis and default
...	any other passthru parameters

Details

Cumulates the return series and displays either as a wealth index or as cumulative returns.

Author(s)

Peter Carl

References

Bacon, Carl. Practical Portfolio Performance Measurement and Attribution. Wiley. 2004.

See Also

chart.TimeSeries
plot

Examples

data(edhec)
chart.CumReturns(edhec[,"Funds of Funds"],main="Cumulative Returns")
chart.CumReturns(edhec[,"Funds of Funds"],wealth.index=TRUE, main="Growth of $1")
data(managers)
chart.CumReturns(managers,main="Cumulative Returns",begin="first")
chart.CumReturns(managers,main="Cumulative Returns",begin="axis")

---

Time series chart of drawdowns through time

Description

A time series chart demonstrating drawdowns from peak equity attained through time, calculated from periodic returns.

Usage

chart.Drawdown(
  R,
  geometric = TRUE,
  legend.loc = NULL,
  colorset = (1:12),
  plot.engine = "default",
  ...
)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
geometric	utilize geometric chaining (TRUE) or simple/arithmetic chaining (FALSE) to aggregate returns, default TRUE
legend.loc	places a legend into one of nine locations on the chart: bottomright, bottom, bottomleft, left, topleft, top, topright, right, or center.
colorset	color palette to use, set by default to rational choices
plot.engine	choose the plot engine you wish to use: ggplot2, plotly,dygraph,googlevis and default
...	any other passthru parameters

Details

Any time the cumulative returns dips below the maximum cumulative returns, it's a drawdown. Drawdowns are measured as a percentage of that maximum cumulative return, in effect, measured from peak equity.

Author(s)

Peter Carl

References

Bacon, C. Practical Portfolio Performance Measurement and Attribution. Wiley. 2004. p. 88

See Also

plot
chart.TimeSeries
findDrawdowns
sortDrawdowns
maxDrawdown
table.Drawdowns
table.DownsideRisk

Examples

data(edhec)
chart.Drawdown(edhec[,c(1,2)], 
		main="Drawdown from Peak Equity Attained", 
		legend.loc="bottomleft")

---

Create an ECDF overlaid with a Normal CDF

Description

Creates an emperical cumulative distribution function (ECDF) overlaid with a cumulative distribution function (CDF)

Usage

chart.ECDF(
  R,
  main = "Empirical CDF",
  xlab = "x",
  ylab = "F(x)",
  colorset = c("black", "#005AFF"),
  lwd = 1,
  lty = c(1, 1),
  element.color = "darkgray",
  xaxis = TRUE,
  yaxis = TRUE,
  ...
)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
main	set the chart title, same as in plot
xlab	set the x-axis label, same as in plot
ylab	set the y-axis label, same as in plot
colorset	color palette to use, defaults to c("black", "\#005AFF"), where first value is used to color the step function and the second color is used for the fitted normal
lwd	set the line width, same as in plot
lty	set the line type, same as in plot
element.color	specify the color of chart elements. Default is "darkgray"
xaxis	if true, draws the x axis
yaxis	if true, draws the y axis
...	any other passthru parameters to plot

Details

The empirical cumulative distribution function (ECDF for short) calculates the fraction of observations less or equal to a given value. The resulting plot is a step function of that fraction at each observation. This function uses ecdf and overlays the CDF for a fitted normal function as well. Inspired by a chart in Ruppert (2004).

Author(s)

Peter Carl

References

Ruppert, David. Statistics and Finance, an Introduction. Springer. 2004. Ch. 2 Fig. 2.5

See Also

plot, ecdf

Examples

data(edhec)
chart.ECDF(edhec[, 1, drop=FALSE])

---

Plots a time series with event dates aligned

Description

Creates a time series plot where events given by a set of dates are aligned, with the adjacent prior and posterior time series data plotted in order. The x-axis is time, but relative to the date specified, e.g., number of months preceeding or following the events.

Usage

chart.Events(R, dates, prior = 12, post = 12, main = NULL, xlab = NULL, ...)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
dates	a list of dates (e.g., c("09/03","05/06")) formatted the same as in R. This function matches the re-formatted row or index names (dates) with the given list, so to get a match the formatting needs to be correct.
prior	the number of periods to plot prior to the event. Interpreted as a positive number.
post	the number of periods to plot following to the event. Interpreted as a positive number.
main	set the chart title, same as in plot
xlab	set the x-axis label, same as in plot
...	any other passthru parameters to the plot function

Details

This is a chart that is commonly used for event studies in econometrics, usually with recession dates, to demonstrate the path of a time series going into and coming out of an event. The time axis is simply the number of periods prior and following the event, and each line represents a different event. Note that if time periods are close enough together and the window shown is wide enough, the data will appear to repeat. That can be confusing, but the function does not currently allow for different windows around each event.

Author(s)

Peter Carl

See Also

chart.TimeSeries,
plot,
par

Examples

## Not run: 
data(managers)
n = table.Drawdowns(managers[,2,drop=FALSE])                          
chart.Events(Drawdowns(managers[,2,drop=FALSE]), 
		dates = n$Trough, 
		prior=max(na.omit(n$"To Trough")), 
		post=max(na.omit(n$Recovery)), 
		lwd=2, colorset=redfocus, legend.loc=NULL, 
		main = "Worst Drawdowns")

## End(Not run)

---

histogram of returns

Description

Create a histogram of returns, with optional curve fits for density and normal. This is a wrapper function for hist, see the help for that function for additional arguments you may wish to pass in.

Usage

chart.Histogram(
  R,
  breaks = "FD",
  main = NULL,
  xlab = "Returns",
  ylab = "Frequency",
  methods = c("none", "add.density", "add.normal", "add.centered", "add.cauchy",
    "add.sst", "add.rug", "add.risk", "add.qqplot"),
  show.outliers = TRUE,
  colorset = c("lightgray", "#00008F", "#005AFF", "#23FFDC", "#ECFF13", "#FF4A00",
    "#800000"),
  border.col = "white",
  lwd = 2,
  xlim = NULL,
  ylim = NULL,
  element.color = "darkgray",
  note.lines = NULL,
  note.labels = NULL,
  note.cex = 0.7,
  note.color = "darkgray",
  probability = FALSE,
  p = 0.95,
  cex.axis = 0.8,
  cex.legend = 0.8,
  cex.lab = 1,
  cex.main = 1,
  xaxis = TRUE,
  yaxis = TRUE,
  ...
)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
breaks	one of: a vector giving the breakpoints between histogram cells, a single number giving the number of cells for the histogram, a character string naming an algorithm to compute the number of cells (see ‘Details’), a function to compute the number of cells. For the last three the number is a suggestion only. see hist for details, default "FD"
main	set the chart title, same as in plot
xlab	set the x-axis label, same as in plot
ylab	set the y-axis label, same as in plot
methods	what to graph, one or more of: add.density to display the density plot add.normal to display a fitted normal distibution line over the mean add.centered to display a fitted normal line over zero add.rug to display a rug of the observations add.risk to display common risk metrics add.qqplot to display a small qqplot in the upper corner of the histogram plot
show.outliers	logical; if TRUE (the default), the histogram will show all of the data points. If FALSE, it will show only the first through the fourth quartile and will exclude outliers.
colorset	color palette to use, set by default to rational choices
border.col	color to use for the border
lwd	set the line width, same as in plot
xlim	set the x-axis limit, same as in plot
ylim	set the y-axis limits, same as in plot
element.color	provides the color for drawing chart elements, such as the box lines, axis lines, etc. Default is "darkgray"
note.lines	draws a vertical line through the value given.
note.labels	adds a text label to vertical lines specified for note.lines.
note.cex	The magnification to be used for note line labels relative to the current setting of 'cex'.
note.color	specifies the color(s) of the vertical lines drawn.
probability	logical; if TRUE, the histogram graphic is a representation of frequencies, the counts component of the result; if FALSE, probability densities, component density, are plotted (so that the histogram has a total area of one). Defaults to TRUE if and only if breaks are equidistant (and probability is not specified). see hist
p	confidence level for calculation, default p=.99
cex.axis	The magnification to be used for axis annotation relative to the current setting of 'cex', same as in plot.
cex.legend	The magnification to be used for sizing the legend relative to the current setting of 'cex'.
cex.lab	The magnification to be used for x- and y-axis labels relative to the current setting of 'cex'.
cex.main	The magnification to be used for the main title relative to the current setting of 'cex'.
xaxis	if true, draws the x axis
yaxis	if true, draws the y axis
...	any other passthru parameters to plot

Details

The default for breaks is "FD". Other names for which algorithms are supplied are "Sturges" (see nclass.Sturges), "Scott", and "FD" / "Freedman-Diaconis" (with corresponding functions nclass.scott and nclass.FD). Case is ignored and partial matching is used. Alternatively, a function can be supplied which will compute the intended number of breaks as a function of R.

Note

Code inspired by a chart on:
http://zoonek2.free.fr/UNIX/48_R/03.html

Author(s)

Peter Carl

See Also

hist

Examples

data(edhec)
    chart.Histogram(edhec[,'Equity Market Neutral',drop=FALSE])

    # version with more breaks and the 
	   # standard close fit density distribution
    chart.Histogram(edhec[,'Equity Market Neutral',drop=FALSE], 
			breaks=40, methods = c("add.density", "add.rug") )

    chart.Histogram(edhec[,'Equity Market Neutral',drop=FALSE], 
			methods = c( "add.density", "add.normal") )

    # version with just the histogram and 
    # normal distribution centered on 0
    chart.Histogram(edhec[,'Equity Market Neutral',drop=FALSE], 
			methods = c( "add.density", "add.centered") )

    # add a rug to the previous plot 
	   # for more granularity on precisely where the distribution fell
    chart.Histogram(edhec[,'Equity Market Neutral',drop=FALSE], 
			methods = c( "add.centered", "add.density", "add.rug") )

    # now show a qqplot to give us another view 
    # on how normal the data are
    chart.Histogram(edhec[,'Equity Market Neutral',drop=FALSE], 
			methods = c("add.centered","add.density","add.rug","add.qqplot"))

    # add risk measure(s) to show where those are 
	   # in relation to observed returns
    chart.Histogram(edhec[,'Equity Market Neutral',drop=FALSE], 
			methods = c("add.density","add.centered","add.rug","add.risk"))

---

Plot a QQ chart

Description

Plot the return data against any theoretical distribution.

Usage

chart.QQPlot(
  R,
  distribution = "norm",
  ylab = NULL,
  xlab = paste(distribution, "Quantiles"),
  main = NULL,
  las = par("las"),
  envelope = FALSE,
  labels = FALSE,
  col = c(1, 4),
  lwd = 2,
  pch = 1,
  cex = 1,
  line = c("quartiles", "robust", "none"),
  element.color = "darkgray",
  cex.axis = 0.8,
  cex.legend = 0.8,
  cex.lab = 1,
  cex.main = 1,
  xaxis = TRUE,
  yaxis = TRUE,
  ylim = NULL,
  distributionParameter = NULL,
  ...
)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
distribution	root name of comparison distribution - e.g., 'norm' for the normal distribution; 't' for the t-distribution. See examples for other ideas.
ylab	set the y-axis label, as in plot
xlab	set the x-axis label, as in plot
main	set the chart title, same as in plot
las	set the direction of axis labels, same as in plot
envelope	confidence level for point-wise confidence envelope, or FALSE for no envelope.
labels	vector of point labels for interactive point identification, or FALSE for no labels.
col	color for points and lines; the default is the second entry in the current color palette (see 'palette' and 'par').
lwd	set the line width, as in plot
pch	symbols to use, see also plot
cex	symbols to use, see also plot
line	'quartiles' to pass a line through the quartile-pairs, or 'robust' for a robust-regression line; the latter uses the 'rlm' function in the 'MASS' package. Specifying 'line = "none"' suppresses the line.
element.color	provides the color for drawing chart elements, such as the box lines, axis lines, etc. Default is "darkgray"
cex.axis	The magnification to be used for axis annotation relative to the current setting of 'cex'
cex.legend	The magnification to be used for sizing the legend relative to the current setting of 'cex'
cex.lab	The magnification to be used for x- and y-axis labels relative to the current setting of 'cex'
cex.main	The magnification to be used for the main title relative to the current setting of 'cex'.
xaxis	if true, draws the x axis
yaxis	if true, draws the y axis
ylim	set the y-axis limits, same as in plot
distributionParameter	a string of the parameters of the distribution e.g., distributionParameter = 'location = 1, scale = 2, shape = 3, df = 4' for skew-T distribution
...	any other passthru parameters to the distribution function

Details

A Quantile-Quantile (QQ) plot is a scatter plot designed to compare the data to the theoretical distributions to visually determine if the observations are likely to have come from a known population. The empirical quantiles are plotted to the y-axis, and the x-axis contains the values of the theorical model. A 45-degree reference line is also plotted. If the empirical data come from the population with the choosen distribution, the points should fall approximately along this reference line. The larger the departure from the reference line, the greater the evidence that the data set have come from a population with a different distribution.

Author(s)

John Fox, ported by Peter Carl

References

main code forked/borrowed/ported from the excellent:
Fox, John (2007) car: Companion to Applied Regression
http://socserv.socsci.mcmaster.ca/jfox/

See Also

qqplot
qq.plot
plot

Examples

library(MASS) 
library(PerformanceAnalytics)
data(managers)
x = checkData(managers[,2, drop = FALSE], na.rm = TRUE, method = "vector")

# Panel 1: Normal distribution
chart.QQPlot(x, main = "Normal Distribution",
		line=c("quartiles"), distribution = 'norm',  
		envelope=0.95)


# Panel 2, Log-Normal distribution
fit = fitdistr(1+x, 'lognormal')
chart.QQPlot(1+x, main = "Log-Normal Distribution", envelope=0.95, 
    distribution='lnorm',distributionParameter='meanlog = fit$estimate[[1]], 
    sdlog = fit$estimate[[2]]')


## Not run:  
# Panel 3: Mixture Normal distribution
library(nor1mix)
obj = norMixEM(x,m=2)
chart.QQPlot(x, main = "Normal Mixture Distribution",
		line=c("quartiles"), distribution = 'norMix',  distributionParameter='obj',
		envelope=0.95)


# Panel 4: Symmetric t distribution
library(sn)
n = length(x)
fit.tSN = st.mple(as.matrix(rep(1,n)),x,symmetr = TRUE)
names(fit.tSN$dp) = c("location","scale","dof")
round(fit.tSN$dp,3)

chart.QQPlot(x, main = "MO Symmetric t-Distribution QQPlot",
		xlab = "quantilesSymmetricTdistEst",line = c("quartiles"),
		envelope = .95, distribution = 't', 
		distributionParameter='df=fit.tSN$dp[3]',pch = 20)

# Panel 5: Skewed t distribution
fit.st = st.mple(as.matrix(rep(1,n)),x)
# fit.st = st.mple(y=x)  Produces same result as line above
names(fit.st$dp) = c("location","scale","skew","dof")
round(fit.st$dp,3)

chart.QQPlot(x, main = "MO Returns Skewed t-Distribution QQPlot",
		xlab = "quantilesSkewedTdistEst",line = c("quartiles"),
		envelope = .95, distribution = 'st',
		distributionParameter = 'xi = fit.st$dp[1],
				omega = fit.st$dp[2],alpha = fit.st$dp[3],
				nu=fit.st$dp[4]',
		pch = 20)

# Panel 6: Stable Parietian
library(fBasics)
fit.stable = stableFit(x,doplot=FALSE)
chart.QQPlot(x, main = "Stable Paretian Distribution", envelope=0.95, 
             distribution = 'stable', 
             distributionParameter = 'alpha = fit(stable.fit)$estimate[[1]], 
                 beta = fit(stable.fit)$estimate[[2]], 
                 gamma = fit(stable.fit)$estimate[[3]], 
                 delta = fit(stable.fit)$estimate[[4]], pm = 0')

## End(Not run)

#end examples

---

Takes a set of returns and relates them to a market benchmark in a scatterplot

Description

Uses a scatterplot to display the relationship of a set of returns to a market benchmark. Fits a linear model and overlays the resulting model. Also overlays a Loess line for comparison.

Usage

chart.Regression(
  Ra,
  Rb,
  Rf = 0,
  excess.returns = FALSE,
  reference.grid = TRUE,
  main = "Title",
  ylab = NULL,
  xlab = NULL,
  xlim = NA,
  colorset = 1:12,
  symbolset = 1:12,
  element.color = "darkgray",
  legend.loc = NULL,
  ylog = FALSE,
  fit = c("loess", "linear", "conditional", "quadratic"),
  span = 2/3,
  degree = 1,
  family = c("symmetric", "gaussian"),
  ylim = NA,
  evaluation = 50,
  legend.cex = 0.8,
  cex = 0.8,
  lwd = 2,
  ...
)

Arguments

Ra	a vector of returns to test, e.g., the asset to be examined
Rb	a matrix, data.frame, or timeSeries of benchmark(s) to test the asset against
Rf	risk free rate, in same period as the returns
excess.returns	logical; should excess returns be used?
reference.grid	if true, draws a grid aligned with the points on the x and y axes
main	set the chart title, same as in plot
ylab	set the y-axis title, same as in plot
xlab	set the x-axis title, same as in plot
xlim	set the x-axis limit, same as in plot
colorset	color palette to use
symbolset	symbols to use, see also 'pch' in plot
element.color	provides the color for drawing chart elements, such as the box lines, axis lines, etc. Default is "darkgray"
legend.loc	places a legend into one of nine locations on the chart: bottomright, bottom, bottomleft, left, topleft, top, topright, right, or center.
ylog	Not used
fit	for values of "loess", "linear", or "conditional", plots a line to fit the data. Conditional lines are drawn separately for positive and negative benchmark returns. "Quadratic" is not yet implemented.
span	passed to loess line fit, as in loess.smooth
degree	passed to loess line fit, as in loess.smooth
family	passed to loess line fit, as in loess.smooth
ylim	set the y-axis limit, same as in plot
evaluation	passed to loess line fit, as in loess.smooth
legend.cex	set the legend size
cex	set the cex size, same as in plot
lwd	set the line width for fits, same as in lines
...	any other passthru parameters to plot

Author(s)

Peter Carl

References

Chapter 7 of Ruppert(2004) gives an extensive overview of CAPM, its assumptions and deficiencies.

See Also

plot

Examples

data(managers)
chart.Regression(managers[, 1:2, drop = FALSE], 
		managers[, 8, drop = FALSE], 
		Rf = managers[, 10, drop = FALSE], 
		excess.returns = TRUE, fit = c("loess", "linear"), 
		legend.loc = "topleft")

---

relative performance chart between multiple return series

Description

Plots a time series chart that shows the ratio of the cumulative performance for two assets at each point in time and makes periods of under- or out-performance easier to see.

Usage

chart.RelativePerformance(
  Ra,
  Rb,
  main = "Relative Performance",
  xaxis = TRUE,
  colorset = (1:12),
  legend.loc = NULL,
  ylog = FALSE,
  elementcolor = "darkgray",
  lty = 1,
  cex.legend = 0.7,
  ...
)

Arguments

Ra	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
Rb	return vector of the benchmark asset
main	set the chart title, same as in plot
xaxis	if true, draws the x axis
colorset	color palette to use, set by default to rational choices
legend.loc	places a legend into one of nine locations on the chart: bottomright, bottom, bottomleft, left, topleft, top, topright, right, or center.
ylog	TRUE/FALSE set the y-axis to logarithmic scale, similar to plot, default FALSE
elementcolor	provides the color for drawing less-important chart elements, such as the box lines, axis lines, etc. replaces darken
lty	set the line type, same as in plot
cex.legend	the magnification to be used for sizing the legend relative to the current setting of 'cex'.
...	any other passthru parameters

Details

To show under- and out-performance through different periods of time, a time series view is more helpful. The value of the chart is less important than the slope of the line. If the slope is positive, the first asset (numerator) is outperforming the second, and vice versa. May be used to look at the returns of a fund relative to each member of the peer group and the peer group index. Alternatively, it might be used to assess the peers individually against an asset class or peer group index.

Author(s)

Peter Carl

See Also

Return.relative

Examples

data(managers)
chart.RelativePerformance(managers[, 1:6, drop=FALSE], 
		managers[, 8, drop=FALSE], 
		colorset=rich8equal, legend.loc="bottomright", 
		main="Relative Performance to S&P")

---

scatter chart of returns vs risk for comparing multiple instruments

Description

A wrapper to create a scatter chart of annualized returns versus annualized risk (standard deviation) for comparing manager performance. Also puts a box plot into the margins to help identify the relative performance quartile.

Usage

chart.RiskReturnScatter(
  R,
  Rf = 0,
  main = "Annualized Return and Risk",
  add.names = TRUE,
  xlab = "Annualized Risk",
  ylab = "Annualized Return",
  method = "calc",
  geometric = TRUE,
  scale = NA,
  add.sharpe = c(1, 2, 3),
  add.boxplots = FALSE,
  colorset = 1,
  symbolset = 1,
  element.color = "darkgray",
  legend.loc = NULL,
  xlim = NULL,
  ylim = NULL,
  cex.legend = 1,
  cex.axis = 0.8,
  cex.main = 1,
  cex.lab = 1,
  ...
)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
Rf	risk free rate, in same period as your returns
main	set the chart title, same as in plot
add.names	plots the row name with the data point. default TRUE. Can be removed by setting it to NULL
xlab	set the x-axis label, as in plot
ylab	set the y-axis label, as in plot
method	if set as "calc", then the function will calculate values from the set of returns passed in. If method is set to "nocalc" then we assume that R is a column of return and a column of risk (e.g., annualized returns, annualized risk), in that order. Other method cases may be set for different risk/return calculations.
geometric	utilize geometric chaining (TRUE) or simple/arithmetic chaining (FALSE) to aggregate returns, default TRUE
scale	number of periods in a year (daily scale = 252, monthly scale = 12, quarterly scale = 4)
add.sharpe	this draws a Sharpe ratio line that indicates Sharpe ratio levels of c(1,2,3). Lines are drawn with a y-intercept of the risk free rate and the slope of the appropriate Sharpe ratio level. Lines should be removed where not appropriate (e.g., sharpe.ratio = NULL).
add.boxplots	TRUE/FALSE adds a boxplot summary of the data on the axis
colorset	color palette to use, set by default to rational choices
symbolset	from pch in plot, submit a set of symbols to be used in the same order as the data sets submitted
element.color	provides the color for drawing chart elements, such as the box lines, axis lines, etc. Default is "darkgray"
legend.loc	places a legend into one of nine locations on the chart: bottomright, bottom, bottomleft, left, topleft, top, topright, right, or center.
xlim	set the x-axis limit, same as in plot
ylim	set the y-axis limit, same as in plot
cex.legend	The magnification to be used for sizing the legend relative to the current setting of 'cex'.
cex.axis	The magnification to be used for axis annotation relative to the current setting of 'cex', same as in plot.
cex.main	The magnification to be used for sizing the title relative to the current setting of 'cex'.
cex.lab	The magnification to be used for x and y labels relative to the current setting of 'cex'.
...	any other passthru parameters to plot

Note

Code inspired by a chart on: http://zoonek2.free.fr/UNIX/48_R/03.html

Author(s)

Peter Carl

Examples

data(edhec)
chart.RiskReturnScatter(edhec, Rf = .04/12)
chart.RiskReturnScatter(edhec, Rf = .04/12, add.boxplots = TRUE)

---

chart rolling correlation fo multiple assets

Description

A wrapper to create a chart of rolling correlation metrics in a line chart

Usage

chart.RollingCorrelation(
  Ra,
  Rb,
  width = 12,
  xaxis = TRUE,
  legend.loc = NULL,
  colorset = (1:12),
  ...,
  fill = NA
)

Arguments

Ra	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
Rb	return vector of the benchmark asset
width	number of periods to apply rolling function window over
xaxis	if true, draws the x axis
legend.loc	places a legend into one of nine locations on the chart: bottomright, bottom, bottomleft, left, topleft, top, topright, right, or center.
colorset	color palette to use, set by default to rational choices
...	any other passthru parameters
fill	a three-component vector or list (recycled otherwise) providing filling values at the left/within/to the right of the data range. See the fill argument of na.fill for details.

Details

The previous parameter na.pad has been replaced with fill; use fill = NA instead of na.pad = TRUE, or fill = NULL instead of na.pad = FALSE.

Author(s)

Peter Carl

Examples

# First we get the data
data(managers)
chart.RollingCorrelation(managers[, 1:6, drop=FALSE], 
		managers[, 8, drop=FALSE], 
		colorset=rich8equal, legend.loc="bottomright", 
		width=24, main = "Rolling 12-Month Correlation")

---

chart the rolling mean return

Description

A wrapper to create a rolling mean return chart with 95

Usage

chart.RollingMean(
  R,
  width = 12,
  xaxis = TRUE,
  ylim = NULL,
  lwd = c(2, 1, 1),
  ...,
  fill = NA
)

Arguments

R	an xts, vector, matrix, data frame, timeSeries or zoo object of asset returns
width	number of periods to apply rolling function window over
xaxis	if true, draws the x axis
ylim	set the y-axis limit, same as in plot
lwd	set the line width, same as in plot. Specified in order of the main line and the two confidence bands.
...	any other passthru parameters
fill	a three-component vector or list (recycled otherwise) providing filling values at the left/within/to the right of the data range. See the fill argument of na.fill for details.

Details

The previous parameter na.pad has been replaced with fill; use fill = NA instead of na.pad = TRUE, or fill = NULL instead of na.pad = FALSE.

Author(s)

Peter Carl

Examples

data(edhec)
chart.RollingMean(edhec[, 9, drop = FALSE])

---