R/CLA.R

@@ -210,7 +210,9 @@ MS_plot <- function(ms, type = "o",
 }
 
 
-## FIXME:
+## FIXME: --> see also in ../man/plot.CLA.Rd
+## -----
+## 0) Use findMu() and findSig() to draw the lines *between*
 ## 1) Learn from Tobias Setz to plot the lower part of the feasible region
 ## 2) Better title, using 'call'
 ## 3) mark some critical points particularly
@@ -221,7 +223,7 @@ plot.CLA <- function(x, type = "o", main = "Efficient Frontier",
                     ylab = expression(mu(w)),
                     col = adjustcolor("blue", alpha.f = 0.5),
                     pch = 16, ...) {
-    stopifnot(is.matrix(ms <- x$MSweights))
+    stopifnot(is.matrix(ms <- x$MS_weights))
     plot(ms[,"Sig"], ms[,"Mu"], type=type, pch=pch, col=col,
          xlab=xlab, ylab=ylab, main=main, ...)
 }

TODO

 ##-*- org -*-->  Emacs .. [Tab] key + [Org] menu; C-c C-o to follow links
 
-* Before release of package
+* ASAP (no longer "Before release of package")
 ** check arguments  e.g., lB <= uB, sum upper Bounds >= 1
-** TODO References -->
-*** 1) Master thesis: I'd like the thesis to be on our web page
-*** 2) References from the thesis, including the "buried" python-paper with *WRONG* algo
+** TODO References --> (partly done)
+*** DONE 1) References from the thesis, including the "buried" python-paper with *WRONG* algo
+*** TODO 2) Master thesis: I'd like the thesis to be on our web page
 ** DONE CLA() should return a (S3) class, "CLA" w/ print() and plot() methods
+** TODO findMu() and findSig() regression check examples *before* changing R/findSigMu.R
+** TODO Improve plot() method, using hyperbolic interpolation see  R/CLA.R  man/plot.CLA.Rd
+** TODO  A. Norring's Masters thesis has a small 12-asset example (from a published source).
+   We should add that as a minimally small data set to use in examples,
+   e.g. plot(). His thesis is in ~/Betreute-Arbeiten/YanhaoShi/Previous_Work/
 
 * With more time, also, e.g., for a short R Journal paper
 ** SparseMatrix plot of the weights

man/CLA.Rd

 \name{CLA}
 \alias{CLA}
-\title{Critical Line Algorithm}
+\title{Critical Line Algorithm for mean-variance optimal portfolio}
 \description{
-  The Critical Line Algorithm was first proposed by Markowitz to solve
-  the mean-variance optimal portfolio problem.
+  The Critical Line Algorithm was first proposed by Markowitz(1987) to
+  solve the mean-variance optimal portfolio problem.
 
-  ... TODO: write more; give references (below) ...
+  We solve the problem with \dQuote{box} constraints, i.e., allow to
+  specify lower and upper bounds (via \code{lB} and \code{uB}) for each
+  asset weight.
+
+  Here we provide a pure \R{} implementation, quite fine tuned and
+  debugged compared to earlier ones.
 }
 \usage{
-CLA(mu, covar, lB, uB, tol.lambda = 1e-07, give.MS = TRUE, keep.names = TRUE)
+CLA(mu, covar, lB, uB, tol.lambda = 1e-07,
+    give.MS = TRUE, keep.names = TRUE)
 }
 \arguments{
   \item{mu}{numeric vector of length \code{n} containing the expected
@@ -24,28 +30,68 @@ CLA(mu, covar, lB, uB, tol.lambda = 1e-07, give.MS = TRUE, keep.names = TRUE)
   \item{keep.names}{\code{\link{logical}} indicating if the
     \code{weights_set} matrix should keep the (asset) \code{names(mu)}.}
 }
-%% \details{
-%% }
+\details{
+  The current implementation of the CLA is based (via Norring's)
+  on Bailey et al.(2013).   We have found buglets in that implementation
+  which lead them to introduce their \dQuote{purge} routines
+  (\code{purgeNumErr}, \code{purgeExcess}),% in Y. Shi's masters' thesis
+  which are no longer necessary.
+
+  Even though this is a pure \R implementation, the algorithm is quite fast
+  also when the number of assets \eqn{n} is large (1000s), though that
+  depends quite a bit on the exact problem.
+}
 \value{
-  a \code{\link{list}} with components
-  \item{weights_set}{ ...}
+  an object of \code{\link{class}} \code{"CLA"} which is a
+  \code{\link{list}} with components
 
-  \item{free_indices}{ ... }
-  \item{gammas}{ ... }
-  \item{lambdas}{ .... }
+  \item{weights_set}{a \eqn{n \times m}{n * m} matrix of asset weights,
+    corresponding to the \eqn{m} steps that the CLA has completed or the
+    \eqn{m} \dQuote{turning points} it has computed.}
+  \item{free_indices}{a \code{\link{list}} of length \code{m}, the
+    \eqn{k}-th component with the indices in \eqn{\{1,\dots,n\}} of
+    those assets whose weights were not at the boundary afater ... }
+  \item{gammas}{numeric vector of length \eqn{m} of the values
+    \eqn{\gamma_k}{gamma[k]} for CLA step \eqn{k}, \eqn{k=1,\dots,n}.}
+  \item{lambdas}{numeric vector of length \eqn{m} of the Lagrange parameters
+    \eqn{\lambda_k}{lambda[k]} for CLA step \eqn{k}, \eqn{k=1,\dots,n}.}
   \item{MS_weights}{the \eqn{\mu(W)} and \eqn{\sigma(W)} corresponding
     to the asset weights \code{weights_set}, i.e., simply the same as
-    \code{MS(weights_set = weights_set, mu = mu, covar = covar)}.}
+    \code{\link{MS}(weights_set = weights_set, mu = mu, covar = covar)}.}
 }
 \references{
-TODO
+  Markowitz, H. (1952)
+  Portfolio selection, \emph{The Journal of Finance} \bold{7}, 77--91;
+  \doi{10.2307/2975974}.
+
+  Markowitz, H. M. (1987, 1st ed.) and
+  Markowitz, H. M. and Todd, P. G. (2000)
+  \emph{Mean-Variance Analysis in Portfolio Choice and Capital Markets};
+  chapters 7 and 13.
+
+  %% Markowitz, H., Todd, P., Xu, G. and Yamane, Y. (1993)
+  %% Computation of mean-semivariance efficient sets by the Critical Line Algorithm,
+  %% \emph{Annals of Operations Research} \bold{45}(1): 307--317;
+  %% \doi{10.1007/BF02282055}.
+
+  Niedermayer, A. and Niedermayer, D. (2010)
+  Applying markowitz’s critical line algorithm, in J. B. Guerard (ed.),
+  Handbook of Portfolio Construction, Springer; chapter 12, 383--400;
+  \doi{10.1007/978-0-387-77439-8_12}.
+
+  Bailey, D. H. and López de Prado, M. (2013)
+  An open-source implementation of the critical-line algorithm for portfolio
+  optimization, \emph{Algorithms} \bold{6}(1), 169--196;
+  \doi{10.3390/a6010169},
 }
-\author{Alexander Norring did the very first version. Current
-  implementation: Yanhao Shi and Martin Maechler}
 %% \note{
 %% }
+\author{Alexander Norring did the very first version (unpublished master
+  thesis). Current implementation: Yanhao Shi and Martin Maechler
+}
 \seealso{
-  \code{\link{MS}}.
+  \code{\link{MS}};
+  for plotting \code{CLA} results: \code{\link{plot.CLA}}.
 }
 \examples{
 data(muS.sp500)
@@ -56,11 +102,12 @@ iS <- sample.int(length(muS.sp500$mu), 24)
 CLsp.24 <- CLA(muS.sp500$mu[iS], muS.sp500$covar[iS, iS], lB=0, uB=1/10)
 CLsp.24 # using the print() method for class "CLA"
 
+plot(CLsp.24)
+
 if(require(Matrix)) { ## visualize how weights change "along turning points"
   show(image(Matrix(CLsp.24$weights_set, sparse=TRUE),
              main = "CLA(muS.sp500 <random_sample(size=24)>) $ weights_set",
              xlab = "turning point", ylab = "asset number"))
 }
-
 }
-%\keyword{ ~kwd1 }% use one of  RShowDoc("KEYWORDS")
+

man/MS.Rd

@@ -18,8 +18,12 @@ MS(weights_set, mu, covar)
   \item{covar}{covariance matrix of (log) returns (identical to
     \emph{argument} of \code{\link{CLA}()}).}
 }
