cookbook/2-Mean-Variance-Optimisation.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "UL9EB0Mn9ny5"
      },
      "source": [
        "# Mean-variance optimization\n",
        "\n",
        "In this cookbook recipe, we work on several examples demonstrating PyPortfolioOpt's mean-variance capabilities. I will discuss what I think should be your \"default\" options, based on my experience in optimising portfolios.\n",
        "\n",
        "To start, you need a list of tickers. Some people just provide the whole universe of stocks, but I don't think this is a good idea - portfolio optimization is quite different from asset selection. I would suggest anywhere from 10-50 stocks as a starting point.\n",
        "\n",
        "Some of the things we cover:\n",
        "\n",
        "- Downloading data and getting it into PyPortfolioOpt\n",
        "- Calculating and visualising the covariance matrix\n",
        "- Optimising a long/short portfolio to minimise total variance\n",
        "- Optimising a portfolio to maximise the Sharpe ratio, subject to sector constraints\n",
        "- Optimising a portfolio to maximise return for a given risk, subject to sector constraints, with an L2 regularisation objective\n",
        "- Optimising a market-neutral portfolio to minimise risk for a given level of return\n",
        "- Optimising along the mean-semivariance frontier\n",
        "- Optimising along the mean-CVaR frontier\n",
        "- Plotting the efficient frontier:\n",
        "    - Simple (using CLA)\n",
        "    - Constrained\n",
        "    - Complex plots\n",
        "\n",
        "Please consult the [docs](https://pyportfolioopt.readthedocs.io/) for more info.\n",
        "\n",
        "## Downloading data\n",
        "\n",
        "To download data, we will use `yfinance`, an excellent library that provides free price data from Yahoo Finance, no API key needed.\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/2-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/2-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/2-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/2-Mean-Variance-Optimisation.ipynb)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 56,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "69vaYVwZ-Cxz",
        "outputId": "dee1bf4a-82ee-4909-e26b-217899258cf2"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "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",
            "Requirement already satisfied: yfinance in /usr/local/lib/python3.7/dist-packages (0.1.70)\n",
            "Requirement already satisfied: PyPortfolioOpt in /usr/local/lib/python3.7/dist-packages (1.5.1)\n",
            "Requirement 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: 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: kiwisolver>=1.0.1 in /usr/local/lib/python3.7/dist-packages (from matplotlib) (1.3.2)\n",
            "Requirement already satisfied: multitasking>=0.0.7 in /usr/local/lib/python3.7/dist-packages (from yfinance) (0.0.10)\n",
            "Requirement already satisfied: requests>=2.26 in /usr/local/lib/python3.7/dist-packages (from yfinance) (2.27.1)\n",
            "Requirement already satisfied: lxml>=4.5.1 in /usr/local/lib/python3.7/dist-packages (from yfinance) (4.7.1)\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: idna<4,>=2.5 in /usr/local/lib/python3.7/dist-packages (from requests>=2.26->yfinance) (2.10)\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: 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: cvxpy<2.0.0,>=1.1.10 in /usr/local/lib/python3.7/dist-packages (from PyPortfolioOpt) (1.1.18)\n",
            "Requirement already satisfied: scipy<2.0,>=1.3 in /usr/local/lib/python3.7/dist-packages (from PyPortfolioOpt) (1.4.1)\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: 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: 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"
          ]
        }
      ],
      "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')"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 57,
      "metadata": {
        "id": "shuJGGeo9ny8"
      },
      "outputs": [],
      "source": [
        "import yfinance as yf\n",
        "import matplotlib.pyplot as plt\n",
        "import pandas as pd\n",
        "import numpy as np"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 58,
      "metadata": {
        "id": "c4r8LJdC9ny8"
      },
      "outputs": [],
      "source": [
        "tickers = [\"MSFT\", \"AMZN\", \"KO\", \"MA\", \"COST\", \n",
        "           \"LUV\", \"XOM\", \"PFE\", \"JPM\", \"UNH\", \n",
        "           \"ACN\", \"DIS\", \"GILD\", \"F\", \"TSLA\"] "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 59,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "XWdfXpB69ny9",
        "outputId": "e60980bf-21e3-470f-a4f7-99da82c820a4"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "[*********************100%***********************]  15 of 15 completed\n"
          ]
        }
      ],
      "source": [
        "ohlc = yf.download(tickers, period=\"max\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 60,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 388
        },
        "id": "S7voZG_T9ny-",
        "outputId": "de26041a-af6d-4554-eb32-1eb9d57d5f3e"
      },
      "outputs": [
        {
          "data": {
            "text/html": [
              "\n",
              "  <div id=\"df-9efe243a-89c2-4ee1-869c-875d2347a211\">\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>ACN</th>\n",
              "      <th>AMZN</th>\n",
              "      <th>COST</th>\n",
              "      <th>DIS</th>\n",
              "      <th>F</th>\n",
              "      <th>GILD</th>\n",
              "      <th>JPM</th>\n",
              "      <th>KO</th>\n",
              "      <th>LUV</th>\n",
              "      <th>MA</th>\n",
              "      <th>MSFT</th>\n",
              "      <th>PFE</th>\n",
              "      <th>TSLA</th>\n",
              "      <th>UNH</th>\n",
              "      <th>XOM</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>343.959991</td>\n",
              "      <td>3158.709961</td>\n",
              "      <td>515.890015</td>\n",
              "      <td>142.509995</td>\n",
              "      <td>17.889999</td>\n",
              "      <td>63.759998</td>\n",
              "      <td>153.070007</td>\n",
              "      <td>61.599998</td>\n",
              "      <td>44.599998</td>\n",
              "      <td>376.130005</td>\n",
              "      <td>300.950012</td>\n",
              "      <td>53.209999</td>\n",
              "      <td>907.340027</td>\n",
              "      <td>483.700012</td>\n",
              "      <td>81.486641</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-08</th>\n",
              "      <td>345.070007</td>\n",
              "      <td>3228.270020</td>\n",
              "      <td>521.150024</td>\n",
              "      <td>142.479996</td>\n",
              "      <td>17.719999</td>\n",
              "      <td>63.700001</td>\n",
              "      <td>155.949997</td>\n",
              "      <td>62.000000</td>\n",
              "      <td>46.070000</td>\n",
              "      <td>374.369995</td>\n",
              "      <td>304.559998</td>\n",
              "      <td>51.700001</td>\n",
              "      <td>922.000000</td>\n",
              "      <td>493.410004</td>\n",
              "      <td>79.379997</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-09</th>\n",
              "      <td>355.529999</td>\n",
              "      <td>3223.790039</td>\n",
              "      <td>528.830017</td>\n",
              "      <td>147.229996</td>\n",
              "      <td>18.350000</td>\n",
              "      <td>63.380001</td>\n",
              "      <td>156.600006</td>\n",
              "      <td>61.040001</td>\n",
              "      <td>47.020000</td>\n",
              "      <td>381.369995</td>\n",
              "      <td>311.209991</td>\n",
              "      <td>51.470001</td>\n",
              "      <td>932.000000</td>\n",
              "      <td>498.100006</td>\n",
              "      <td>79.000000</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-10</th>\n",
              "      <td>342.390015</td>\n",
              "      <td>3180.070068</td>\n",
              "      <td>518.479980</td>\n",
              "      <td>152.160004</td>\n",
              "      <td>18.080000</td>\n",
              "      <td>61.790001</td>\n",
              "      <td>155.949997</td>\n",
              "      <td>61.380001</td>\n",
              "      <td>46.529999</td>\n",
              "      <td>374.390015</td>\n",
              "      <td>302.380005</td>\n",
              "      <td>50.599998</td>\n",
              "      <td>904.549988</td>\n",
              "      <td>486.720001</td>\n",
              "      <td>78.239998</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-11</th>\n",
              "      <td>329.179993</td>\n",
              "      <td>3065.870117</td>\n",
              "      <td>509.670013</td>\n",
              "      <td>149.470001</td>\n",
              "      <td>17.549999</td>\n",
              "      <td>62.070000</td>\n",
              "      <td>153.919998</td>\n",
              "      <td>60.290001</td>\n",
              "      <td>45.529999</td>\n",
              "      <td>369.769989</td>\n",
              "      <td>295.040009</td>\n",
              "      <td>50.779999</td>\n",
              "      <td>860.000000</td>\n",
              "      <td>478.130005</td>\n",
              "      <td>80.209999</td>\n",
              "    </tr>\n",
              "  </tbody>\n",
              "</table>\n",
              "</div>\n",
              "      <button class=\"colab-df-convert\" onclick=\"convertToInteractive('df-9efe243a-89c2-4ee1-869c-875d2347a211')\"\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-9efe243a-89c2-4ee1-869c-875d2347a211 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-9efe243a-89c2-4ee1-869c-875d2347a211');\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": [
              "                   ACN         AMZN  ...         UNH        XOM\n",
              "Date                                 ...                       \n",
              "2022-02-07  343.959991  3158.709961  ...  483.700012  81.486641\n",
              "2022-02-08  345.070007  3228.270020  ...  493.410004  79.379997\n",
              "2022-02-09  355.529999  3223.790039  ...  498.100006  79.000000\n",
              "2022-02-10  342.390015  3180.070068  ...  486.720001  78.239998\n",
              "2022-02-11  329.179993  3065.870117  ...  478.130005  80.209999\n",
              "\n",
              "[5 rows x 15 columns]"
            ]
          },
          "execution_count": 60,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "prices = ohlc[\"Adj Close\"].dropna(how=\"all\")\n",
        "prices.tail()"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 61,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 563
        },
        "id": "-8Et4dlp9ny-",
        "outputId": "e35cbcf6-f837-4a84-9946-b7a31d4b6901"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 1080x720 with 1 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          },
          "output_type": "display_data"
        }
      ],
      "source": [
        "prices[prices.index >= \"2008-01-01\"].plot(figsize=(15,10));"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "v4vdGWLR9ny-"
      },
      "source": [
        "## Calculating the covariance matrix"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 62,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 35
        },
        "id": "dTFkI4ll9ny-",
        "outputId": "2a0c7a48-d357-4445-bdd1-44dbe901c17a"
      },
      "outputs": [
        {
          "data": {
            "application/vnd.google.colaboratory.intrinsic+json": {
              "type": "string"
            },
            "text/plain": [
              "'1.5.1'"
            ]
          },
          "execution_count": 62,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "import pypfopt\n",
        "pypfopt.__version__"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 63,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 520
        },
        "id": "0hDN8ZJG9ny_",
        "outputId": "35244fed-56ac-4207-ee84-736e924b1210"
      },
      "outputs": [
        {
          "data": {
            "text/html": [
              "\n",
              "  <div id=\"df-1fb48916-7e76-4fc2-916e-0dc13d1c440b\">\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>ACN</th>\n",
              "      <th>AMZN</th>\n",
              "      <th>COST</th>\n",
              "      <th>DIS</th>\n",
              "      <th>F</th>\n",
              "      <th>GILD</th>\n",
              "      <th>JPM</th>\n",
              "      <th>KO</th>\n",
              "      <th>LUV</th>\n",
              "      <th>MA</th>\n",
              "      <th>MSFT</th>\n",
              "      <th>PFE</th>\n",
              "      <th>TSLA</th>\n",
              "      <th>UNH</th>\n",
              "      <th>XOM</th>\n",
              "    </tr>\n",
              "  </thead>\n",
              "  <tbody>\n",
              "    <tr>\n",
              "      <th>ACN</th>\n",
              "      <td>0.090509</td>\n",
              "      <td>0.044122</td>\n",
              "      <td>0.027093</td>\n",
              "      <td>0.039862</td>\n",
              "      <td>0.042294</td>\n",
              "      <td>0.028876</td>\n",
              "      <td>0.048031</td>\n",
              "      <td>0.020089</td>\n",
              "      <td>0.035989</td>\n",
              "      <td>0.044941</td>\n",
              "      <td>0.040171</td>\n",
              "      <td>0.025456</td>\n",
              "      <td>0.038706</td>\n",
              "      <td>0.030231</td>\n",
              "      <td>0.030277</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>AMZN</th>\n",
              "      <td>0.044122</td>\n",
              "      <td>0.333174</td>\n",
              "      <td>0.046653</td>\n",
              "      <td>0.053939</td>\n",
              "      <td>0.050742</td>\n",
              "      <td>0.058897</td>\n",
              "      <td>0.065846</td>\n",
              "      <td>0.019743</td>\n",
              "      <td>0.046568</td>\n",
              "      <td>0.055070</td>\n",
              "      <td>0.071108</td>\n",
              "      <td>0.031008</td>\n",
              "      <td>0.056317</td>\n",
              "      <td>0.034517</td>\n",
              "      <td>0.026534</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>COST</th>\n",
              "      <td>0.027093</td>\n",
              "      <td>0.046653</td>\n",
              "      <td>0.101307</td>\n",
              "      <td>0.031453</td>\n",
              "      <td>0.030889</td>\n",
              "      <td>0.026991</td>\n",
              "      <td>0.038500</td>\n",
              "      <td>0.020990</td>\n",
              "      <td>0.030894</td>\n",
              "      <td>0.031610</td>\n",
              "      <td>0.036822</td>\n",
              "      <td>0.025182</td>\n",
              "      <td>0.023795</td>\n",
              "      <td>0.027244</td>\n",
              "      <td>0.020258</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>DIS</th>\n",
              "      <td>0.039862</td>\n",
              "      <td>0.053939</td>\n",
              "      <td>0.031453</td>\n",
              "      <td>0.099282</td>\n",
              "      <td>0.040060</td>\n",
              "      <td>0.032258</td>\n",
              "      <td>0.046948</td>\n",
              "      <td>0.026108</td>\n",
              "      <td>0.038929</td>\n",
              "      <td>0.049582</td>\n",
              "      <td>0.042028</td>\n",
              "      <td>0.029342</td>\n",
              "      <td>0.036409</td>\n",
              "      <td>0.031974</td>\n",
              "      <td>0.025565</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>F</th>\n",
              "      <td>0.042294</td>\n",
              "      <td>0.050742</td>\n",
              "      <td>0.030889</td>\n",
              "      <td>0.040060</td>\n",
              "      <td>0.126229</td>\n",
              "      <td>0.029964</td>\n",
              "      <td>0.054264</td>\n",
              "      <td>0.026189</td>\n",
              "      <td>0.045692</td>\n",
              "      <td>0.061195</td>\n",
              "      <td>0.040478</td>\n",
              "      <td>0.026943</td>\n",
              "      <td>0.049889</td>\n",
              "      <td>0.028910</td>\n",
              "      <td>0.027745</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>GILD</th>\n",
              "      <td>0.028876</td>\n",
              "      <td>0.058897</td>\n",
              "      <td>0.026991</td>\n",
              "      <td>0.032258</td>\n",
              "      <td>0.029964</td>\n",
              "      <td>0.236847</td>\n",
              "      <td>0.042570</td>\n",
              "      <td>0.016573</td>\n",
              "      <td>0.030993</td>\n",
              "      <td>0.032428</td>\n",
              "      <td>0.035246</td>\n",
              "      <td>0.032544</td>\n",
              "      <td>0.031860</td>\n",
              "      <td>0.034024</td>\n",
              "      <td>0.021151</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>JPM</th>\n",
              "      <td>0.048031</td>\n",
              "      <td>0.065846</td>\n",
              "      <td>0.038500</td>\n",
              "      <td>0.046948</td>\n",
              "      <td>0.054264</td>\n",
              "      <td>0.042570</td>\n",
              "      <td>0.128635</td>\n",
              "      <td>0.027724</td>\n",
              "      <td>0.048865</td>\n",
              "      <td>0.069651</td>\n",
              "      <td>0.049022</td>\n",
              "      <td>0.032685</td>\n",
              "      <td>0.038669</td>\n",
              "      <td>0.038593</td>\n",
              "      <td>0.033223</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>KO</th>\n",
              "      <td>0.020089</td>\n",
              "      <td>0.019743</td>\n",
              "      <td>0.020990</td>\n",
              "      <td>0.026108</td>\n",
              "      <td>0.026189</td>\n",
              "      <td>0.016573</td>\n",
              "      <td>0.027724</td>\n",
              "      <td>0.053686</td>\n",
              "      <td>0.022939</td>\n",
              "      <td>0.025996</td>\n",
              "      <td>0.027703</td>\n",
              "      <td>0.026023</td>\n",
              "      <td>0.017915</td>\n",
              "      <td>0.022867</td>\n",
              "      <td>0.020719</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>LUV</th>\n",
              "      <td>0.035989</td>\n",
              "      <td>0.046568</td>\n",
              "      <td>0.030894</td>\n",
              "      <td>0.038929</td>\n",
              "      <td>0.045692</td>\n",
              "      <td>0.030993</td>\n",
              "      <td>0.048865</td>\n",
              "      <td>0.022939</td>\n",
              "      <td>0.138389</td>\n",
              "      <td>0.047140</td>\n",
              "      <td>0.036270</td>\n",
              "      <td>0.025900</td>\n",
              "      <td>0.036126</td>\n",
              "      <td>0.032550</td>\n",
              "      <td>0.023492</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>MA</th>\n",
              "      <td>0.044941</td>\n",
              "      <td>0.055070</td>\n",
              "      <td>0.031610</td>\n",
              "      <td>0.049582</td>\n",
              "      <td>0.061195</td>\n",
              "      <td>0.032428</td>\n",
              "      <td>0.069651</td>\n",
              "      <td>0.025996</td>\n",
              "      <td>0.047140</td>\n",
              "      <td>0.118957</td>\n",
              "      <td>0.048222</td>\n",
              "      <td>0.032067</td>\n",
              "      <td>0.045800</td>\n",
              "      <td>0.043067</td>\n",
              "      <td>0.042364</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>MSFT</th>\n",
              "      <td>0.040171</td>\n",
              "      <td>0.071108</td>\n",
              "      <td>0.036822</td>\n",
              "      <td>0.042028</td>\n",
              "      <td>0.040478</td>\n",
              "      <td>0.035246</td>\n",
              "      <td>0.049022</td>\n",
              "      <td>0.027703</td>\n",
              "      <td>0.036270</td>\n",
              "      <td>0.048222</td>\n",
              "      <td>0.114380</td>\n",
              "      <td>0.030531</td>\n",
              "      <td>0.046543</td>\n",
              "      <td>0.033904</td>\n",
              "      <td>0.029044</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>PFE</th>\n",
              "      <td>0.025456</td>\n",
              "      <td>0.031008</td>\n",
              "      <td>0.025182</td>\n",
              "      <td>0.029342</td>\n",
              "      <td>0.026943</td>\n",
              "      <td>0.032544</td>\n",
              "      <td>0.032685</td>\n",
              "      <td>0.026023</td>\n",
              "      <td>0.025900</td>\n",
              "      <td>0.032067</td>\n",
              "      <td>0.030531</td>\n",
              "      <td>0.076177</td>\n",
              "      <td>0.017701</td>\n",
              "      <td>0.028095</td>\n",
              "      <td>0.023014</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>TSLA</th>\n",
              "      <td>0.038706</td>\n",
              "      <td>0.056317</td>\n",
              "      <td>0.023795</td>\n",
              "      <td>0.036409</td>\n",
              "      <td>0.049889</td>\n",
              "      <td>0.031860</td>\n",
              "      <td>0.038669</td>\n",
              "      <td>0.017915</td>\n",
              "      <td>0.036126</td>\n",
              "      <td>0.045800</td>\n",
              "      <td>0.046543</td>\n",
              "      <td>0.017701</td>\n",
              "      <td>0.318528</td>\n",
              "      <td>0.030380</td>\n",
              "      <td>0.028871</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>UNH</th>\n",
              "      <td>0.030231</td>\n",
              "      <td>0.034517</td>\n",
              "      <td>0.027244</td>\n",
              "      <td>0.031974</td>\n",
              "      <td>0.028910</td>\n",
              "      <td>0.034024</td>\n",
              "      <td>0.038593</td>\n",
              "      <td>0.022867</td>\n",
              "      <td>0.032550</td>\n",
              "      <td>0.043067</td>\n",
              "      <td>0.033904</td>\n",
              "      <td>0.028095</td>\n",
              "      <td>0.030380</td>\n",
              "      <td>0.163641</td>\n",
              "      <td>0.022321</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>XOM</th>\n",
              "      <td>0.030277</td>\n",
              "      <td>0.026534</td>\n",
              "      <td>0.020258</td>\n",
              "      <td>0.025565</td>\n",
              "      <td>0.027745</td>\n",
              "      <td>0.021151</td>\n",
              "      <td>0.033223</td>\n",
              "      <td>0.020719</td>\n",
              "      <td>0.023492</td>\n",
              "      <td>0.042364</td>\n",
              "      <td>0.029044</td>\n",
              "      <td>0.023014</td>\n",
              "      <td>0.028871</td>\n",
              "      <td>0.022321</td>\n",
              "      <td>0.051663</td>\n",
              "    </tr>\n",
              "  </tbody>\n",
              "</table>\n",
              "</div>\n",
              "      <button class=\"colab-df-convert\" onclick=\"convertToInteractive('df-1fb48916-7e76-4fc2-916e-0dc13d1c440b')\"\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-1fb48916-7e76-4fc2-916e-0dc13d1c440b 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-1fb48916-7e76-4fc2-916e-0dc13d1c440b');\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": [
              "           ACN      AMZN      COST  ...      TSLA       UNH       XOM\n",
              "ACN   0.090509  0.044122  0.027093  ...  0.038706  0.030231  0.030277\n",
              "AMZN  0.044122  0.333174  0.046653  ...  0.056317  0.034517  0.026534\n",
              "COST  0.027093  0.046653  0.101307  ...  0.023795  0.027244  0.020258\n",
              "DIS   0.039862  0.053939  0.031453  ...  0.036409  0.031974  0.025565\n",
              "F     0.042294  0.050742  0.030889  ...  0.049889  0.028910  0.027745\n",
              "GILD  0.028876  0.058897  0.026991  ...  0.031860  0.034024  0.021151\n",
              "JPM   0.048031  0.065846  0.038500  ...  0.038669  0.038593  0.033223\n",
              "KO    0.020089  0.019743  0.020990  ...  0.017915  0.022867  0.020719\n",
              "LUV   0.035989  0.046568  0.030894  ...  0.036126  0.032550  0.023492\n",
              "MA    0.044941  0.055070  0.031610  ...  0.045800  0.043067  0.042364\n",
              "MSFT  0.040171  0.071108  0.036822  ...  0.046543  0.033904  0.029044\n",
              "PFE   0.025456  0.031008  0.025182  ...  0.017701  0.028095  0.023014\n",
              "TSLA  0.038706  0.056317  0.023795  ...  0.318528  0.030380  0.028871\n",
              "UNH   0.030231  0.034517  0.027244  ...  0.030380  0.163641  0.022321\n",
              "XOM   0.030277  0.026534  0.020258  ...  0.028871  0.022321  0.051663\n",
              "\n",
              "[15 rows x 15 columns]"
            ]
          },
          "execution_count": 63,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "from pypfopt import risk_models\n",
        "from pypfopt import plotting\n",
        "\n",
        "sample_cov = risk_models.sample_cov(prices, frequency=252)\n",
        "sample_cov"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 64,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 297
        },
        "id": "HZ15mDtz9ny_",
        "outputId": "5fe64424-4756-4289-e29e-39edc3eb83df"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 432x288 with 2 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          },
          "output_type": "display_data"
        }
      ],
      "source": [
        "plotting.plot_covariance(sample_cov, plot_correlation=True);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "0bhjN57j9ny_"
      },
      "source": [
        "For reasons discussed in the docs, the sample covariance matrix should not be your default choice. I think a better option is Ledoit-Wolf shrinkage, which reduces the extreme values in the covariance matrix. In the image below, we can see that there are fewer bright spots outside the diagonal:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 65,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 297
        },
        "id": "htpILjX-9nzA",
        "outputId": "254cc6d7-bbee-48bf-c888-82c85a96bf83"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 432x288 with 2 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          },
          "output_type": "display_data"
        }
      ],
      "source": [
        "S = risk_models.CovarianceShrinkage(prices).ledoit_wolf()\n",
        "plotting.plot_covariance(S, plot_correlation=True);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "4mbpNBp39nzA"
      },
      "source": [
        "## Return estimation\n",
        "\n",
        "As discussed in the docs, it is often a bad idea to provide returns using a simple estimate like the mean of past returns. Unless you have a proprietary method for estimating returns, research suggests that you may be better off not providing expected returns – you can then just find the `min_volatility()` portfolio or use `HRP`. \n",
        "\n",
        "However, in this example we will use the CAPM returns, which aims to be slightly more stable than the default mean historical return. Please see the notebook `1-RiskReturnModels.ipynb` for more information."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 66,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "c_syhOUu9nzH",
        "outputId": "40e40fd5-06ac-4f42-c375-7a240c15c27e"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "ACN     0.208954\n",
              "AMZN    0.357918\n",
              "COST    0.195447\n",
              "DIS     0.225500\n",
              "F       0.225823\n",
              "GILD    0.256957\n",
              "JPM     0.254209\n",
              "KO      0.149553\n",
              "LUV     0.228889\n",
              "MA      0.262448\n",
              "MSFT    0.240114\n",
              "PFE     0.179743\n",
              "TSLA    0.281222\n",
              "UNH     0.222502\n",
              "XOM     0.142792\n",
              "Name: mkt, dtype: float64"
            ]
          },
          "execution_count": 66,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "from pypfopt import expected_returns\n",
        "\n",
        "mu = expected_returns.capm_return(prices)\n",
        "mu"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 67,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 374
        },
        "id": "MlqP3XP99nzH",
        "outputId": "f5e026c2-d259-4894-d3dc-a667d591e101"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 720x432 with 1 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          },
          "output_type": "display_data"
        }
      ],
      "source": [
        "mu.plot.barh(figsize=(10,6));"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "iHNXRsJA9nzI"
      },
      "source": [
        "## Long/short min variance\n",
        "\n",
        "In this section, we construct a long/short portfolio with the objective of minimising variance. There is a good deal of research that demonstrates that these global-minimum variance (GMV) portfolios outperform mean-variance optimized portfolios."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 68,
      "metadata": {
        "id": "LTjcmcmK9nzI"
      },
      "outputs": [],
      "source": [
        "from pypfopt import EfficientFrontier"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 69,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "ZD5_4rlY9nzI",
        "outputId": "81faef92-6667-4452-8859-3a659d235b14"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "OrderedDict([('ACN', 0.23365),\n",
              "             ('AMZN', 0.00898),\n",
              "             ('COST', 0.09927),\n",
              "             ('DIS', -0.01671),\n",
              "             ('F', -0.01694),\n",
              "             ('GILD', 0.04402),\n",
              "             ('JPM', -0.04977),\n",
              "             ('KO', 0.12552),\n",
              "             ('LUV', 0.02447),\n",
              "             ('MA', 0.23242),\n",
              "             ('MSFT', 0.00184),\n",
              "             ('PFE', 0.06605),\n",
              "             ('TSLA', 0.14038),\n",
              "             ('UNH', 0.03111),\n",
              "             ('XOM', 0.07571)])"
            ]
          },
          "execution_count": 69,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "S = risk_models.CovarianceShrinkage(prices).ledoit_wolf()\n",
        "\n",
        "# You don't have to provide expected returns in this case\n",
        "ef = EfficientFrontier(None, S, weight_bounds=(None, None))\n",
        "ef.min_volatility()\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 70,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 265
        },
        "id": "RVRwHED99nzJ",
        "outputId": "f606418a-1614-4c38-9574-c18b1b9c5ac6"
      },
      "outputs": [
        {
          "data": {
            "image/png": "iVBORw0KGgoAAAANSUhEUgAAAYIAAAD4CAYAAADhNOGaAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADh0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uMy4yLjIsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy+WH4yJAAAX90lEQVR4nO3dfbRdVX3u8e8jVF4atMTE+ALhAEVbg1wKp9bbqhXEIVbQ4KU2aYtYGTfFl9EBRYsVOxQvjvoCVBEsTUWD3vJitYAiRUEMaK9yOcFADMhLCCJIMYCVG0Ek8bl/rHVgZWef17XX3uec9XzG2OOsNdfca8/JPpxf1lxz/aZsExER7fW0QTcgIiIGK4EgIqLlEggiIlougSAiouUSCCIiWm7HQTdgqhYsWOChoaFBNyMiYlZZs2bNg7YXdjs26wLB0NAQIyMjg25GRMSsIumHYx3L0FBERMslEEREtFytoSFJewLXAQfbfljS7sCNwGuAtwNHAAZuAd5h+97yfQb+xfafl/s7AvcD19s+ok6b2ujIky4bdBNmva+c8YZBNyFiYGpdEdj+EfCPwIfLog8DK4EVwG7AC23vB1wK/JsklfV+DuwvaZdy/9XAfXXaEhER09OLoaF/AF4q6QTgZcCngL8ATrS9FcD2Z4HHgUMr77sCeF25vRy4sAdtiYiIKaodCGw/AbybIiCcAOwF3GP7kY6qI8CSyv5FwDJJOwMHANfXbUtERExdr24Wv5ZijH//yb7B9s3AEMXVwBXj1ZW0QtKIpJFNmzbVaWdERHSoHQgkHUgxxv9S4ETgIWCxpN06qh4MrO8o+zJwOhMMC9leaXvY9vDChV2fh4iIiGmqFQjKm7//CJxg+x7gY8BHgfOBMyXtUNZ7M7ArcE3HKT4DnGp7XZ12RETE9NV9svh/UtwPuKrcH71RvBI4Grhd0q+AHwBHuWMVnHI66Vk129B6mfoYEXVotq1QNjw87KSYiIiYGklrbA93O5YniyMiWi6BICKi5RIIIiJaLoEgIqLlEggiIlpu1i1ME9ubCdlHM4U1YvbqxZPFQ5K+31H2AUnvkrRK0n2SdirLF0i6e6L31W1TRERMXj+GhrYCb+3D50RExDT0IxB8HDixXHwmIiJmmH4EgnuAbwPHdDm2r6S1oy/g+G4nSPbRiIjm9CIQjJWjolr+9xRrFnR+3gbbB46+gHO7nijZRyMiGtOLQPAQsHtH2XzgwdEd23cAa4E39eDzIiKih3qxQtlm4H5JhwJImg8cTjEcVPUhIDOCIiJmmF7dwH0zcI6kM8v9U21veGqterC9XtKNwEE9+swoZQ5/RNSRNNQRES2QNNQRETGmBIKIiJZLIIiIaLkEgoiIlksgiIhouSlPH5X0LOAb5e5zKJLKjeZ9uITiobGtwK+Av7R9vaTVwLtsbzfdR9LS8n2/bfsHU+5BzIg01DH3ZFpye0w5ENh+CDgQirTRwGbbp0v678CZwEG2H5e0AHj6JE65nOLhs+XA+6fanoiIqKeXQ0PPBR60/TiA7Qdt/3i8N0iaB7wMOA5Y1sO2RETEJPUyEHwd2FPS7ZI+JekPJ/GeNwBX2r4deEjSwT1sT0RETELPAkGZc+hgYAXFPYOLJb1lgrctBy4qty8q97eTNNQREc3p6WIxtrcCq4HVktYBxwKrutUtk9MdCrxYkoEdAEt6tzvyXtheCayEIsVEL9scEdF2PbsikPRCSftVig4EfjjOW44GPm97L9tDtvcENgIv71WbIiJiYr28IpgHfFLSbwBbgDspholGfVXSE+X2d4AFwEc6zvEliuGh63rYrjkv0/wioo5agcD2Byrba4DfH6PeKyd5vrPqtCciIqYuTxZHRLRcAkFERMslEEREtFwCQUREyyUQRES0XE8fKIvBSPbRsWVqbcTEeh4IJG0F1pXnvhU41vajlfJRS4Eh4DKKB8lGvcv21b1uV0REdNfEFcFjtkfTVP8LcDxFeuony0dJGgK+ZfuIBtoRERGT0PQ9gm8Bv9nwZ0RERA2NBQJJOwKv5anhoF0krS1fl1SqvrxSvlbSvl3OleyjERENaWJoaBdJa8vtbwHnldvbDQ2N1ploaCjZRyMimtPoPYKIiJj58hxBRETLzYTnCF5eGUoCOM32FwfWmlkoc+Ujoo6eBwLb8yZbbns18MxetyEiIiYvQ0MRES2XQBAR0XIJBBERLZdAEBHRcgkEEREtN+VAIMmS/ndlf0dJmyRdXu4vknS5pJsk3SLpirJ8SNJjHekk3l/Z3lrZ/qvedXHuO/Kky5KKOiKmbTrTR38O7C9pF9uPAa8G7qsc/yBwle1PAEg6oHJsQ5enjk8t623OE8kREf033aGhK4DXldvLgQsrx54L3Du6Y/vmaX5GRET0wXQDwUXAMkk7AwcA11eOnQOcJ+mbkk6R9LzKsX0rwz/nTPOzIyKih6b1ZLHtm8tFZZZTXB1Uj31N0j7A4RRpqL8naf/ycLehoQlJWgGsAFi8ePF0mhwREWOoM2voy8DpbDssBIDth21fYPsY4AbgFTU+B9srbQ/bHl64cGGdU0VERIc6geAzwKm2q+sQI+lQSbuW27sB+wL31PiciIho0LSTztm+Fziry6GDgbMlbaEINJ+2fUM5lBQNSPbRiKhD9uxa8Gt4eNgjIyODbkZExKwiaY3t4W7H8mRxRETLJRBERLRcAkFERMslEEREtFwCQUREy82ExeujpmQejZjbmp4i3ugVwUQpqyvll0r6bpNtiYiI7poeGnoyZXW535myGkm/QfEQ2jPLHEUREdFH/bhHMF7KaoA3Al+hzGjah/ZERERFPwLBeCmr4angcGG5vR1JKySNSBrZtGlTo42NiGibxgNBuTDNEF1SVktaBOwHfNv27cATlZTV1XMk+2hEREP6NX10rJTVbwJ2BzZKupunAkZERPRJvwJB15TVFH/0D7c9ZHuI4qZx7hNERPRRX54j6JayukxLvRfw3Uq9jZJ+Jun3bHfeS4gxJA11RNTRaCCwPa9L2Wpgdbn7/C7HD2qyTRERsa2kmIiIaLkEgoiIlksgiIhouQSCiIiWSyCIiGi5ns4akrS5OlOonCJ6ue39K2UfADYDmyieIVheObYAuBXYw/bjvWzbXNavNNSZphoxNw3yiuAS4NWSdq2UHQ18JUEgIqJ/BhYIbD8CXAscWSlexvZpKCIiokGDvkdwIWVKCUnPA14AXDPQFkVEtEzTgcATlH8V+ANJz6BIQPcl21s7KycNdUREc5oOBA9RZBetmg88CGD7MeBK4CjGGRZKGuqIiOY0Gghsbwbul3QogKT5wOHAtyvVLgT+GlgEfKfJ9kRExPZ6nXRuV0n3VvbPBN4MnCPpzLLsVNsbKnWuAj4HnGd7rKGkGEemdUZEHT0NBLbHusI4ZJz3bAEy3hMRMSCDnjUUEREDlkAQEdFyCQQRES2XQBAR0XIJBBERLdeXxeujWf3KPhqzT6YWx2Q0fkUgaXNl+48k3S5pL0l7SLpM0h2SNkj6hKSnN92eiIjYVt+GhiS9CjgLeC1wD/BvwKW296NINjcP+FC/2hMREYW+BAJJrwD+GTiifKr4UOAXtj8LUCaaOxF4a8f6BBER0bB+BIKdgEuBpbZ/UJYtAdZUK5XrE9wD/GbnCZJ9NCKiOf0IBE8A/wc4bronSPbRiIjm9CMQ/IpirYGXSHpvWXYLcHC1UrkmwWLgzj60KSIiSn25R2D7UeB1wJ9JOg74BkWm0jcDSNoBOANYVdaNiIg+6dtzBLYflnQ4cB2wiWIxmk9J+juKgHQF8N5xThFjyFzxiKij8UBge15l+0fA3pXDR27/joiI6KekmIiIaLkEgoiIlksgiIhouQSCiIiWSyCIiGi5RmYNlRlH9wduBW4Dnk4xbfTtFA+NbQQ+ZPt9Zf0FwP3AP9l+ZxNtgrmbrjnTRyOijqavCDbYPhA4AHgRsLQs30jxgNmoPwbWN9yWiIjool9PFm+hyDc0mlDuUeBWScPl/p8AX+hHWyIiYlv9SkO9K/AqYF2l+CJgmaQ9ga3Aj/vRloiI2FbTTxbvK2ktYOAy2/8uaag8diXwv4AHgIvHO4mkFcAKgMWLFzfW2IiINmo6EIzeI9iO7V9KWgOcRHH/4PVjncT2SmAlwPDwsJtoaEREWw168fozgGvLhHQDbkpERDv1PBBI2hF4fDJ1ba+nj7OFMs0yImJ7TVwRLKEYErqb4lmCbYxTvgpY1UB7IiJiHD2dNSTpeOBC4H29PG9ERDSnp1cEts8Fzu3lOSMiolnJNRQR0XIJBBERLZdAEBHRcoN+jiB6YDZnVc2U3ojBq3VFIGmRpAsk3SVpjaTvSDpK0islXV7WeYuks7u8925J68rXLZJOk7RznfZERMTUTTsQqHgU+FLgOtv72D4YWAbsMYXTHGL7xcBLgH2Af5pueyIiYnrqXBEcCvyynDIKgO0f2v7kVE9kezNwPLBU0vwabYqIiCmqEwiWADf2qiG2H6FYsGa/zmOSVkgakTSyadOmXn1kRETQw1lDks6RdJOkG+qcpluh7ZW2h20PL1y4sMbpIyKiU51AsB44aHTH9jsoFp+Z1l9qSbsBQ8DtNdoUERFTVCcQXAPsLOltlbJdp3MiSfOATwGX2v5pjTZFRMQUTfs5AtuWtBT4B0l/A2wCfg6c3KX6W8q6o15a/vxmOfvoacAlFCuWxRRlLn5E1FHrgTLb91NMGe1mdVlnFd3TSw/V+eyIiOiNpJiIiGi5BIKIiJZLIIiIaLkEgoiIlksgiIhouYGnoZa0FVhXKVpaLnA/5/UqfXSmj0ZEHQMPBMBjtg8cdCMiItoqQ0MRES03E64IdpG0ttzeaPuogbYmIqJlZkIgmHBoSNIKYAXA4sWL+9KoiIi2mBVDQ0lDHRHRnFkRCCIiojkzYWiotTLtMyJmgoFfEdieN+g2RES02cADQUREDFYCQUREyyUQRES0XAJBRETLJRBERLRcpo8OULKPRsRM0MgVgaStktZKWi/pJkknSXpaeeyVki4vtxdJurysc4ukK5poT0REjK2pK4In8wdJejZwAfAM4P0d9T4IXGX7E2XdAxpqT0REjKHxewS2f0KRMO6dktRx+LnAvZW6NzfdnoiI2FZfbhbbvgvYAXh2x6FzgPMkfVPSKZKe1+39klZIGpE0smnTpqabGxHRKgOdNWT7a8A+wD8DvwV8T9J26UWTfTQiojl9CQSS9gG2Aj/pPGb7YdsX2D4GuAF4RT/aFBERhcYDQfkv/HOBs22749ihknYtt3cD9gXuabpNERHxlKZmDY0uP/lrwBbg88CZXeodDJwtaQtFUPq07RsaatOMk/n/ETETNBIIbO8wzrHVwOpy+2PAx5poQ0RETE5STEREtFwCQUREyyUQRES0XAJBRETLJRBERLTclGcNSXoO8HHgd4H/Ah4ATqCYKvpJ4PkUAeZzwGm2LWkRcB6wZ1nvbuBkimmlAIuBn5WvB20fNv0utU+v0llHszJdOGaqKQWCMmncJcD5tpeVZf8NWASsAt5m++vlQ2JfAt5OkU9ouyyjttcBoxlKVwGX2/5iLzoVERGTN9WhoUOAJ2yfO1pg+ybgBcB/2P56WfYo8E7gPWW1ZBmNiJihphoI9gfWdClf0lluewMwT9IzmGSW0YiI6L9+paGeVJbRsSQNdUREc6YaCNZT5AfqdEtneZlxdLPtR6BeltGkoY6IaM5UA8E1wE6SVowWlMtL3ga8TNJhZdkuwFnAR8v9ZBmNiJihpjRrqJwKehTwcUknA7+gmAp6AvAG4JOSzqFYjezzwNnlW1udZbRpmZYYEXWoY4mAGW94eNgjIyODbkZExKwiaY3t4W7H8mRxRETLJRBERLRcAkFERMslEEREtFwCQUREyzW1eH300WSyj2aKaUSMZVJXBJKWSrKk3yr3h8r90yp1Fkh6QtLZ5f7XJK2tvH4s6fry2CpJ90naqfLeu3veu4iImNBkh4aWA98uf47aCLyusv/HFCkoALD9GtsH2j4Q+APgEeB9lfpbgbdOp9EREdE7EwYCSfOAlwHHAcsqhx4FbpU0+oDCnwBfGOM0nwCusH1VpezjwImSMjwVETFAk7kieANwpe3bgYckVZPLXQQsk7Qnxb/wf9z5ZklvBIaBv+04dA/FVcYxEzUg2UcjIpozmUCwnOIPPuXP6vDQlcCrKa4ULu58o6TnU1wN/Kntx7uc+++Bd0/UjmQfjYhozrjDMpLmA4cCL5ZkimRyplhoBtu/lLQGOAl4EfD6ynsFnA982PYt3c5v+w5Ja4E39aAvERExDRONzx8NfN72X44WSLqWYhH6UWcA19p+uPjb/6R3Ab+wfc4En/Eh4KuTb3JERPTSRIFgOfCRjrIvURnvt72eymyhitOAe8t/8Y/6qe1DqpVsr5d0I3DQpFsd28gzAhFRR9JQR0S0QNJQR0TEmBIIIiJaLoEgIqLlEggiIlougSAiouV6ludH0lLgEuC3bf+gLHsJcDqwiCI30RrgrygeIPsMcKDtm8u63weOsH13r9rUFpNJQx0Rs19TU8V7eUWwTYZSSYuAfwVOtv1C279DkZJit7L+vcApPfz8iIiYhp4EgjEylL4DON/2d0br2f6i7QfK3cuBJZJe2Is2RETE9PTqiqBbhtL9KYaCxvIr4KPAe3vUhoiImIZeBYLxMpSO5wLgpZL2Hq9S0lBHRDSn9s3icTKUng8cDIx5J9P2FklnACeP9xm2VwIroUgxUbfNERHxlF5cEYxmKN3L9pDtPSmWsbwaOFbS741WlPTG8iZy1SrgMCALDUREDEAvpo+OlaF0Wfk6XdKzKe4JXEcxc+hJ5ZoGZ1EsYBPTkOyjEVFHso9GRLRAso9GRMSYEggiIlpu1g0NSdoE/HCab18APNjD5swUc7Ffc7FPkH7NNnOpX3vZ7jopZ9YFgjokjYw1RjabzcV+zcU+Qfo128zVfnXK0FBERMslEEREtFzbAsHKQTegIXOxX3OxT5B+zTZztV/baNU9goiI2F7brggiIqJDAkFERMvNuUAgab6kqyTdUf7cfYx6x5Z17pB0bKV8taTbJK0tX8/uX+u3a+PhZVvulPSeLsd3knRxefx6SUOVY39blt8m6TX9bPdEptsvSUOSHqt8N+f2u+3jmUS/XiHpRklbJB3dcazr7+Og1ezT1sp39eX+tXpik+jXX0u6RdLNkr4haa/KsRn5XdVie069KBa7eU+5/R7gI13qzAfuKn/uXm7vXh5bDQzPgH7sAGwA9gGeDtwEvKijztuBc8vtZcDF5faLyvo7AXuX59lh0H3qQb+GgO8Pug81+jUEHAB8Djh6Mr+Ps7VP5bHNg+5DjX4dAuxabr+t8js4I7+ruq85d0VAsVra+eX2+cDSLnVeA1xl+2HbPwWuAg7vU/sm6yXAnbbvsv1LigV/OtOMVvv6ReBVklSWX2T7cdsbgTvL880Edfo1k03YL9t3276ZIhNv1Uz9fazTp5lsMv36pu1Hy93vAnuU2zP1u6plLgaCRbbvL7f/E+hc/wDg+cCPKvv3lmWjPltezv7dAP8ATdTGberY3gL8DHjWJN87KHX6BbC3pO9JulbSy5tu7BTU+W8+U7+vuu3auVxZ8LuSuv2DbFCm2q/jgH+f5ntnhV6sR9B3kq4GntPl0CnVHdsuV02bij+zfZ+k3SjWVTiG4rI3Bu9+YLHt0XWxL5W0xPYjg25YdLVX+f/SPsA1ktbZ3jDoRk2FpD8HhoE/HHRbmjQrrwhsH2Z7/y6vy4AHJD0XoPz5ky6nuA/Ys7K/R1mG7dGf/49iTeVBDamM2cZudSTtCDwTeGiS7x2UaferHOp6CMD2Gopx3hc03uLJqfPffKZ+X7XaVfl/6S6Ke2+/08vG1TCpfkk6jOIfl6+3/fhU3jvrDPomRa9fwMfY9mbxR7vUmU+xnObu5WtjWbYjsKCs82sU49PHD6gfO1LciNqbp25oLemo8w62van6hXJ7CdveLL6LmXOzuE6/Fo72g+JG333A/EH3abL9qtRdxfY3i7f7fZzlfdod2KncXgDcQccN2ZncL4qgtQHYr6N8Rn5Xtf+bDLoBDXzJzwK+Uf7iXT36JVFc3n26Uu+tFDdR7wT+oiz7dWANcDOwnmL5zIH9AQX+CLi9/IU8pSz7IMW/UAB2Bv617MP/BfapvPeU8n23Aa8d9PfSi34B/6P8XtYCNwJHDrovU+zX71KMKf+c4spt/Xi/jzPhNd0+Ab8PrCv/yK4Djht0X6bYr6uBB8rftbXAl2f6d1XnlRQTEREtNyvvEURERO8kEEREtFwCQUREyyUQRES0XAJBRETLJRBERLRcAkFERMv9f5SBkagSVdu/AAAAAElFTkSuQmCC",
            "text/plain": [
              "<Figure size 432x288 with 1 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          },
          "output_type": "display_data"
        }
      ],
      "source": [
        "pd.Series(weights).plot.barh();"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "jpgqSknF9nzJ"
      },
      "source": [
        "We can get a quick indication of the portfolio performance as follows. Note that this is an in sample estimate and may have very little resemblance to how the portfolio actually performs!"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 71,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "ZnDm8UkC9nzJ",
        "outputId": "9302f8ed-698e-461b-c4a1-ad8113f1aa11"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Annual volatility: 11.9%\n"
          ]
        }
      ],
      "source": [
        "ef.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 72,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 692
        },
        "id": "aYa6yhWx9nzJ",
        "outputId": "0d5cf83b-05f5-44b4-92ae-8f2ab51f6a96"
      },
      "outputs": [
        {
          "data": {
            "text/html": [
              "\n",
              "  <div id=\"df-f194463e-dc4c-434c-8c86-ad1d07949b29\">\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>ACN</th>\n",
              "      <th>AMZN</th>\n",
              "      <th>COST</th>\n",
              "      <th>DIS</th>\n",
              "      <th>F</th>\n",
              "      <th>GILD</th>\n",
              "      <th>JPM</th>\n",
              "      <th>KO</th>\n",
              "      <th>LUV</th>\n",
              "      <th>MA</th>\n",
              "      <th>MSFT</th>\n",
              "      <th>PFE</th>\n",
              "      <th>TSLA</th>\n",
              "      <th>UNH</th>\n",
              "      <th>XOM</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>1962-01-02</th>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.058398</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.051133</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.101854</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>1962-01-03</th>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.059182</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.049994</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.103367</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>1962-01-04</th>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.059182</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.050374</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.103619</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>1962-01-05</th>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.059378</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.049234</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.101350</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>1962-01-08</th>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.059182</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.048728</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>NaN</td>\n",
              "      <td>0.101098</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>...</th>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "      <td>...</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-07</th>\n",
              "      <td>343.959991</td>\n",
              "      <td>3158.709961</td>\n",
              "      <td>515.890015</td>\n",
              "      <td>142.509995</td>\n",
              "      <td>17.889999</td>\n",
              "      <td>63.759998</td>\n",
              "      <td>153.070007</td>\n",
              "      <td>61.599998</td>\n",
              "      <td>44.599998</td>\n",
              "      <td>376.130005</td>\n",
              "      <td>300.950012</td>\n",
              "      <td>53.209999</td>\n",
              "      <td>907.340027</td>\n",
              "      <td>483.700012</td>\n",
              "      <td>81.486641</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-08</th>\n",
              "      <td>345.070007</td>\n",
              "      <td>3228.270020</td>\n",
              "      <td>521.150024</td>\n",
              "      <td>142.479996</td>\n",
              "      <td>17.719999</td>\n",
              "      <td>63.700001</td>\n",
              "      <td>155.949997</td>\n",
              "      <td>62.000000</td>\n",
              "      <td>46.070000</td>\n",
              "      <td>374.369995</td>\n",
              "      <td>304.559998</td>\n",
              "      <td>51.700001</td>\n",
              "      <td>922.000000</td>\n",
              "      <td>493.410004</td>\n",
              "      <td>79.379997</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-09</th>\n",
              "      <td>355.529999</td>\n",
              "      <td>3223.790039</td>\n",
              "      <td>528.830017</td>\n",
              "      <td>147.229996</td>\n",
              "      <td>18.350000</td>\n",
              "      <td>63.380001</td>\n",
              "      <td>156.600006</td>\n",
              "      <td>61.040001</td>\n",
              "      <td>47.020000</td>\n",
              "      <td>381.369995</td>\n",
              "      <td>311.209991</td>\n",
              "      <td>51.470001</td>\n",
              "      <td>932.000000</td>\n",
              "      <td>498.100006</td>\n",
              "      <td>79.000000</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-10</th>\n",
              "      <td>342.390015</td>\n",
              "      <td>3180.070068</td>\n",
              "      <td>518.479980</td>\n",
              "      <td>152.160004</td>\n",
              "      <td>18.080000</td>\n",
              "      <td>61.790001</td>\n",
              "      <td>155.949997</td>\n",
              "      <td>61.380001</td>\n",
              "      <td>46.529999</td>\n",
              "      <td>374.390015</td>\n",
              "      <td>302.380005</td>\n",
              "      <td>50.599998</td>\n",
              "      <td>904.549988</td>\n",
              "      <td>486.720001</td>\n",
              "      <td>78.239998</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2022-02-11</th>\n",
              "      <td>329.179993</td>\n",
              "      <td>3065.870117</td>\n",
              "      <td>509.670013</td>\n",
              "      <td>149.470001</td>\n",
              "      <td>17.549999</td>\n",
              "      <td>62.070000</td>\n",
              "      <td>153.919998</td>\n",
              "      <td>60.290001</td>\n",
              "      <td>45.529999</td>\n",
              "      <td>369.769989</td>\n",
              "      <td>295.040009</td>\n",
              "      <td>50.779999</td>\n",
              "      <td>860.000000</td>\n",
              "      <td>478.130005</td>\n",
              "      <td>80.209999</td>\n",
              "    </tr>\n",
              "  </tbody>\n",
              "</table>\n",
              "<p>15134 rows × 15 columns</p>\n",
              "</div>\n",
              "      <button class=\"colab-df-convert\" onclick=\"convertToInteractive('df-f194463e-dc4c-434c-8c86-ad1d07949b29')\"\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-f194463e-dc4c-434c-8c86-ad1d07949b29 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-f194463e-dc4c-434c-8c86-ad1d07949b29');\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": [
              "                   ACN         AMZN  ...         UNH        XOM\n",
              "Date                                 ...                       \n",
              "1962-01-02         NaN          NaN  ...         NaN   0.101854\n",
              "1962-01-03         NaN          NaN  ...         NaN   0.103367\n",
              "1962-01-04         NaN          NaN  ...         NaN   0.103619\n",
              "1962-01-05         NaN          NaN  ...         NaN   0.101350\n",
              "1962-01-08         NaN          NaN  ...         NaN   0.101098\n",
              "...                ...          ...  ...         ...        ...\n",
              "2022-02-07  343.959991  3158.709961  ...  483.700012  81.486641\n",
              "2022-02-08  345.070007  3228.270020  ...  493.410004  79.379997\n",
              "2022-02-09  355.529999  3223.790039  ...  498.100006  79.000000\n",
              "2022-02-10  342.390015  3180.070068  ...  486.720001  78.239998\n",
              "2022-02-11  329.179993  3065.870117  ...  478.130005  80.209999\n",
              "\n",
              "[15134 rows x 15 columns]"
            ]
          },
          "execution_count": 72,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "prices"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ORCrBIG19nzK"
      },
      "source": [
        "Let's say we were happy with this portfolio and wanted to actually go out and buy the shares.  To do this, we would need to construct a **discrete allocation** (unless your broker supports fractional shares!)\n",
        "\n",
        "If we had \\$20,0000 to invest and would like our portfolio to be 130/30 long/short, we can construct the actual allocation as follows:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 73,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "w10Rcb-X9nzK",
        "outputId": "052edfa3-7811-459c-debb-644dc7aa2368"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Discrete allocation performed with $35.89 leftover\n"
          ]
        },
        {
          "data": {
            "text/plain": [
              "{'ACN': 13,\n",
              " 'COST': 4,\n",
              " 'DIS': -8,\n",
              " 'F': -70,\n",
              " 'GILD': 13,\n",
              " 'JPM': -23,\n",
              " 'KO': 38,\n",
              " 'LUV': 10,\n",
              " 'MA': 12,\n",
              " 'PFE': 25,\n",
              " 'TSLA': 3,\n",
              " 'UNH': 1,\n",
              " 'XOM': 17}"
            ]
          },
          "execution_count": 73,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "from pypfopt import DiscreteAllocation\n",
        "\n",
        "latest_prices = prices.iloc[-1]  # prices as of the day you are allocating\n",
        "da = DiscreteAllocation(weights, latest_prices, total_portfolio_value=20000, short_ratio=0.3)\n",
        "alloc, leftover = da.lp_portfolio()\n",
        "print(f\"Discrete allocation performed with ${leftover:.2f} leftover\")\n",
        "alloc"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ab3Rk-Aa9nzK"
      },
      "source": [
        "## Max Sharpe with sector constraints\n",
        "\n",
        "If you have your own model for returns (or have read the warnings and want to proceed anyways), you may consider maximising the Sharpe ratio. This theoretically gives the optimal portfolio in terms of risks-returns.\n",
        "\n",
        "In this section, we construct a long-only max-sharpe portfolio, but also incorporate sector constraints. Sector constraints require three things. A `sector_mapper`, your `sector_lower` bounds, and your `sector_upper` bounds."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 74,
      "metadata": {
        "id": "mJcyi2-E9nzK"
      },
      "outputs": [],
      "source": [
        "sector_mapper = {\n",
        "    \"MSFT\": \"Tech\",\n",
        "    \"AMZN\": \"Consumer Discretionary\",\n",
        "    \"KO\": \"Consumer Staples\",\n",
        "    \"MA\": \"Financial Services\",\n",
        "    \"COST\": \"Consumer Staples\",\n",
        "    \"LUV\": \"Aerospace\",\n",
        "    \"XOM\": \"Energy\",\n",
        "    \"PFE\": \"Healthcare\",\n",
        "    \"JPM\": \"Financial Services\",\n",
        "    \"UNH\": \"Healthcare\",\n",
        "    \"ACN\": \"Misc\",\n",
        "    \"DIS\": \"Media\",\n",
        "    \"GILD\": \"Healthcare\",\n",
        "    \"F\": \"Auto\",\n",
        "    \"TSLA\": \"Auto\"\n",
        "}\n",
        "\n",
        "sector_lower = {\n",
        "    \"Consumer Staples\": 0.1, # at least 10% to staples\n",
        "    \"Tech\": 0.05 # at least 5% to tech\n",
        "    # For all other sectors, it will be assumed there is no lower bound\n",
        "}\n",
        "\n",
        "sector_upper = {\n",
        "    \"Tech\": 0.2,\n",
        "    \"Aerospace\":0.1,\n",
        "    \"Energy\": 0.1,\n",
        "    \"Auto\":0.15\n",
        "}"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "1h5ZdZwF9nzL"
      },
      "source": [
        "We then set up the optimizer and add our constraints. We can use `ef.add_objective()` to add other constraints. For example, let's say that in addition to the above sector constraints, I specifically want:\n",
        "\n",
        "- 10% of the portfolio in AMZN\n",
        "- Less than 5% of my portfolio in TSLA"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 75,
      "metadata": {
        "id": "FRjwf0wN9nzL"
      },
      "outputs": [],
      "source": [
        "mu = expected_returns.capm_return(prices)\n",
        "S = risk_models.CovarianceShrinkage(prices).ledoit_wolf()\n",
        "\n",
        "ef = EfficientFrontier(mu, S)  # weight_bounds automatically set to (0, 1)\n",
        "ef.add_sector_constraints(sector_mapper, sector_lower, sector_upper)\n",
        "\n",
        "amzn_index = ef.tickers.index(\"AMZN\")\n",
        "ef.add_constraint(lambda w: w[amzn_index] == 0.10)\n",
        "\n",
        "tsla_index = ef.tickers.index(\"TSLA\")\n",
        "ef.add_constraint(lambda w: w[tsla_index] <= 0.05)\n",
        "\n",
        "ef.add_constraint(lambda w: w[10] >= 0.05)\n",
        "\n",
        "ef.max_sharpe()\n",
        "weights = ef.clean_weights()"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 76,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "pZAu8ypG9nzL",
        "outputId": "2a3703a8-bbd0-468d-f0c6-25be50f7b0c7"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "OrderedDict([('ACN', 0.17008),\n",
              "             ('AMZN', 0.1),\n",
              "             ('COST', 0.05561),\n",
              "             ('DIS', 0.0),\n",
              "             ('F', 0.0),\n",
              "             ('GILD', 0.06237),\n",
              "             ('JPM', 0.0),\n",
              "             ('KO', 0.04439),\n",
              "             ('LUV', 0.0232),\n",
              "             ('MA', 0.38482),\n",
              "             ('MSFT', 0.05),\n",
              "             ('PFE', 0.02564),\n",
              "             ('TSLA', 0.05),\n",
              "             ('UNH', 0.0339),\n",
              "             ('XOM', 0.0)])"
            ]
          },
          "execution_count": 76,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 77,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 575
        },
        "id": "izbZQ6-G9nzL",
        "outputId": "1aafb3d3-a32b-469e-e702-6044c7f54116"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 720x720 with 1 Axes>"
            ]
          },
          "metadata": {},
          "output_type": "display_data"
        }
      ],
      "source": [
        "pd.Series(weights).plot.pie(figsize=(10,10));"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "kGa9xMQ19nzM"
      },
      "source": [
        "We can immediately see that our explicit constraints were satisfied, and can check all the sector constraints as follows:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 78,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "JtA8KzWp9nzM",
        "outputId": "cd007325-fa24-4f41-f8fa-3d149ae7fc23"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Consumer Discretionary: 0.100\n",
            "Financial Services: 0.385\n",
            "Misc: 0.170\n",
            "Consumer Staples: 0.100\n",
            "Tech: 0.050\n",
            "Energy: 0.000\n",
            "Aerospace: 0.023\n",
            "Auto: 0.050\n",
            "Healthcare: 0.122\n",
            "Media: 0.000\n"
          ]
        }
      ],
      "source": [
        "# O(N^2) loop not a good idea in a coding interview :)\n",
        "for sector in set(sector_mapper.values()):\n",
        "    total_weight = 0\n",
        "    for t,w in weights.items():\n",
        "        if sector_mapper[t] == sector:\n",
        "            total_weight += w\n",
        "    print(f\"{sector}: {total_weight:.3f}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "qOZ-z4AK9nzM"
      },
      "source": [
        "## Maximise return for a given risk, with L2 regularisation\n",
        "\n",
        "Let's imagine that we've put a lot of thought into our risk tolerance, and have decided that we can't accept anything more than 15% volatility. We can use PyPortfolioOpt to construct a portfolio that maximises return for a given risk (with the same caveats about expected returns)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 79,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "sKantkrg9nzM",
        "outputId": "3b60679f-80ef-4ec7-e029-989ef9d27f14"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "OrderedDict([('ACN', 0.0),\n",
              "             ('AMZN', 0.18686),\n",
              "             ('COST', 0.1),\n",
              "             ('DIS', 0.0),\n",
              "             ('F', 0.0),\n",
              "             ('GILD', 0.0642),\n",
              "             ('JPM', 0.0),\n",
              "             ('KO', 0.0),\n",
              "             ('LUV', 0.0),\n",
              "             ('MA', 0.44753),\n",
              "             ('MSFT', 0.05),\n",
              "             ('PFE', 0.0),\n",
              "             ('TSLA', 0.15),\n",
              "             ('UNH', 0.00141),\n",
              "             ('XOM', 0.0)])"
            ]
          },
          "execution_count": 79,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "ef = EfficientFrontier(mu, S)\n",
        "ef.add_sector_constraints(sector_mapper, sector_lower, sector_upper)\n",
        "ef.efficient_risk(target_volatility=0.15)\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 80,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "46ylv28y9nzM",
        "outputId": "de8f0548-437e-4997-cc46-d927d5f61df2"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "8/15 tickers have zero weight\n"
          ]
        }
      ],
      "source": [
        "num_small = len([k for k in weights if weights[k] <= 1e-4])\n",
        "print(f\"{num_small}/{len(ef.tickers)} tickers have zero weight\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 81,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "3HWpBJxZ9nzM",
        "outputId": "cae10c97-978e-40ee-8dd5-796d9635f53f"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Expected annual return: 27.5%\n",
            "Annual volatility: 15.0%\n",
            "Sharpe Ratio: 1.70\n"
          ]
        }
      ],
      "source": [
        "ef.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "sFdT8Xar9nzN"
      },
      "source": [
        "While this portfolio seems like it meets our objectives, we might be worried by the fact that a lot of the tickers have been assigned zero weight. In effect, the optimizer is \"overfitting\" to the data you have provided -- you are much more likely to get better results by enforcing some level of diversification. One way of doing this is to use **L2 regularisation** – essentially, adding a penalty on the number of near-zero weights."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 82,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "wiaa_L2u9nzN",
        "outputId": "0adbf717-faaa-4142-9fe3-6ca9368cc23f"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "OrderedDict([('ACN', 0.04658),\n",
              "             ('AMZN', 0.20432),\n",
              "             ('COST', 0.08843),\n",
              "             ('DIS', 0.01432),\n",
              "             ('F', 0.0),\n",
              "             ('GILD', 0.0832),\n",
              "             ('JPM', 0.04714),\n",
              "             ('KO', 0.01157),\n",
              "             ('LUV', 0.03085),\n",
              "             ('MA', 0.23886),\n",
              "             ('MSFT', 0.05),\n",
              "             ('PFE', 0.0),\n",
              "             ('TSLA', 0.15),\n",
              "             ('UNH', 0.03473),\n",
              "             ('XOM', 0.0)])"
            ]
          },
          "execution_count": 82,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "from pypfopt import objective_functions\n",
        "\n",
        "# You must always create a new efficient frontier object\n",
        "ef = EfficientFrontier(mu, S)\n",
        "ef.add_sector_constraints(sector_mapper, sector_lower, sector_upper)\n",
        "ef.add_objective(objective_functions.L2_reg, gamma=0.1)  # gamma is the tuning parameter\n",
        "ef.efficient_risk(0.15)\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 83,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "G0ZO5l4D9nzN",
        "outputId": "aefa431d-90b2-493b-8232-8dc8c8213212"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "3/15 tickers have zero weight\n"
          ]
        }
      ],
      "source": [
        "num_small = len([k for k in weights if weights[k] <= 1e-4])\n",
        "print(f\"{num_small}/{len(ef.tickers)} tickers have zero weight\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "n8yo6ey19nzN"
      },
      "source": [
        "We can tune the value of gamma to choose the number of nonzero tickers. Larger gamma pulls portfolio weights towards an equal allocation."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 84,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "hIdHgQnE9nzO",
        "outputId": "76b74cec-dbad-4278-ad5c-6a3bb99b404d"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "OrderedDict([('ACN', 0.05538),\n",
              "             ('AMZN', 0.12987),\n",
              "             ('COST', 0.06147),\n",
              "             ('DIS', 0.06366),\n",
              "             ('F', 0.06115),\n",
              "             ('GILD', 0.07939),\n",
              "             ('JPM', 0.07801),\n",
              "             ('KO', 0.03853),\n",
              "             ('LUV', 0.06535),\n",
              "             ('MA', 0.08213),\n",
              "             ('MSFT', 0.07096),\n",
              "             ('PFE', 0.04078),\n",
              "             ('TSLA', 0.08885),\n",
              "             ('UNH', 0.06216),\n",
              "             ('XOM', 0.0223)])"
            ]
          },
          "execution_count": 84,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "ef = EfficientFrontier(mu, S)\n",
        "ef.add_sector_constraints(sector_mapper, sector_lower, sector_upper)\n",
        "ef.add_objective(objective_functions.L2_reg, gamma=1)  # gamma is the tuning parameter\n",
        "ef.efficient_risk(0.15)\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 85,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 575
        },
        "id": "p0DzMHim9nzO",
        "outputId": "baaaab0c-4bee-4883-c0fb-70b4d650ef90"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 720x720 with 1 Axes>"
            ]
          },
          "metadata": {},
          "output_type": "display_data"
        }
      ],
      "source": [
        "pd.Series(weights).plot.pie(figsize=(10, 10));"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 86,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "zFLNfMLr9nzO",
        "outputId": "69c1cead-6233-465a-a3c3-6c5def23d624"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Expected annual return: 24.7%\n",
            "Annual volatility: 14.8%\n",
            "Sharpe Ratio: 1.53\n"
          ]
        }
      ],
      "source": [
        "ef.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "wggcvvSR9nzO"
      },
      "source": [
        "The resulting portfolio still has a volatility of less than our 15% limit. It's in-sample Sharpe ratio has gone down, but this portfolio is a lot more robust for actual investment."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Q1r-Z6ws9nzO"
      },
      "source": [
        "## Minimise risk for a given return, market-neutral\n",
        "\n",
        "We may instead be in the situation where we have a certain required rate of return (maybe we are a pension fund that needs 7% return a year), but would like to minimise risk. Additionally, suppose we would like our portfolio to be market neutral, in the sense that it is equally exposed to the long and short sides.  "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 87,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "XB4Cw8at9nzO",
        "outputId": "26404432-1324-435e-cde0-c28a242a571e"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "OrderedDict([('ACN', -0.03775),\n",
              "             ('AMZN', 0.22059),\n",
              "             ('COST', -0.06087),\n",
              "             ('DIS', -0.00219),\n",
              "             ('F', -0.00302),\n",
              "             ('GILD', 0.04782),\n",
              "             ('JPM', 0.04736),\n",
              "             ('KO', -0.1412),\n",
              "             ('LUV', 0.00141),\n",
              "             ('MA', 0.06322),\n",
              "             ('MSFT', 0.02031),\n",
              "             ('PFE', -0.08583),\n",
              "             ('TSLA', 0.09499),\n",
              "             ('UNH', -0.00931),\n",
              "             ('XOM', -0.15554)])"
            ]
          },
          "execution_count": 87,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "# Must have no weight bounds to allow shorts\n",
        "ef = EfficientFrontier(mu, S, weight_bounds=(None, None))\n",
        "ef.add_objective(objective_functions.L2_reg)\n",
        "ef.efficient_return(target_return=0.07, market_neutral=True)\n",
        "weights = ef.clean_weights()\n",
        "weights"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 88,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "Uf3oUKFP9nzO",
        "outputId": "aa726cf0-1200-4fa9-f61d-ca5807679a34"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Expected annual return: 7.0%\n",
            "Annual volatility: 10.6%\n",
            "Sharpe Ratio: 0.47\n"
          ]
        }
      ],
      "source": [
        "ef.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 89,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 374
        },
        "id": "4rrQKk1Q9nzP",
        "outputId": "95a52da6-37ed-4dad-cd5b-2701affa6695"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 720x432 with 1 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          },
          "output_type": "display_data"
        }
      ],
      "source": [
        "pd.Series(weights).plot.barh(figsize=(10,6));"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 90,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "YwR1iKqv9nzP",
        "outputId": "478e0b8b-c1ed-4826-a1bc-1ad928927123"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Net weight: -0.00\n"
          ]
        }
      ],
      "source": [
        "print(f\"Net weight: {sum(weights.values()):.2f}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "PBvVeqtm9nzP"
      },
      "source": [
        "## Efficient semi-variance optimization\n",
        "\n",
        "In this example, we will minimise the portfolio semivariance (i.e downside volatility) subject to a return constraint (target 20%).\n",
        "\n",
        "There are actually two ways of doing this in PyPortfolioOpt. The first is the \"intuitive\" way. We compute a semicovariance matrix, and pass this into `EfficientFrontier` (just like we would do for the exponential cov matrix or the Ledoit-Wolf shrunk matrix)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 91,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 0
        },
        "id": "8FsS5Yqu9nzP",
        "outputId": "94948fd4-598a-4fa7-a41a-371fbda43f43"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 432x288 with 2 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          },
          "output_type": "display_data"
        }
      ],
      "source": [
        "semicov = risk_models.semicovariance(prices, benchmark=0)\n",
        "plotting.plot_covariance(semicov);"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 92,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "cK0NfwQ69nzP",
        "outputId": "16b22337-b5ac-42cc-fe4c-8543d96275fd"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "OrderedDict([('ACN', 0.25802),\n",
              "             ('AMZN', 0.0),\n",
              "             ('COST', 0.08907),\n",
              "             ('DIS', 0.0),\n",
              "             ('F', 0.0),\n",
              "             ('GILD', 0.0098),\n",
              "             ('JPM', 0.0),\n",
              "             ('KO', 0.1331),\n",
              "             ('LUV', 0.0),\n",
              "             ('MA', 0.30826),\n",
              "             ('MSFT', 0.0),\n",
              "             ('PFE', 0.04855),\n",
              "             ('TSLA', 0.14339),\n",
              "             ('UNH', 0.0),\n",
              "             ('XOM', 0.00981)])"
            ]
          },
          "execution_count": 92,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "ef = EfficientFrontier(mu, semicov)\n",
        "ef.efficient_return(0.2)\n",
        "weights = ef.clean_weights()\n",
        "weights\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 93,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "TUmSYq629nzP",
        "outputId": "62eba498-9e70-41b9-c361-5ad7f7814348"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Expected annual return: 22.5%\n",
            "Annual volatility: 9.0%\n",
            "Sharpe Ratio: 2.29\n"
          ]
        }
      ],
      "source": [
        "ef.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3ZZeruY69nzP"
      },
      "source": [
        "However, this solution is not truly optimal in mean-semivariance space. To do the optimization properly, we must use the `EfficientSemivariance` class. This requires us to first compute the returns and drop NaNs."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 94,
      "metadata": {
        "id": "1qGD5WW69nzQ"
      },
      "outputs": [],
      "source": [
        "returns = expected_returns.returns_from_prices(prices)\n",
        "returns = returns.dropna()"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 95,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "Tyeys0NY9nzQ",
        "outputId": "bf3aa95f-99ab-4410-e9f9-c04e10bf82eb"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Expected annual return: 20.0%\n",
            "Annual semi-deviation: 10.1%\n",
            "Sortino Ratio: 1.78\n"
          ]
        }
      ],
      "source": [
        "from pypfopt import EfficientSemivariance\n",
        "\n",
        "es = EfficientSemivariance(mu, returns)\n",
        "es.efficient_return(0.2)\n",
        "es.portfolio_performance(verbose=True);\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "6g-7u4YA9nzQ"
      },
      "source": [
        "To compare this with the heuristic solution, I will use a quick hack: replacing the `es.weights` with `es.weights` and running `es.portfolio_performance` again. Please don't be encouraged to do this in real life!"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 96,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "6jLzfOCj9nzQ",
        "outputId": "ba8f4fcc-882a-4764-b0b8-e3906677dbd7"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Expected annual return: 22.5%\n",
            "Annual semi-deviation: 14.0%\n",
            "Sortino Ratio: 1.47\n"
          ]
        }
      ],
      "source": [
        "es.weights = ef.weights\n",
        "es.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "FK4C6ah89nzQ"
      },
      "source": [
        "We see that the heuristic method has a significantly lower Sortino ratio, and much higher semivariance."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "yJAcvz899nzQ"
      },
      "source": [
        "## Efficient CVaR optimization\n",
        "\n",
        "In this example, we will find the portfolio that maximises return subject to a CVaR constraint.\n",
        "\n",
        "Before doing this, let's first compute the 95%-CVaR for the max-sharpe portfolio."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 97,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 281
        },
        "id": "x1d3qupJ9nzR",
        "outputId": "daadeac7-706a-445e-fdd6-ab02efc6d005"
      },
      "outputs": [
        {
          "data": {
            "text/html": [
              "\n",
              "  <div id=\"df-0d654402-8300-438c-9404-9cf0713e36aa\">\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>ACN</th>\n",
              "      <th>AMZN</th>\n",
              "      <th>COST</th>\n",
              "      <th>DIS</th>\n",
              "      <th>F</th>\n",
              "      <th>GILD</th>\n",
              "      <th>JPM</th>\n",
              "      <th>KO</th>\n",
              "      <th>LUV</th>\n",
              "      <th>MA</th>\n",
              "      <th>MSFT</th>\n",
              "      <th>PFE</th>\n",
              "      <th>TSLA</th>\n",
              "      <th>UNH</th>\n",
              "      <th>XOM</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>2010-06-30</th>\n",
              "      <td>0.000000</td>\n",
              "      <td>0.005985</td>\n",
              "      <td>-0.014381</td>\n",
              "      <td>-0.024768</td>\n",
              "      <td>0.020243</td>\n",
              "      <td>-0.019731</td>\n",
              "      <td>-0.012142</td>\n",
              "      <td>-0.004172</td>\n",
              "      <td>0.000000</td>\n",
              "      <td>-0.017045</td>\n",
              "      <td>-0.012870</td>\n",
              "      <td>-0.001401</td>\n",
              "      <td>-0.002512</td>\n",
              "      <td>-0.008034</td>\n",
              "      <td>-0.003840</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2010-07-01</th>\n",
              "      <td>-0.009573</td>\n",
              "      <td>0.015559</td>\n",
              "      <td>0.001277</td>\n",
              "      <td>-0.000318</td>\n",
              "      <td>0.048611</td>\n",
              "      <td>-0.004084</td>\n",
              "      <td>-0.013129</td>\n",
              "      <td>-0.001795</td>\n",
              "      <td>-0.010801</td>\n",
              "      <td>0.016651</td>\n",
              "      <td>0.006518</td>\n",
              "      <td>-0.002104</td>\n",
              "      <td>-0.078472</td>\n",
              "      <td>-0.019366</td>\n",
              "      <td>-0.008060</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2010-07-02</th>\n",
              "      <td>-0.008882</td>\n",
              "      <td>-0.016402</td>\n",
              "      <td>-0.012204</td>\n",
              "      <td>-0.003493</td>\n",
              "      <td>-0.027436</td>\n",
              "      <td>0.021383</td>\n",
              "      <td>-0.006929</td>\n",
              "      <td>0.000399</td>\n",
              "      <td>-0.021838</td>\n",
              "      <td>0.000345</td>\n",
              "      <td>0.004750</td>\n",
              "      <td>-0.006324</td>\n",
              "      <td>-0.125683</td>\n",
              "      <td>0.016158</td>\n",
              "      <td>-0.000707</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2010-07-06</th>\n",
              "      <td>0.012388</td>\n",
              "      <td>0.008430</td>\n",
              "      <td>-0.004241</td>\n",
              "      <td>0.010835</td>\n",
              "      <td>-0.011673</td>\n",
              "      <td>-0.002868</td>\n",
              "      <td>0.013954</td>\n",
              "      <td>0.007592</td>\n",
              "      <td>-0.011163</td>\n",
              "      <td>-0.013513</td>\n",
              "      <td>0.023635</td>\n",
              "      <td>0.010608</td>\n",
              "      <td>-0.160938</td>\n",
              "      <td>0.020848</td>\n",
              "      <td>0.015733</td>\n",
              "    </tr>\n",
              "    <tr>\n",
              "      <th>2010-07-07</th>\n",
              "      <td>0.022130</td>\n",
              "      <td>0.030620</td>\n",
              "      <td>0.005370</td>\n",
              "      <td>0.044767</td>\n",
              "      <td>0.042323</td>\n",
              "      <td>0.004889</td>\n",
              "      <td>0.050097</td>\n",
              "      <td>0.020623</td>\n",
              "      <td>0.062088</td>\n",
              "      <td>0.037694</td>\n",
              "      <td>0.020151</td>\n",
              "      <td>0.023093</td>\n",
              "      <td>-0.019243</td>\n",
              "      <td>0.010731</td>\n",
              "      <td>0.016882</td>\n",
              "    </tr>\n",
              "  </tbody>\n",
              "</table>\n",
              "</div>\n",
              "      <button class=\"colab-df-convert\" onclick=\"convertToInteractive('df-0d654402-8300-438c-9404-9cf0713e36aa')\"\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-0d654402-8300-438c-9404-9cf0713e36aa 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-0d654402-8300-438c-9404-9cf0713e36aa');\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": [
              "                 ACN      AMZN      COST  ...      TSLA       UNH       XOM\n",
              "Date                                      ...                              \n",
              "2010-06-30  0.000000  0.005985 -0.014381  ... -0.002512 -0.008034 -0.003840\n",
              "2010-07-01 -0.009573  0.015559  0.001277  ... -0.078472 -0.019366 -0.008060\n",
              "2010-07-02 -0.008882 -0.016402 -0.012204  ... -0.125683  0.016158 -0.000707\n",
              "2010-07-06  0.012388  0.008430 -0.004241  ... -0.160938  0.020848  0.015733\n",
              "2010-07-07  0.022130  0.030620  0.005370  ... -0.019243  0.010731  0.016882\n",
              "\n",
              "[5 rows x 15 columns]"
            ]
          },
          "execution_count": 97,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "returns = expected_returns.returns_from_prices(prices).dropna()\n",
        "returns.head()"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 98,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "4RdDFhAt9nzR",
        "outputId": "76d8a6e4-c2b9-4c39-e525-e7b8cf2444e7"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Expected annual return: 25.3%\n",
            "Annual volatility: 12.9%\n",
            "Sharpe Ratio: 1.81\n"
          ]
        }
      ],
      "source": [
        "ef = EfficientFrontier(mu, S)\n",
        "ef.max_sharpe()\n",
        "weight_arr = ef.weights\n",
        "ef.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 99,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 265
        },
        "id": "29a0FtJY9nzR",
        "outputId": "a053e96e-e6fc-4c93-92ce-2cd3373ae112"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 432x288 with 1 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          },
          "output_type": "display_data"
        }
      ],
      "source": [
        "# Compute CVaR\n",
        "portfolio_rets = (returns * weight_arr).sum(axis=1)\n",
        "portfolio_rets.hist(bins=50);"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 100,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "8LLBZ15l9nzR",
        "outputId": "5f81ae25-bf09-495e-c389-9df5890717d0"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "VaR: -2.13%\n",
            "CVaR: -3.24%\n"
          ]
        }
      ],
      "source": [
        "# VaR\n",
        "var = portfolio_rets.quantile(0.05)\n",
        "cvar = portfolio_rets[portfolio_rets <= var].mean()\n",
        "print(\"VaR: {:.2f}%\".format(100*var))\n",
        "print(\"CVaR: {:.2f}%\".format(100*cvar))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "PxHWPjSz9nzR"
      },
      "source": [
        "This value of the CVaR means that our average loss on the worst 5% of days will be -3.35%. Let's say that this were beyond our comfort zone (for a \\\\$100,000 portfolio, this would mean losing \\\\$3350 in a day).\n",
        "\n",
        "Let's firstly construct the portfolio with the minimum CVaR:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 101,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "bQ79Y0Gr9nzR",
        "outputId": "b92a041c-9e59-45ba-8cab-ac427d889126"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Expected annual return: 18.1%\n",
            "Conditional Value at Risk: 2.11%\n"
          ]
        }
      ],
      "source": [
        "from pypfopt import EfficientCVaR\n",
        "\n",
        "ec = EfficientCVaR(mu, returns)\n",
        "ec.min_cvar()\n",
        "ec.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "hVEjdNOv9nzS"
      },
      "source": [
        "We have significantly reduced the CVaR, but at the cost of a large reduction in returns. We can use `efficient_risk` to maximise the return for a target risk. Let's say that a 2.5% CVaR is acceptable."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 102,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "onq8FVDr9nzS",
        "outputId": "32b82ef5-e86c-414d-b965-d44e27813ff3"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Expected annual return: 25.0%\n",
            "Conditional Value at Risk: 2.50%\n"
          ]
        }
      ],
      "source": [
        "from pypfopt import EfficientCVaR\n",
        "\n",
        "ec = EfficientCVaR(mu, returns)\n",
        "ec.efficient_risk(target_cvar=0.025)\n",
        "ec.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "6wjVOkqd9nzS"
      },
      "source": [
        "We now have similar returns to before (24.7% vs 25.8%), but with a lower tail risk (2.50% CVaR vs 3.35%). "
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "LJ_DCIo19nzS"
      },
      "source": [
        "## Plotting - Unconstrained\n",
        "\n",
        "To plot the unconstrained efficient frontier, it is easiest to use the critical line algorithm. "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 103,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "n0UWSKGj9nzS",
        "outputId": "08a6de2a-17e4-4f70-92ea-fe86a9c8f442"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Expected annual return: 25.1%\n",
            "Annual volatility: 12.8%\n",
            "Sharpe Ratio: 1.81\n"
          ]
        }
      ],
      "source": [
        "from pypfopt import CLA, plotting\n",
        "\n",
        "cla = CLA(mu, S)\n",
        "cla.max_sharpe()\n",
        "cla.portfolio_performance(verbose=True);"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 104,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 297
        },
        "id": "Sk2eFFZ79nzS",
        "outputId": "6f967d10-32c4-4f83-ecac-aed15aa8180a"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 432x288 with 1 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          },
          "output_type": "display_data"
        }
      ],
      "source": [
        "ax = plotting.plot_efficient_frontier(cla, showfig=False)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "aURS39QR9nzS"
      },
      "source": [
        "## Plotting - Constrained"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "2xPJH-s69nzT"
      },
      "source": [
        "In this example, we will plot the efficient frontier corresponding to portfolios with a constraint on exposure to MSFT, AMZN, and TSLA (e.g maybe we want to avoid big tech)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 105,
      "metadata": {
        "id": "OavRfyqJ9nzT"
      },
      "outputs": [],
      "source": [
        "import cvxpy as cp\n",
        "\n",
        "mu = expected_returns.capm_return(prices)\n",
        "S = risk_models.CovarianceShrinkage(prices).ledoit_wolf()\n",
        "\n",
        "ef = EfficientFrontier(mu, S,)\n",
        "big_tech_indices = [t in {\"MSFT\", \"AMZN\", \"TSLA\"} for t in tickers]\n",
        "ef.add_constraint(lambda w: cp.sum(w[big_tech_indices]) <= 0.3)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "iPJ5mK8p9nzT"
      },
      "source": [
        "As per the docs, *before* we call any optimization function, we should pass this to the plotting module:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 106,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 297
        },
        "id": "BOehDOq19nzT",
        "outputId": "171cb51c-a5c4-402a-e17e-86d1dda072b1"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 432x288 with 1 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          },
          "output_type": "display_data"
        }
      ],
      "source": [
        "ax = plotting.plot_efficient_frontier(ef, ef_param=\"risk\", \n",
        "                                      ef_param_range=np.linspace(0.12, 0.4, 50), \n",
        "                                      showfig=False);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ht1M5kIo9nzT"
      },
      "source": [
        "## Complex plots\n",
        "\n",
        "The `plotting` module allows you to pass in an `ax`, on top of which the plots are added. This allows you to build complex plots. \n",
        "\n",
        "In this example, we will plot the efficient frontier as well as 10,000 simulated portfolios. \n",
        "\n",
        "To generate the simulated portfolios, we will sample random weights from the Dirichlet distribution (these are already normalised):"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 107,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "esHxc73V9nzT",
        "outputId": "decb7120-4d2e-49f3-f7d9-fcb5b78cdcce"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Sample portfolio returns: [0.23543194 0.23507301 0.22410885 ... 0.22769761 0.21848404 0.24754775]\n",
            "Sample portfolio volatilities: 0       0.149765\n",
            "1       0.159008\n",
            "2       0.141414\n",
            "3       0.169300\n",
            "4       0.151457\n",
            "          ...   \n",
            "9995    0.154257\n",
            "9996    0.152824\n",
            "9997    0.158934\n",
            "9998    0.144248\n",
            "9999    0.160539\n",
            "Length: 10000, dtype: float64\n"
          ]
        }
      ],
      "source": [
        "n_samples = 10000\n",
        "w = np.random.dirichlet(np.ones(len(mu)), n_samples)\n",
        "rets = w.dot(mu)\n",
        "stds = np.sqrt((w.T * (S @ w.T)).sum(axis=0))\n",
        "sharpes = rets / stds\n",
        "\n",
        "print(\"Sample portfolio returns:\", rets)\n",
        "print(\"Sample portfolio volatilities:\", stds)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Ad_x63489nzT"
      },
      "source": [
        "Note that the above code is equivalent to generating samples via a for loop (just more efficient)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 108,
      "metadata": {
        "id": "H3nL43aM9nzT"
      },
      "outputs": [],
      "source": [
        "# mus = []\n",
        "# stds = []\n",
        "# sharpes = []\n",
        "# for _ in range(10000):\n",
        "#     w = np.random.dirichlet(np.ones(len(mu)))\n",
        "#     # w = np.random.rand(len(mu))\n",
        "#     # w /= w.sum()\n",
        "#     ret = mu.dot(w)\n",
        "#     std = np.sqrt(w.dot(S @ w))\n",
        "#     mus.append(ret)\n",
        "#     stds.append(std)\n",
        "#     sharpes.append(ret / std)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 109,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 297
        },
        "id": "WjCjkC9p9nzU",
        "outputId": "386b35b3-75fd-4186-8f65-f16317246965"
      },
      "outputs": [
        {
          "data": {
            "image/png": "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",
            "text/plain": [
              "<Figure size 432x288 with 1 Axes>"
            ]
          },
          "metadata": {
            "needs_background": "light"
          },
          "output_type": "display_data"
        }
      ],
      "source": [
        "# Plot efficient frontier with Monte Carlo sim\n",
        "ef = EfficientFrontier(mu, S)\n",
        "\n",
        "fig, ax = plt.subplots()\n",
        "plotting.plot_efficient_frontier(ef, ax=ax, show_assets=False)\n",
        "\n",
        "# Find and plot the tangency portfolio\n",
        "ef2 = EfficientFrontier(mu, S)\n",
        "ef2.max_sharpe()\n",
        "ret_tangent, std_tangent, _ = ef2.portfolio_performance()\n",
        "\n",
        "# Plot random portfolios\n",
        "ax.scatter(stds, rets, marker=\".\", c=sharpes, cmap=\"viridis_r\")\n",
        "\n",
        "# Format\n",
        "ax.set_title(\"Efficient Frontier with random portfolios\")\n",
        "ax.legend()\n",
        "plt.tight_layout()\n",
        "plt.show()\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 109,
      "metadata": {
        "id": "dZ0tR7Lt9nzU"
      },
      "outputs": [],
      "source": []
    }
  ],
  "metadata": {
    "colab": {
      "collapsed_sections": [
        "PBvVeqtm9nzP"
      ],
      "name": "2-Mean-Variance-Optimisation.ipynb",
      "provenance": []
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}