Merge pull request #266 from robertmartin8/v1.3.1

v1.3.1

Author: robertmartin8

README.md

@@ -8,7 +8,7 @@
         <img src="https://img.shields.io/badge/python-v3-brightgreen.svg"
             alt="python"></a> &nbsp;
     <a href="https://pypi.org/project/PyPortfolioOpt/">
-        <img src="https://img.shields.io/badge/pypi-v1.3.0-brightgreen.svg"
+        <img src="https://img.shields.io/badge/pypi-v1.3.1-brightgreen.svg"
             alt="pypi"></a> &nbsp;
     <a href="https://opensource.org/licenses/MIT">
         <img src="https://img.shields.io/badge/license-MIT-brightgreen.svg"

docs/Plotting.rst

@@ -4,15 +4,46 @@
 Plotting
 ########
 
+All of the optimisation functions in :py:class:`EfficientFrontier` produce a single optimal portfolio.
+However, you may want to plot the entire efficient frontier. This efficient frontier can be thought
+of in several different ways:
 
-.. automodule:: pypfopt.plotting
+1. The set of all :py:func:`efficient_risk` portfolios for a range of target risks
+2. The set of all :py:func:`efficient_return` portfolios for a range of target returns
+3. The set of all :py:func:`max_quadratic_utility` portfolios for a range of risk aversions.
 
-    .. autofunction:: _plot_io
+The :py:mod:`plotting` module provides support for all three of these approaches. To produce
+a plot of the efficient frontier, you should instantiate your :py:class:`EfficientFrontier` object
+and add constraints like you normally would, but *before* calling an optimisation function (e.g with
+:py:func:`ef.max_sharpe`), you should pass this the instantiated object into :py:func:`plot.plot_efficient_frontier`:: 
+
+    ef = EfficientFrontier(mu, S, weight_bounds=(None, None))
+    ef.add_constraint(lambda w: w[0] >= 0.2)
+    ef.add_constraint(lambda w: w[2] == 0.15)
+    ef.add_constraint(lambda w: w[3] + w[4] <= 0.10)
+
+    # 100 portfolios with risks between 0.10 and 0.30
+    risk_range = np.linspace(0.10, 0.40, 100)
+    ax = plotting.plot_efficient_frontier(ef, ef_param="risk", ef_param_range=risk_range,
+                               show_assets=True, showfig=True)
+
+This produces the following plot -- you can set attributes using the returned ``ax`` object: 
+
+    .. image:: ../media/ef_plot.png
+        :width: 80%
+        :align: center
+        :alt: the Efficient Frontier
+
+
+.. automodule:: pypfopt.plotting
 
     .. tip::
 
         To save the plot, pass ``filename="somefile.png"`` as a keyword argument to any of
-        the methods below.
+        the plotting functions. This (along with some other kwargs) get passed through
+        :py:func:`_plot_io` before being returned.
+
+    .. autofunction:: _plot_io
 
     .. autofunction:: plot_covariance
 

docs/Roadmap.rst

@@ -25,12 +25,19 @@ discuss. If you have any other feature requests, please raise them using GitHub
 1.3.0
 =====
 
+- Significantly improved plotting functionality: can now plot constrained efficient frontier!
 - Efficient semivariance portfolios (thanks to `Philipp Schiele <https://github.com/phschiele>`_)
 - Improved functionality for portfolios with short positions (thanks to `Rich Caputo <https://github.com/arcaputo3>`_).
 - Significant improvement in test coverage (thanks to `Carl Peasnell <https://github.com/SeaPea1>`_).
 - Several bug fixes and usability improvements.
 - Migrated from TravisCI to Github Actions.
 
+1.3.1
+-----
+
+- Minor cleanup (forgotten commits from v1.3.0).
+
+
 1.2.0
 =====
 

docs/conf.py

@@ -58,7 +58,7 @@
 # The short X.Y version.
 version = "1.3"
 # The full version, including alpha/beta/rc tags.
