cookbook/3-Advanced-Mean-Variance-Optimisation.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "pQhw2JJu_YO0"
      },
      "source": [
        "# Advanced MVO - custom objectives\n",
        "\n",
        "PyPortfolioOpt has implemented some of the most common objective functions (e.g `min_volatility`, `max_sharpe`, `max_quadratic_utility`, `efficient_risk`, `efficient_return`). However, sometimes yoy may have an idea for a different objective function.\n",
        "\n",
        "In this cookbook recipe, we cover:\n",
        "\n",
        "- Mininimising transaction costs\n",
        "- Custom convex objectives\n",
        "- Custom nonconvex objectives\n",
        "\n",
        "## Acquiring data\n",
        "\n",
        "As discussed in the previous notebook, assets are an exogenous input (i.e you must come up with a list of tickers). We will use `yfinance` to download data for thesee tickers\n",
        "\n",
        "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/robertmartin8/PyPortfolioOpt/blob/master/cookbook/3-Advanced-Mean-Variance-Optimisation.ipynb)\n",
        "    \n",
        "[![Kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://github.com/robertmartin8/PyPortfolioOpt/blob/master/cookbook/3-Advanced-Mean-Variance-Optimisation.ipynb)\n",
        "    \n",
        "[![Gradient](https://assets.paperspace.io/img/gradient-badge.svg)](https://console.paperspace.com/github/robertmartin8/PyPortfolioOpt/blob/master/cookbook/3-Advanced-Mean-Variance-Optimisation.ipynb)\n",
        "    \n",
        "[![Open In SageMaker Studio Lab](https://studiolab.sagemaker.aws/studiolab.svg)](https://studiolab.sagemaker.aws/import/github/robertmartin8/PyPortfolioOpt/blob/master/cookbook/3-Advanced-Mean-Variance-Optimisation.ipynb)"
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "!pip install pandas numpy matplotlib yfinance PyPortfolioOpt\n",
        "import os\n",
        "if not os.path.isdir('data'):\n",
        "    os.system('git clone https://github.com/robertmartin8/PyPortfolioOpt.git')\n",
        "    os.chdir('PyPortfolioOpt/cookbook')"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "kWJJAvG4_iEz",
        "outputId": "26b7d743-eb20-4fb5-a99d-f4a5098ee8ad"
      },
      "execution_count": 5,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Requirement already satisfied: pandas in /usr/local/lib/python3.7/dist-packages (1.3.5)\n",
            "Requirement already satisfied: numpy in /usr/local/lib/python3.7/dist-packages (1.19.5)\n",
            "Requirement already satisfied: matplotlib in /usr/local/lib/python3.7/dist-packages (3.2.2)\n",
            "Collecting yfinance\n",
            "  Downloading yfinance-0.1.70-py2.py3-none-any.whl (26 kB)\n",
            "Collecting PyPortfolioOpt\n",
            "  Downloading PyPortfolioOpt-1.5.1-py3-none-any.whl (61 kB)\n",
            "\u001b[K     |████████████████████████████████| 61 kB 5.0 MB/s \n",
            "\u001b[?25hRequirement already satisfied: pytz>=2017.3 in /usr/local/lib/python3.7/dist-packages (from pandas) (2018.9)\n",
            "Requirement already satisfied: python-dateutil>=2.7.3 in /usr/local/lib/python3.7/dist-packages (from pandas) (2.8.2)\n",
            "Requirement already satisfied: six>=1.5 in /usr/local/lib/python3.7/dist-packages (from python-dateutil>=2.7.3->pandas) (1.15.0)\n",
            "Requirement already satisfied: kiwisolver>=1.0.1 in /usr/local/lib/python3.7/dist-packages (from matplotlib) (1.3.2)\n",
            "Requirement already satisfied: cycler>=0.10 in /usr/local/lib/python3.7/dist-packages (from matplotlib) (0.11.0)\n",
            "Requirement already satisfied: pyparsing!=2.0.4,!=2.1.2,!=2.1.6,>=2.0.1 in /usr/local/lib/python3.7/dist-packages (from matplotlib) (3.0.7)\n",
            "Requirement already satisfied: multitasking>=0.0.7 in /usr/local/lib/python3.7/dist-packages (from yfinance) (0.0.10)\n",
            "Collecting requests>=2.26\n",
            "  Downloading requests-2.27.1-py2.py3-none-any.whl (63 kB)\n",
            "\u001b[K     |████████████████████████████████| 63 kB 1.9 MB/s \n",
            "\u001b[?25hCollecting lxml>=4.5.1\n",
            "  Downloading lxml-4.7.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl (6.4 MB)\n",
            "\u001b[K     |████████████████████████████████| 6.4 MB 48.9 MB/s \n",
            "\u001b[?25hRequirement already satisfied: idna<4,>=2.5 in /usr/local/lib/python3.7/dist-packages (from requests>=2.26->yfinance) (2.10)\n",
            "Requirement already satisfied: urllib3<1.27,>=1.21.1 in /usr/local/lib/python3.7/dist-packages (from requests>=2.26->yfinance) (1.24.3)\n",
            "Requirement already satisfied: certifi>=2017.4.17 in /usr/local/lib/python3.7/dist-packages (from requests>=2.26->yfinance) (2021.10.8)\n",
            "Requirement already satisfied: charset-normalizer~=2.0.0 in /usr/local/lib/python3.7/dist-packages (from requests>=2.26->yfinance) (2.0.11)\n",
            "Requirement already satisfied: scipy<2.0,>=1.3 in /usr/local/lib/python3.7/dist-packages (from PyPortfolioOpt) (1.4.1)\n",
            "Collecting cvxpy<2.0.0,>=1.1.10\n",
            "  Downloading cvxpy-1.1.18-cp37-cp37m-manylinux_2_24_x86_64.whl (2.7 MB)\n",
            "\u001b[K     |████████████████████████████████| 2.7 MB 42.3 MB/s \n",
            "\u001b[?25hRequirement already satisfied: scs>=1.1.6 in /usr/local/lib/python3.7/dist-packages (from cvxpy<2.0.0,>=1.1.10->PyPortfolioOpt) (3.1.0)\n",
            "Requirement already satisfied: ecos>=2 in /usr/local/lib/python3.7/dist-packages (from cvxpy<2.0.0,>=1.1.10->PyPortfolioOpt) (2.0.10)\n",
            "Requirement already satisfied: osqp>=0.4.1 in /usr/local/lib/python3.7/dist-packages (from cvxpy<2.0.0,>=1.1.10->PyPortfolioOpt) (0.6.2.post0)\n",
            "Requirement already satisfied: qdldl in /usr/local/lib/python3.7/dist-packages (from osqp>=0.4.1->cvxpy<2.0.0,>=1.1.10->PyPortfolioOpt) (0.1.5.post0)\n",
            "Installing collected packages: requests, lxml, cvxpy, yfinance, PyPortfolioOpt\n",
            "  Attempting uninstall: requests\n",
            "    Found existing installation: requests 2.23.0\n",
            "    Uninstalling requests-2.23.0:\n",
            "      Successfully uninstalled requests-2.23.0\n",
            "  Attempting uninstall: lxml\n",
            "    Found existing installation: lxml 4.2.6\n",
            "    Uninstalling lxml-4.2.6:\n",
            "      Successfully uninstalled lxml-4.2.6\n",
            "  Attempting uninstall: cvxpy\n",
            "    Found existing installation: cvxpy 1.0.31\n",
            "    Uninstalling cvxpy-1.0.31:\n",
            "      Successfully uninstalled cvxpy-1.0.31\n",
            "\u001b[31mERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.\n",
            "google-colab 1.0.0 requires requests~=2.23.0, but you have requests 2.27.1 which is incompatible.\n",
            "datascience 0.10.6 requires folium==0.2.1, but you have folium 0.8.3 which is incompatible.\u001b[0m\n",
            "Successfully installed PyPortfolioOpt-1.5.1 cvxpy-1.1.18 lxml-4.7.1 requests-2.27.1 yfinance-0.1.70\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 6,
      "metadata": {
        "id": "yd0GLGye_YO1"
      },
      "outputs": [],
      "source": [
        "import yfinance as yf\n",
        "import pandas as pd\n",
        "import numpy as np\n",
        "import matplotlib.pyplot as plt"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 7,
      "metadata": {
        "id": "HRko0Vbr_YO2"
      },
      "outputs": [],
      "source": [
        "tickers = [\"BLK\", \"BAC\", \"AAPL\", \"TM\", \"WMT\",\n",
        "           \"JD\", \"INTU\", \"MA\", \"UL\", \"CVS\",\n",
        "           \"DIS\", \"AMD\", \"NVDA\", \"PBI\", \"TGT\"]"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 8,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "b8QidoAw_YO2",
        "outputId": "cc6b4958-fa84-48d8-9a8a-3dd63d59d085"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "[*********************100%***********************]  15 of 15 completed\n"
          ]
        }
      ],
      "source": [
        "ohlc = yf.download(tickers, period=\"max\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 9,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 368
        },
        "id": "41-UTlPR_YO3",
        "outputId": "45e79da8-c066-4962-d5e2-57baafa8d68c"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/html": [
              "\n",
              "  <div id=\"df-3cf465d7-73b3-4487-bf3a-a90c0188319d\">\n",
              "    <div class=\"colab-df-container\">\n",
              "      <div>\n",
              "<style scoped>\n",
              "    .dataframe tbody tr th:only-of-type {\n",
              "        vertical-align: middle;\n",
              "    }\n",
              "\n",
              "    .dataframe tbody tr th {\n",
              "        vertical-align: top;\n",
              "    }\n",
              "\n",
              "    .dataframe thead th {\n",
              "        text-align: right;\n",
              "    }\n",
              "</style>\n",
              "<table border=\"1\" class=\"dataframe\">\n",
              "  <thead>\n",
              "    <tr style=\"text-align: right;\">\n",
              "      <th></th>\n",
              "      <th>AAPL</th>\n",
              "      <th>AMD</th>\n",
              "      <th>BAC</th>\n",
              "      <th>BLK</th>\n",
              "      <th>CVS</th>\n",
              "      <th>DIS</th>\n",
              "      <th>INTU</th>\n",
              "      <th>JD</th>\n",
              "      <th>MA</th>\n",
              "      <th>NVDA</th>\n",
              "      <th>PBI</th>\n",
              "      <th>TGT</th>\n",
              "      <th>TM</th>\n",
              "      <th>UL</th>\n",
              "      <th>WMT</th>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>Date</th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "      <th></th>\n",
              "    </tr>\n",
              "  </thead>\n",
              "  <tbody>\n",
              "    <tr>\n",
              "      <th>2022-02-07</th>\n",
              "      <td>171.660004</td>\n",
              "      <td>123.669998</td>\n",
              "      <td>48.509998</td>\n",
              "      <td>816.919983</td>\n",
              "      <td>109.410004</td>\n",
              "      <td>142.509995</td>\n",
              "      <td>545.280029</td>\n",
              "      <td>73.150002</td>\n",
              "      <td>376.130005</td>\n",
              "      <td>247.279999</td>\n",
              "      <td>4.81</td>\n",
              "      <td>211.289993</td>\n",
              "      <td>197.240005</td>\n",
              "      <td>52.250000</td>\n",
              "      <td>137.960007</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-08</th>\n",
              "      <td>174.830002</td>\n",
              "      <td>128.229996</td>\n",
              "      <td>49.380001</td>\n",
              "      <td>807.390015</td>\n",
              "      <td>110.830002</td>\n",
              "      <td>142.479996</td>\n",
              "      <td>554.229980</td>\n",
              "      <td>75.360001</td>\n",
              "      <td>374.369995</td>\n",
              "      <td>251.080002</td>\n",
              "      <td>5.04</td>\n",
              "      <td>212.949997</td>\n",
              "      <td>200.320007</td>\n",
              "      <td>52.299999</td>\n",
              "      <td>137.990005</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-09</th>\n",
              "      <td>176.279999</td>\n",
              "      <td>132.850006</td>\n",
              "      <td>49.279999</td>\n",
              "      <td>813.000000</td>\n",
              "      <td>104.790001</td>\n",
              "      <td>147.229996</td>\n",
              "      <td>579.400024</td>\n",
              "      <td>78.290001</td>\n",
              "      <td>381.369995</td>\n",
              "      <td>267.049988</td>\n",
              "      <td>5.10</td>\n",
              "      <td>216.639999</td>\n",
              "      <td>201.369995</td>\n",
              "      <td>52.139999</td>\n",
              "      <td>137.690002</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-10</th>\n",
              "      <td>172.119995</td>\n",
              "      <td>125.769997</td>\n",
              "      <td>49.049999</td>\n",
              "      <td>778.190002</td>\n",
              "      <td>105.320000</td>\n",
              "      <td>152.160004</td>\n",
              "      <td>557.580017</td>\n",
              "      <td>76.400002</td>\n",
              "      <td>374.390015</td>\n",
              "      <td>258.239990</td>\n",
              "      <td>4.94</td>\n",
              "      <td>213.839996</td>\n",
              "      <td>194.410004</td>\n",
              "      <td>51.220001</td>\n",
              "      <td>136.080002</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-11</th>\n",
              "      <td>168.639999</td>\n",
              "      <td>113.180000</td>\n",
              "      <td>47.919998</td>\n",
              "      <td>772.489990</td>\n",
              "      <td>104.239998</td>\n",
              "      <td>149.470001</td>\n",
              "      <td>535.809998</td>\n",
              "      <td>73.980003</td>\n",
              "      <td>369.769989</td>\n",
              "      <td>239.490005</td>\n",
              "      <td>4.91</td>\n",
              "      <td>211.559998</td>\n",
              "      <td>192.710007</td>\n",
              "      <td>52.730000</td>\n",
              "      <td>135.330002</td>\n",
              "    </tr>\n",
              "  </tbody>\n",
              "</table>\n",
              "</div>\n",
              "      <button class=\"colab-df-convert\" onclick=\"convertToInteractive('df-3cf465d7-73b3-4487-bf3a-a90c0188319d')\"\n",
              "              title=\"Convert this dataframe to an interactive table.\"\n",
              "              style=\"display:none;\">\n",
              "        \n",
              "  <svg xmlns=\"http://www.w3.org/2000/svg\" height=\"24px\"viewBox=\"0 0 24 24\"\n",
              "       width=\"24px\">\n",
              "    <path d=\"M0 0h24v24H0V0z\" fill=\"none\"/>\n",
              "    <path d=\"M18.56 5.44l.94 2.06.94-2.06 2.06-.94-2.06-.94-.94-2.06-.94 2.06-2.06.94zm-11 1L8.5 8.5l.94-2.06 2.06-.94-2.06-.94L8.5 2.5l-.94 2.06-2.06.94zm10 10l.94 2.06.94-2.06 2.06-.94-2.06-.94-.94-2.06-.94 2.06-2.06.94z\"/><path d=\"M17.41 7.96l-1.37-1.37c-.4-.4-.92-.59-1.43-.59-.52 0-1.04.2-1.43.59L10.3 9.45l-7.72 7.72c-.78.78-.78 2.05 0 2.83L4 21.41c.39.39.9.59 1.41.59.51 0 1.02-.2 1.41-.59l7.78-7.78 2.81-2.81c.8-.78.8-2.07 0-2.86zM5.41 20L4 18.59l7.72-7.72 1.47 1.35L5.41 20z\"/>\n",
              "  </svg>\n",
              "      </button>\n",
              "      \n",
              "  <style>\n",
              "    .colab-df-container {\n",
              "      display:flex;\n",
              "      flex-wrap:wrap;\n",
              "      gap: 12px;\n",
              "    }\n",
              "\n",
              "    .colab-df-convert {\n",
              "      background-color: #E8F0FE;\n",
              "      border: none;\n",
              "      border-radius: 50%;\n",
              "      cursor: pointer;\n",
              "      display: none;\n",
              "      fill: #1967D2;\n",
              "      height: 32px;\n",
              "      padding: 0 0 0 0;\n",
              "      width: 32px;\n",
              "    }\n",
              "\n",
              "    .colab-df-convert:hover {\n",
              "      background-color: #E2EBFA;\n",
              "      box-shadow: 0px 1px 2px rgba(60, 64, 67, 0.3), 0px 1px 3px 1px rgba(60, 64, 67, 0.15);\n",
              "      fill: #174EA6;\n",
              "    }\n",
              "\n",
              "    [theme=dark] .colab-df-convert {\n",
              "      background-color: #3B4455;\n",
              "      fill: #D2E3FC;\n",
              "    }\n",
              "\n",
              "    [theme=dark] .colab-df-convert:hover {\n",
              "      background-color: #434B5C;\n",
              "      box-shadow: 0px 1px 3px 1px rgba(0, 0, 0, 0.15);\n",
              "      filter: drop-shadow(0px 1px 2px rgba(0, 0, 0, 0.3));\n",
              "      fill: #FFFFFF;\n",
              "    }\n",
              "  </style>\n",
              "\n",
              "      <script>\n",
              "        const buttonEl =\n",
              "          document.querySelector('#df-3cf465d7-73b3-4487-bf3a-a90c0188319d button.colab-df-convert');\n",
              "        buttonEl.style.display =\n",
              "          google.colab.kernel.accessAllowed ? 'block' : 'none';\n",
              "\n",
              "        async function convertToInteractive(key) {\n",
              "          const element = document.querySelector('#df-3cf465d7-73b3-4487-bf3a-a90c0188319d');\n",
              "          const dataTable =\n",
              "            await google.colab.kernel.invokeFunction('convertToInteractive',\n",
              "                                                     [key], {});\n",
              "          if (!dataTable) return;\n",
              "\n",
              "          const docLinkHtml = 'Like what you see? Visit the ' +\n",
              "            '<a target=\"_blank\" href=https://colab.research.google.com/notebooks/data_table.ipynb>data table notebook</a>'\n",
              "            + ' to learn more about interactive tables.';\n",
              "          element.innerHTML = '';\n",
              "          dataTable['output_type'] = 'display_data';\n",
              "          await google.colab.output.renderOutput(dataTable, element);\n",
              "          const docLink = document.createElement('div');\n",
              "          docLink.innerHTML = docLinkHtml;\n",
              "          element.appendChild(docLink);\n",
              "        }\n",
              "      </script>\n",
              "    </div>\n",
              "  </div>\n",
              "  "
            ],
            "text/plain": [
              "                  AAPL         AMD  ...         UL         WMT\n",
              "Date                                ...                       \n",
              "2022-02-07  171.660004  123.669998  ...  52.250000  137.960007\n",
              "2022-02-08  174.830002  128.229996  ...  52.299999  137.990005\n",
              "2022-02-09  176.279999  132.850006  ...  52.139999  137.690002\n",
              "2022-02-10  172.119995  125.769997  ...  51.220001  136.080002\n",
              "2022-02-11  168.639999  113.180000  ...  52.730000  135.330002\n",
              "\n",
              "[5 rows x 15 columns]"
            ]
          },
          "metadata": {},
          "execution_count": 9
        }
      ],
      "source": [
        "prices = ohlc[\"Adj Close\"]\n",
        "prices.tail()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "8fZeMKRg_YO4"
      },
      "source": [
        "## Expected returns and risk models\n",
        "\n",
        "In this notebook, we will use James-Stein shrinkage and semicovariance (which only penalises downside risk)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 10,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 35
        },
        "id": "5_0F7H7k_YO4",
        "outputId": "973ab4df-85ba-45bc-a907-2be2ec28793c"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "application/vnd.google.colaboratory.intrinsic+json": {
              "type": "string"
            },
            "text/plain": [
              "'1.5.1'"
            ]
          },
          "metadata": {},
          "execution_count": 10
        }
      ],
      "source": [
        "import pypfopt\n",
        "pypfopt.__version__"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 11,
      "metadata": {
        "id": "U6m_oOBG_YO4"
      },
      "outputs": [],
      "source": [
        "from pypfopt import risk_models, expected_returns\n",
        "from pypfopt import plotting\n",
        "\n",
        "mu = expected_returns.capm_return(prices)\n",
        "S = risk_models.semicovariance(prices)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 12,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 320
        },
        "id": "V-3Q-NM__YO5",
        "outputId": "57e931b0-70d9-4cb7-c0e8-741fb86db943"
      },
      "outputs": [
        {
          "output_type": "display_data",
          "data": {
            "image/png": "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\n",
            "text/plain": [
              "<Figure size 720x360 with 1 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          }
        }
      ],
      "source": [
        "mu.plot.barh(figsize=(10,5));"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 13,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 297
        },
        "id": "pgEDbNJ7_YO5",
        "outputId": "ac4edb81-60a7-48dc-ea68-02926985e564"
      },
      "outputs": [
        {
          "output_type": "display_data",
          "data": {
            "image/png": "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\n",
            "text/plain": [
              "<Figure size 432x288 with 2 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          }
        }
      ],
      "source": [
        "plotting.plot_covariance(S, plot_correlation=True);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "8V6jyzsw_YO5"
      },
      "source": [
        "## Min volatility with a transaction cost objective\n",
        "\n",
        "Let's say that you already have a portfolio, and want to now optimize it. It could be quite expensive to completely reallocate, so you may want to take into account transaction costs. PyPortfolioOpt provides a simple objective to account for this.\n",
        "\n",
        "Note: this objective will not play nicely with `max_sharpe`."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 14,
      "metadata": {
        "id": "70ib0FwA_YO5"
      },
      "outputs": [],
      "source": [
        "# Pretend that you started with a default-weight allocation\n",
        "initial_weights = np.array([1/len(tickers)] * len(tickers))"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 15,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "h4DCRaLe_YO6",
        "outputId": "bab1cd04-1fb4-4d87-d784-ec3006753ba3"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.02823),\n",
              "             ('AMD', 0.0),\n",
              "             ('BAC', 0.01232),\n",
              "             ('BLK', 0.06667),\n",
              "             ('CVS', 0.06667),\n",
              "             ('DIS', 0.06667),\n",
              "             ('INTU', 0.06667),\n",
              "             ('JD', 0.23445),\n",
              "             ('MA', 0.06667),\n",
              "             ('NVDA', 0.05833),\n",
              "             ('PBI', 0.06667),\n",
              "             ('TGT', 0.06667),\n",
              "             ('TM', 0.06667),\n",
              "             ('UL', 0.06667),\n",
              "             ('WMT', 0.06667)])"
            ]
          },
          "metadata": {},
          "execution_count": 15
        }
      ],
      "source": [
        "from pypfopt import EfficientFrontier, objective_functions\n",
        "\n",
        "ef = EfficientFrontier(mu, S)\n",
        "\n",
        "# 1% broker commission\n",
        "ef.add_objective(objective_functions.transaction_cost, w_prev=initial_weights, k=0.01)\n",
        "ef.min_volatility()\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "iTTvy6xH_YO6"
      },
      "source": [
        "Notice that many of the weights are 0.06667, i.e your original equal weight. In fact, the only change has been an allocation of AMD's weight to JD. If we lower the cost `k`, the allocation will change more:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 16,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "pTepg1-Q_YO6",
        "outputId": "335af198-0d41-482c-a923-617240ee5ffd"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.0),\n",
              "             ('AMD', 0.0),\n",
              "             ('BAC', 0.0),\n",
              "             ('BLK', 0.06667),\n",
              "             ('CVS', 0.04699),\n",
              "             ('DIS', 0.0),\n",
              "             ('INTU', 0.01458),\n",
              "             ('JD', 0.4362),\n",
              "             ('MA', 0.19541),\n",
              "             ('NVDA', 0.0),\n",
              "             ('PBI', 0.0),\n",
              "             ('TGT', 0.00327),\n",
              "             ('TM', 0.06667),\n",
              "             ('UL', 0.10354),\n",
              "             ('WMT', 0.06667)])"
            ]
          },
          "metadata": {},
          "execution_count": 16
        }
      ],
      "source": [
        "ef = EfficientFrontier(mu, S)\n",
        "ef.add_objective(objective_functions.transaction_cost, w_prev=initial_weights, k=0.001)\n",
        "ef.min_volatility()\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "YM-gPp1S_YO7"
      },
      "source": [
        "The optimizer seems to really like JD. The reason for this is that it is highly anticorrelated to other assets (notice the dark column in the covariance plot). Hence, historically, it adds a lot of diversification. But it is dangerous to place too much emphasis on what happened in the past, so we may want to limit the asset weights. \n",
        "\n",
        "In addition, we notice that 4 stocks have now been allocated zero weight, which may be undesirable. Both of these problems can be fixed by adding an [L2 regularisation objective](https://pyportfolioopt.readthedocs.io/en/latest/EfficientFrontier.html#more-on-l2-regularisation). "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 17,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "Mh22zJrI_YO7",
        "outputId": "f6b4707d-c5cb-4c81-d676-7f1cc9c412e5"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.06191),\n",
              "             ('AMD', 0.0538),\n",
              "             ('BAC', 0.06219),\n",
              "             ('BLK', 0.0704),\n",
              "             ('CVS', 0.06684),\n",
              "             ('DIS', 0.06516),\n",
              "             ('INTU', 0.06667),\n",
              "             ('JD', 0.0771),\n",
              "             ('MA', 0.0733),\n",
              "             ('NVDA', 0.06381),\n",
              "             ('PBI', 0.0648),\n",
              "             ('TGT', 0.06603),\n",
              "             ('TM', 0.06915),\n",
              "             ('UL', 0.0708),\n",
              "             ('WMT', 0.06804)])"
            ]
          },
          "metadata": {},
          "execution_count": 17
        }
      ],
      "source": [
        "ef = EfficientFrontier(mu, S)\n",
        "ef.add_objective(objective_functions.transaction_cost, w_prev=initial_weights, k=0.001)\n",
        "ef.add_objective(objective_functions.L2_reg)\n",
        "ef.min_volatility()\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "zQrFckqY_YO7"
      },
      "source": [
        "This has had too much of an evening-out effect. After all, if the resulting allocation is going to be so close to equal weights, we may as well stick with our initial allocation. We can reduce the strength of the L2 regularisation by reducing `gamma`:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 18,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "VdeeHz8J_YO7",
        "outputId": "735a86d3-078e-4a28-cb2e-19da01de4542"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.02011),\n",
              "             ('AMD', 0.0),\n",
              "             ('BAC', 0.00851),\n",
              "             ('BLK', 0.09644),\n",
              "             ('CVS', 0.06667),\n",
              "             ('DIS', 0.04351),\n",
              "             ('INTU', 0.06058),\n",
              "             ('JD', 0.18765),\n",
              "             ('MA', 0.1367),\n",
              "             ('NVDA', 0.02831),\n",
              "             ('PBI', 0.03699),\n",
              "             ('TGT', 0.05195),\n",
              "             ('TM', 0.08463),\n",
              "             ('UL', 0.10431),\n",
              "             ('WMT', 0.07363)])"
            ]
          },
          "metadata": {},
          "execution_count": 18
        }
      ],
      "source": [
        "ef = EfficientFrontier(mu, S)\n",
        "ef.add_objective(objective_functions.transaction_cost, w_prev=initial_weights, k=0.001)\n",
        "ef.add_objective(objective_functions.L2_reg, gamma=0.05)  # default is 1\n",
        "ef.min_volatility()\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 19,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "EFN7ul8-_YO8",
        "outputId": "575da3e2-c1ed-4821-dbec-8475d1f0c3b7"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Expected annual return: 17.7%\n",
            "Annual volatility: 9.6%\n",
            "Sharpe Ratio: 1.64\n"
          ]
        }
      ],
      "source": [
        "ef.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ra5fBWi8_YO8"
      },
      "source": [
        "This portfolio is now reasonably balanced, but also puts significantly more weight on JD. "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 20,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 575
        },
        "id": "3Klc-L_8_YO8",
        "outputId": "9bc2e6e6-9411-4be4-a851-918a648b5306"
      },
      "outputs": [
        {
          "output_type": "display_data",
          "data": {
            "image/png": "iVBORw0KGgoAAAANSUhEUgAAAjsAAAIuCAYAAABZzclzAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADh0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uMy4yLjIsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy+WH4yJAAAgAElEQVR4nOzdeZhcV30m/vd7z62t933RYkmWrd2yFsvyhjdABBNjjE0FyELIJISaZBImHYWEzCRMT5YhDmT/hcGsSX5AEUwwTTKJSBgLbMDYrV2yZFlba+99X6vqzB9VbbekXqqqq+rce+v9PE8/kmq59xXIXW+fe+45orUGERERkVdZpgMQERER5RPLDhEREXkayw4RERF5GssOEREReRrLDhEREXkayw4RERF5GssOEREReRrLDhEREXkayw4RERF5GssOEREReRrLDhEREXkayw4RERF5GssOEREReRrLDhEREXkayw4RERF5GssOEREReRrLDhEREXkayw4RERF5GssOEREReRrLDhEREXkayw4RERF5GssOEREReRrLDhEREXkayw4RERF5GssOEREReRrLDhEREXkayw4RERF5GssOEREReRrLDhEREXkayw4RERF5GssOEREReRrLDhEREXkayw4RERF5GssOEREReRrLDhEREXkayw6RR4nIcOrXlSKiReS/zHjur0Xk50Xkb0TkgIgcE5Gx1O8PiMiTIvKciNwx4z0rReSIib8LEdFisOwQFYdOAL8uIv6ZD2qtf0VrvQXAIwBOaa23pL6+biQlEVEesOwQFYcuAP8B4AOmgxARFRrLDlHx+ASA3xQRZToIEVEhsewQFQmt9WkALwJ4f7pvSfMxIiJHY9khKi5/BOCjACSN1/YAqJ7x5xoA3fkIVSxEJJ6aAH5URA6KSIuIWKnnHhSRb6d+3ygi30695piI/IvZ5ETuxrJDVES01scBHAPwaBovfw7Az4jIdDH6AID/m6doxWIsNQF8I4C3Ang7gN+f5XWtAL6jtb5da70BwG8XMiSR17DsEBWfPwSwLI3XfQbAEICDInIQQBmAP81nsGKite4E8CEAvzqjUE5rBnBhxmsPFTIbkdeI1rwET0RUCCIyrLUuu+6xfgBrAawH8Jta658UkbcBiALYD+DfAXxBa32p4IGJPIIjO0REDqO1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\n",
            "text/plain": [
              "<Figure size 720x720 with 1 Axes>"
            ]
          },
          "metadata": {}
        }
      ],
      "source": [
        "pd.Series(weights).plot.pie(figsize=(10,10));"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "A4s-3rWa_YO9"
      },
      "source": [
        "## Custom convex objectives\n",
        "\n",
        "PyPortfolioOpt comes with the following built-in objective functions, as of v1.2.1:\n",
        "\n",
        "- Portfolio variance (i.e square of volatility)\n",
        "- Portfolio return\n",
        "- Sharpe ratio\n",
        "- L2 regularisation (minimising this reduces nonzero weights)\n",
        "- Quadratic utility\n",
        "- Transaction cost model (a simple one)\n",
        "\n",
        "However, you may want have a different objective. If this new objective is **convex**, you can optimize a portfolio with the full benefit of PyPortfolioOpt's modular syntax, for example adding other constraints and objectives.\n",
        "\n",
        "To demonstrate this, we will minimise the **logarithmic-barrier** function suggested in the paper 60 Years of Portfolio Optimization, by Kolm et al (2014):\n",
        "\n",
        "$$f(w, S, k) = w^T S w - k \\sum_{i=1}^N \\ln w$$\n",
        "\n",
        "We must first convert this mathematical objective into the language of cvxpy. Cvxpy is a powerful modelling language for convex optimization problems. It is clean and easy to use, the only caveat is that objectives must be expressed with `cvxpy` functions, a list of which can be found [here](https://www.cvxpy.org/tutorial/functions/index.html)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 21,
      "metadata": {
        "id": "5WjglE6d_YO9"
      },
      "outputs": [],
      "source": [
        "import cvxpy as cp\n",
        "\n",
        "# Note: functions are minimised. If you want to maximise an objective, stick a minus sign in it.\n",
        "def logarithmic_barrier_objective(w, cov_matrix, k=0.1):\n",
        "    log_sum = cp.sum(cp.log(w))\n",
        "    var = cp.quad_form(w, cov_matrix)\n",
        "    return var - k * log_sum"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "UxmNQahn_YO9"
      },
      "source": [
        "Once we have written the objective function, we can just use the `ef.convex_objective()` to minimise the objective."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 22,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "SMsaFWHB_YO9",
        "outputId": "5a25c217-5d8b-4185-89de-a7379a5ef5fe"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.03845),\n",
              "             ('AMD', 0.02609),\n",
              "             ('BAC', 0.0376),\n",
              "             ('BLK', 0.07672),\n",
              "             ('CVS', 0.05664),\n",
              "             ('DIS', 0.04637),\n",
              "             ('INTU', 0.05215),\n",
              "             ('JD', 0.2),\n",
              "             ('MA', 0.11405),\n",
              "             ('NVDA', 0.04123),\n",
              "             ('PBI', 0.04431),\n",
              "             ('TGT', 0.04933),\n",
              "             ('TM', 0.06961),\n",
              "             ('UL', 0.08328),\n",
              "             ('WMT', 0.06417)])"
            ]
          },
          "metadata": {},
          "execution_count": 22
        }
      ],
      "source": [
        "ef = EfficientFrontier(mu, S, weight_bounds=(0.01, 0.2))\n",
        "ef.convex_objective(logarithmic_barrier_objective, cov_matrix=S, k=0.001)\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 23,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "TGkjjU3z_YO-",
        "outputId": "d8e09c26-503d-4ac6-e57b-f81af6456544"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Expected annual return: 18.5%\n",
            "Annual volatility: 10.2%\n",
            "Sharpe Ratio: 1.62\n"
          ]
        }
      ],
      "source": [
        "ef.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "mOAd1ncH_YO-"
      },
      "source": [
        "This is compatible with all the constraints discussed in the previous recipe. Let's say that we want to limit JD's weight to 15%."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 24,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "J3rM2vkz_YO-",
        "outputId": "b00c2c60-47c5-419d-97d1-52957b32a56c"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.03938),\n",
              "             ('AMD', 0.02634),\n",
              "             ('BAC', 0.03819),\n",
              "             ('BLK', 0.08264),\n",
              "             ('CVS', 0.05924),\n",
              "             ('DIS', 0.04784),\n",
              "             ('INTU', 0.05447),\n",
              "             ('JD', 0.15),\n",
              "             ('MA', 0.13048),\n",
              "             ('NVDA', 0.04262),\n",
              "             ('PBI', 0.04594),\n",
              "             ('TGT', 0.05102),\n",
              "             ('TM', 0.07402),\n",
              "             ('UL', 0.09008),\n",
              "             ('WMT', 0.06773)])"
            ]
          },
          "metadata": {},
          "execution_count": 24
        }
      ],
      "source": [
        "ef = EfficientFrontier(mu, S, weight_bounds=(0.01, 0.2))\n",
        "jd_index = ef.tickers.index(\"JD\")  # get the index of JD\n",
        "ef.add_constraint(lambda w: w[jd_index] <= 0.15)\n",
        "ef.convex_objective(logarithmic_barrier_objective, cov_matrix=S, k=0.001)\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "v-ObCWVv_YO-"
      },
      "source": [
        "## Custom nonconvex objectives\n",
        "\n",
        "In some cases, you may be trying to optimize for nonconvex objectives. Optimization in general is a very hard problem, so please be aware that you may have mixed results in that case. Convex problems, on the other hand, are well understood and can be solved with nice theoretical guarantees.\n",
        "\n",
        "PyPortfolioOpt does offer some functionality for nonconvex optimization, but it is not really encouraged. In particular, nonconvex optimization is not compatible with PyPortfolioOpt's modular constraints API.\n",
        "\n",
        "As an example, we will use the Deviation Risk Parity objective from Kolm et al (2014). Because we are not using a convex solver, we don't have to define it using `cvxpy` functions."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 25,
      "metadata": {
        "id": "WYIshUU__YO-"
      },
      "outputs": [],
      "source": [
        "def deviation_risk_parity(w, cov_matrix):\n",
        "    diff = w * np.dot(cov_matrix, w) - (w * np.dot(cov_matrix, w)).reshape(-1, 1)\n",
        "    return (diff ** 2).sum().sum()"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 26,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "_fgoI8gj_YO-",
        "outputId": "a3f3c341-503e-4b7a-ef96-8bdf462c6d8a"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.0558),\n",
              "             ('AMD', 0.02641),\n",
              "             ('BAC', 0.05807),\n",
              "             ('BLK', 0.07668),\n",
              "             ('CVS', 0.07138),\n",
              "             ('DIS', 0.06556),\n",
              "             ('INTU', 0.06944),\n",
              "             ('JD', 0.07842),\n",
              "             ('MA', 0.07869),\n",
              "             ('NVDA', 0.06197),\n",
              "             ('PBI', 0.06493),\n",
              "             ('TGT', 0.06762),\n",
              "             ('TM', 0.07491),\n",
              "             ('UL', 0.0769),\n",
              "             ('WMT', 0.07323)])"
            ]
          },
          "metadata": {},
          "execution_count": 26
        }
      ],
      "source": [
        "ef = EfficientFrontier(mu, S, weight_bounds=(0.01, 0.12))\n",
        "ef.nonconvex_objective(deviation_risk_parity, ef.cov_matrix)\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "1JJVTSOb_YO_"
      },
      "source": [
        "However, let's say we now want to enforce that JD has a weight of 10%. In the convex case, this would be as simple as:\n",
        "\n",
        "```python\n",
        "ef.add_objective(lambda w: w[jd_index] == 0.10)\n",
        "```\n",
        "\n",
        "But unfortunately, scipy does not allow for such intuitive syntax. You will need to rearrange your constraints to make them either `=0` or `<= 0`. \n",
        "\n",
        "```python\n",
        "constraints = [\n",
        "    # First constraint\n",
        "     {\"type\": \"eq\",  # equality constraint,\n",
        "      \"fun\": lambda w: w[1] - 0.2},  # the equality functions are assumed to = 0 \n",
        "      \n",
        "    # Second constraint\n",
        "    {\"type\": \"ineq\",  # inequality constraint\n",
        "     \"fun\": lambda w: w[0] - 0.5}   # inequality functions <= 0\n",
        "]\n",
        "```\n",
        "\n",
        "For more information, you can consult the [scipy docs](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html), but they aren't very helpful."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 27,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "84sElIfw_YO_",
        "outputId": "f4e9713d-2215-4093-9900-17a2035c5906"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.05576),\n",
              "             ('AMD', 0.02999),\n",
              "             ('BAC', 0.05776),\n",
              "             ('BLK', 0.07353),\n",
              "             ('CVS', 0.06915),\n",
              "             ('DIS', 0.06421),\n",
              "             ('INTU', 0.06745),\n",
              "             ('JD', 0.1),\n",
              "             ('MA', 0.07516),\n",
              "             ('NVDA', 0.06094),\n",
              "             ('PBI', 0.06357),\n",
              "             ('TGT', 0.06597),\n",
              "             ('TM', 0.07208),\n",
              "             ('UL', 0.07373),\n",
              "             ('WMT', 0.07071)])"
            ]
          },
          "metadata": {},
          "execution_count": 27
        }
      ],
      "source": [
        "ef = EfficientFrontier(mu, S, weight_bounds=(0.01, 0.12))\n",
        "\n",
        "ef.nonconvex_objective(\n",
        "    deviation_risk_parity,\n",
        "    objective_args=S,\n",
        "    weights_sum_to_one=True,\n",
        "    constraints=[\n",
        "        {\"type\": \"eq\", \"fun\": lambda w: w[jd_index] - 0.10},  \n",
        "    ],\n",
        ")\n",
        "\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "0SoIPcj2_YO_"
      },
      "source": [
        "## More examples of nonconvex objectives\n",
        "\n",
        "The scipy format is not intuitive and is hard to explain, so here are a bunch of examples (adapted from the tests). Some of these are actually convex, so you should use `convex_objective` instead. "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 28,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "vfzCiKQT_YO_",
        "outputId": "a6413d3f-22d7-4406-9904-c480be20bd53"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.04432),\n",
              "             ('AMD', 0.03205),\n",
              "             ('BAC', 0.0439),\n",
              "             ('BLK', 0.07685),\n",
              "             ('CVS', 0.06049),\n",
              "             ('DIS', 0.05166),\n",
              "             ('INTU', 0.05695),\n",
              "             ('JD', 0.16311),\n",
              "             ('MA', 0.10119),\n",
              "             ('NVDA', 0.04752),\n",
              "             ('PBI', 0.05026),\n",
              "             ('TGT', 0.05434),\n",
              "             ('TM', 0.07063),\n",
              "             ('UL', 0.08069),\n",
              "             ('WMT', 0.06605)])"
            ]
          },
          "metadata": {},
          "execution_count": 28
        }
      ],
      "source": [
        "# Another example of deviation risk parity\n",
        "def deviation_risk_parity(w, cov_matrix):\n",
        "    n = cov_matrix.shape[0]\n",
        "    rp = (w * (cov_matrix @ w)) / cp.quad_form(w, cov_matrix)\n",
        "    return cp.sum_squares(rp - 1 / n).value\n",
        "\n",
        "ef = EfficientFrontier(mu, S)\n",
        "ef.nonconvex_objective(deviation_risk_parity, ef.cov_matrix)\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 29,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "P2jqcyK7_YO_",
        "outputId": "59979140-7fd0-41cc-fb52-8b12586b2066"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.1),\n",
              "             ('AMD', 0.03371),\n",
              "             ('BAC', 0.04774),\n",
              "             ('BLK', 0.07578),\n",
              "             ('CVS', 0.06051),\n",
              "             ('DIS', 0.05414),\n",
              "             ('INTU', 0.05662),\n",
              "             ('JD', 0.11429),\n",
              "             ('MA', 0.09186),\n",
              "             ('NVDA', 0.04985),\n",
              "             ('PBI', 0.05315),\n",
              "             ('TGT', 0.05564),\n",
              "             ('TM', 0.06813),\n",
              "             ('UL', 0.07496),\n",
              "             ('WMT', 0.06363)])"
            ]
          },
          "metadata": {},
          "execution_count": 29
        }
      ],
      "source": [
        "# Deviation risk parity with weight bound on the first asset\n",
        "ef = EfficientFrontier(mu, S)\n",
        "ef.nonconvex_objective(deviation_risk_parity, \n",
        "                       ef.cov_matrix, \n",
        "                       constraints=[{\"type\":\"eq\", \"fun\":lambda w: w[0] - 0.1}])\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 30,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "voar0fB2_YPA",
        "outputId": "2721f2ad-7b9f-4a8a-967a-48921b88e853"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.09646),\n",
              "             ('AMD', 0.16657),\n",
              "             ('BAC', 0.01497),\n",
              "             ('BLK', -0.09881),\n",
              "             ('CVS', -0.17057),\n",
              "             ('DIS', 0.21792),\n",
              "             ('INTU', 0.11454),\n",
              "             ('JD', 0.14593),\n",
              "             ('MA', 0.59801),\n",
              "             ('NVDA', 0.42335),\n",
              "             ('PBI', -0.03505),\n",
              "             ('TGT', 0.00214),\n",
              "             ('TM', -0.47931),\n",
              "             ('UL', -0.8376),\n",
              "             ('WMT', -0.15855)])"
            ]
          },
          "metadata": {},
          "execution_count": 30
        }
      ],
      "source": [
        "# Market-neutral efficient risk.\n",
        "# Please use ef.efficient_risk() for anything serious.\n",
        "target_risk = 0.19\n",
        "ef = EfficientFrontier(mu, S, weight_bounds=(None, None))\n",
        "\n",
        "# Weights sum to zero\n",
        "weight_constr = {\"type\": \"eq\", \"fun\": lambda w: np.sum(w)}\n",
        "\n",
        "# Portfolio vol less than target vol\n",
        "risk_constr = {\n",
        "    \"type\": \"eq\",\n",
        "    \"fun\": lambda w: target_risk ** 2 - np.dot(w.T, np.dot(ef.cov_matrix, w)),\n",
        "}\n",
        "constraints = [weight_constr, risk_constr]\n",
        "\n",
        "ef.nonconvex_objective(\n",
        "    lambda w, mu: -w.T.dot(mu),  # min negative return i.e max return\n",
        "    objective_args=(ef.expected_returns),\n",
        "    weights_sum_to_one=False,\n",
        "    constraints=constraints,\n",
        ")\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 31,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "2kgcF-V9_YPH",
        "outputId": "862dc21d-2005-438b-eb0d-3ebe2d7e0222"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.0),\n",
              "             ('AMD', 0.06009),\n",
              "             ('BAC', 0.0),\n",
              "             ('BLK', 0.0),\n",
              "             ('CVS', 0.0),\n",
              "             ('DIS', 0.0),\n",
              "             ('INTU', 0.0),\n",
              "             ('JD', 0.0),\n",
              "             ('MA', 0.0),\n",
              "             ('NVDA', 0.93991),\n",
              "             ('PBI', 0.0),\n",
              "             ('TGT', 0.0),\n",
              "             ('TM', 0.0),\n",
              "             ('UL', 0.0),\n",
              "             ('WMT', 0.0)])"
            ]
          },
          "metadata": {},
          "execution_count": 31
        }
      ],
      "source": [
        "# Utility objective - you could actually use ef.max_quadratic_utility\n",
        "ef = EfficientFrontier(mu, S)\n",
        "\n",
        "def utility_obj(weights, mu, cov_matrix, k=1):\n",
        "    return -weights.dot(mu) + k * np.dot(weights.T, np.dot(cov_matrix, weights))\n",
        "\n",
        "ef.nonconvex_objective(\n",
        "    utility_obj,\n",
        "    objective_args=(ef.expected_returns, ef.cov_matrix, 1)\n",
        "    # default is for weights to sum to 1\n",
        ")\n",
        "\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 32,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "LnNkM5DJ_YPH",
        "outputId": "874299e2-37a8-4783-9f8e-7608ff293837"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "1.0000000000000004"
            ]
          },
          "metadata": {},
          "execution_count": 32
        }
      ],
      "source": [
        "ef.weights.sum()"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 33,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "FSFhcUz7_YPH",
        "outputId": "0a086117-7335-4558-aaee-c7c70c295f90"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "OrderedDict([('AAPL', 0.06667),\n",
              "             ('AMD', 0.06667),\n",
              "             ('BAC', 0.06667),\n",
              "             ('BLK', 0.06667),\n",
              "             ('CVS', 0.06667),\n",
              "             ('DIS', 0.06667),\n",
              "             ('INTU', 0.06667),\n",
              "             ('JD', 0.06667),\n",
              "             ('MA', 0.06667),\n",
              "             ('NVDA', 0.06667),\n",
              "             ('PBI', 0.06667),\n",
              "             ('TGT', 0.06667),\n",
              "             ('TM', 0.06667),\n",
              "             ('UL', 0.06667),\n",
              "             ('WMT', 0.06667)])"
            ]
          },
          "metadata": {},
          "execution_count": 33
        }
      ],
      "source": [
        "# Kelly objective with weight bounds on zeroth asset\n",
        "def kelly_objective(w, e_returns, cov_matrix, k=3):\n",
        "    variance = np.dot(w.T, np.dot(cov_matrix, w))\n",
        "    objective = variance * 0.5 * k - np.dot(w, e_returns)\n",
        "    return objective\n",
        "\n",
        "lower_bounds, upper_bounds = 0.01, 0.3\n",
        "ef = EfficientFrontier(mu, S)\n",
        "ef.nonconvex_objective(\n",
        "    kelly_objective,\n",
        "    objective_args=(ef.expected_returns, ef.cov_matrix, 1000),\n",
        "    constraints=[\n",
        "        {\"type\": \"eq\", \"fun\": lambda w: np.sum(w) - 1},\n",
        "        {\"type\": \"ineq\", \"fun\": lambda w: w[0] - lower_bounds},\n",
        "        {\"type\": \"ineq\", \"fun\": lambda w: upper_bounds - w[0]},\n",
        "    ],\n",
        ")\n",
        "\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 33,
      "metadata": {
        "id": "IP6os0tS_YPI"
      },
      "outputs": [],
      "source": [
        ""
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    },
    "language_info": {
      "name": "python"
    },
    "colab": {
      "name": "3-Advanced-Mean-Variance-Optimisation.ipynb",
      "provenance": [],
      "collapsed_sections": []
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}