-%% \details{
-%% }
+\details{
+  These are trivially computable from the \code{\link{CLA}()}'s result.
+  To correctly \emph{interpolate} this, \dQuote{hyperbolic}
+  interpolation is needed, provided by the \code{\link{findSig}} and
+  \code{\link{findMu}} functions.% say more, here or there
+}
 \value{
   a \code{\link{list}} with components
   \item{Sig}{numeric vector of length \eqn{m} of standard deviations,

man/plot.CLA.Rd

+\name{plot.CLA}
+\alias{plot.CLA}
+\title{Plotting CLA() results including Efficient Frontier}
+\description{
+  A partly experimental \code{\link{plot}()} method for
+  \code{\link{CLA}()} objects.
+
+  It draws the efficient frontier in the \eqn{\mu_w,\sigma_w} aka (mean,
+  std.dev.) plane.
+
+  Currently, this is quite rudimentary.\cr
+  Future improvements would allow
+  - to add the/some single asset points,
+  - to correctly   (`hyperbolically') interpolate between turning points
+  - add text about the number of (unique) critical points
+  - add option \code{add = FALSE} which when TRUE would use
+    \code{\link{lines}} instead \code{plot}.
+}
+\usage{%% --> ../R/CLA.R
+\method{plot}{CLA}(x, type = "o", main = "Efficient Frontier",
+     xlab = expression(sigma(w)),
+     ylab = expression(mu(w)),
+     col = adjustcolor("blue", alpha.f = 0.5),
+     pch = 16, \dots)
+}
+\arguments{
+  \item{x}{a named \code{\link{list}} as resulting from \code{\link{CLA}()}.}
+  \item{type}{the \code{\link{lines}}/\code{\link{points}} types used
+  for the efficient frontier.  This will become more sophisticated,
+  i.e., \emph{may change non-compatibly!!}}
+  \item{main}{main \code{\link{title}}.}
+  \item{xlab, ylab}{x- and y- axis labels, passed to \code{\link{plot.default}}.}
+  \item{col, pch}{color and point type, passed to
+  \code{\link{plot.default}}, but with differing defaults in this method.}
+  \item{\dots}{potentially further arguments passed to
+    \code{\link{plot}}, i.e., \code{\link{plot.default}}.}
+}
+%% \details{
+%% }
+%% \value{
+%% }
+\author{Martin Maechler.}
+\seealso{
+  \code{\link{CLA}}, \code{\link{plot.default}}.
+}
+\examples{
+## TODO %% Add A. Norring's small 12-asset example see --> ../TODO
+## ---- one example is in help(CLA)
+}
+\keyword{hplot}
+