-release = "1.3.0"
+release = "1.3.1"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -12,16 +12,16 @@
     <embed>
         <p align="center">
             <a href="https://www.python.org/">
-                <img src="https://img.shields.io/badge/python-v3-brightgreen.svg?style=flat-square"
+                <img src="https://img.shields.io/badge/python-v3-brightgreen.svg"
                     alt="python"></a> &nbsp;
             <a href="https://pypi.org/project/PyPortfolioOpt/">
-                <img src="https://img.shields.io/badge/pypi-v1.3.0-brightgreen.svg?style=flat-square"
+                <img src="https://img.shields.io/badge/pypi-v1.3.1-brightgreen.svg"
                     alt="python"></a> &nbsp;
             <a href="https://opensource.org/licenses/MIT">
-                <img src="https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square"
+                <img src="https://img.shields.io/badge/license-MIT-brightgreen.svg"
                     alt="MIT license"></a> &nbsp;
             <a href="https://github.com/robertmartin8/PyPortfolioOpt/graphs/commit-activity">
-                <img src="https://img.shields.io/badge/Maintained%3F-yes-brightgreen.svg?style=flat-square"
+                <img src="https://img.shields.io/badge/Maintained%3F-yes-brightgreen.svg"
                     alt="MIT license"></a> &nbsp;
         </p>
     </embed>

media/ef_plot.png

@@ -10,7 +10,7 @@
 from .risk_models import CovarianceShrinkage
 
 
-__version__ = "1.3.0"
+__version__ = "1.3.1"
 
 __all__ = [
     "market_implied_prior_returns",

poetry.lock

@@ -120,16 +120,17 @@ class BaseConvexOptimizer(BaseOptimizer):
     """
     The BaseConvexOptimizer contains many private variables for use by
     ``cvxpy``. For example, the immutable optimisation variable for weights
-    is stored as self._w. Interacting directly with these variables is highly
-    discouraged.
+    is stored as self._w. Interacting directly with these variables directly
+    is discouraged.
 
     Instance variables:
 
     - ``n_assets`` - int
     - ``tickers`` - str list
     - ``weights`` - np.ndarray
-    - ``solver`` - str
-    - ``solver_options`` - {str: str} dict
+    - ``_opt`` - cp.Problem
+    - ``_solver`` - str
+    - ``_solver_options`` - {str: str} dict
 
     Public methods:
 
@@ -175,6 +176,7 @@ def __init__(
         self._upper_bounds = None
         self._map_bounds_to_constraints(weight_bounds)
 
+        self._opt = None
         self._solver = solver
         self._verbose = verbose
         self._solver_options = solver_options if solver_options else {}
@@ -227,19 +229,21 @@ def _solve_cvxpy_opt_problem(self):
         :raises exceptions.OptimizationError: if problem is not solvable by cvxpy
         """
         try:
-            opt = cp.Problem(cp.Minimize(self._objective), self._constraints)
+            self._opt = cp.Problem(cp.Minimize(self._objective), self._constraints)
 
             if self._solver is not None:
-                opt.solve(
+                self._opt.solve(
                     solver=self._solver, verbose=self._verbose, **self._solver_options
                 )
             else:
-                opt.solve(verbose=self._verbose, **self._solver_options)
+                self._opt.solve(verbose=self._verbose, **self._solver_options)
         except (TypeError, cp.DCPError) as e:
             raise exceptions.OptimizationError from e
 
-        if opt.status not in {"optimal", "optimal_inaccurate"}:
-            raise exceptions.OptimizationError("Solver status: {}".format(opt.status))
+        if self._opt.status not in {"optimal", "optimal_inaccurate"}:
+            raise exceptions.OptimizationError(
+                "Solver status: {}".format(self._opt.status)
+            )
         self.weights = self._w.value.round(16) + 0.0  # +0.0 removes signed zero
         return self._make_output_weights()