black_litterman_model.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "source": [
    "# How to make a winning portfolio with the epic Black-Litterman approach\n",
    "\n",
    "The Black-Litterman model is a mathematical tool for portfolio allocation. It was developed in 1990 by Fischer Black and Robert Litterman at Goldman Sachs.\n",
    "\n",
    "The Black-Litterman model takes a Bayesian approach to asset allocation. Specifically, it combines a prior estimate of returns with views on certain assets, to produce a posterior estimate of expected returns.\n",
    "\n",
    "It starts with an asset allocation based on the equilibrium assumption, which suggests that assets will perform in the future as they have in the past. The model then modifies this initial allocation by considering the investor’s views on future asset performance.\n",
    "\n",
    "Black-Litterman incorporates subjective views into market equilibrium returns providing a more personalized approach to asset allocation."
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "bd5e6a344e0236cb"
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "outputs": [],
   "source": [
    "# Imports and set up\n",
    "\n",
    "# We’ll use PyPortfolioOpt to construct the Black-Litterman portfolio weights. We’ll also use the OpenBB SDK for data and seaborn for plotting.\n",
    "\n",
    "import numpy as np\n",
    "\n",
    "from pypfopt.black_litterman import BlackLittermanModel\n",
    "from pypfopt.efficient_frontier import EfficientFrontier\n",
    "from pypfopt import risk_models\n",
    "from pypfopt import plotting\n",
    "\n",
    "from openbb_terminal.sdk import openbb\n",
    "import seaborn as sns\n",
    "sns.set_theme()\n",
    "# Let’s grab some prices\n",
    "\n",
    "prices = openbb.economy.index([\"AAPL\", \"BBY\", \"BAC\", \"SBUX\", \"T\"])"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2023-08-06T11:10:13.553362Z",
     "start_time": "2023-08-06T11:10:10.150612Z"
    }
   },
   "id": "5ecc6965fae1e4e"
  },
  {
   "cell_type": "markdown",
   "source": [
    "# Set up the Black-Litterman model\n",
    "\n",
    "The Black-Litterman model supports absolute or relative views. Absolute views are statements like: “AAPL will return 20%” or “BBY will drop 40%”. Relative views, on the other hand, are statements like “GOOG will outperform FB by 3%.”"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "f9d386b662c8bc77"
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "outputs": [],
   "source": [
    "# This issue covers absolute views.\n",
    "\n",
    "viewdict = {\n",
    "    \"AAPL\": 0.20, \n",
    "    \"BBY\": 0.25,\n",
    "    \"BAC\": 0.10,\n",
    "    \"SBUX\": 0.2,\n",
    "    \"T\": 0.15\n",
    "}\n",
    "\n",
    "cov_matrix = risk_models.sample_cov(prices)\n",
    "# These views are passed to PyPortfolioOpt in the form of a Python dictionary. Each symbol is mapped to an absolute return. Then, we create a sample covariance matrix."
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2023-08-06T11:10:13.559425Z",
     "start_time": "2023-08-06T11:10:13.554539Z"
    }
   },
   "id": "809f089410b62a91"
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "outputs": [
    {
     "data": {
      "text/plain": "<AxesSubplot:xlabel='Volatility', ylabel='Return'>"
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": "<Figure size 640x480 with 1 Axes>",
      "image/png": "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G2taW0+9Xo+XXnoJL730EuLi4uzW8xx1fE2Bzn2OAq2v6blz5wAAgiDgrbfewr/+9S8YDAb8+c9/RllZGc/TdsCeNydpHP40Go02Q6EGgwGenp7N7icIAt5//30sXboUzz77LB577DHrum3btsFsNsPLywsAkJycjMLCQqxcuRLp6ent9E5cR1trCgC9evUCACxevBjDhw/H7t27MXz4cOvxrtaS43UUjq7pAw88gA8//BAGgwE+Pj4AgKSkJNTU1GDp0qWYPn16h+7ZaG09//73vyM+Ph4PP/xwk8fz8PCwHu9qPEfbXlMAnfocBVpf0wEDBuCXX36Bv78/RCIRgIbv+xEjRmDjxo0YN26c9XhX60znqaN17DPQhTV2R6vVapvlarUaoaGhTe5TX1+Pl19+GcuWLcPs2bPxwgsv2KxXKBTW4NYoMTGx03RLt7amOTk5+P77722WhYaGws/PDyUlJfDz84NSqWzV16ijcXRNgYa/vht/KTZKTEyEXq9HVVWVA1vvelpbzy+++AI///wz+vbti759++Kpp54CAIwePRrLli3jOQrH1xTo3Oco0LbfTwEBAdbgBgCenp6Iioriz9J2wvDmJMnJyfD29saBAwesy7RaLTIzM63XsF1r1qxZ+Oqrr/DOO+9g0qRJNuu0Wi0GDhyIjRs32iw/efIkunXr5vD2u6LW1vTnn3/GjBkzrDd8AEBeXh4qKirQpUsXiEQi9OvXD7/++qvNfgcOHMCAAQPa7424EEfXVBAE3H777TbXwAEN52lwcDD8/f3b7824gNbWc9euXdi2bRs2b96MzZs34+9//zuAhutdH374YZ6jcHxNO/s5CrS+pp9//jkGDRoEvV5vXVZTU4NLly6ha9euPE/bg3Nvdu3c3n33XWHgwIHCnj17bObRMRqNgslkEtRqtXVqkC+++EJITEwUPvroI7t5dBq3mT59ujB06FDh+++/Fy5evCgsX75c6N69u/DDDz84823eVK2paUVFhTBs2DAhIyNDOHv2rHDw4EHh/vvvF9LT061zE/34449C9+7dhVWrVgnnz58X/vnPfwqpqamdam4iR9f07bffFvr06SNs375dyM3NFT777DMhNTVV+Pzzz535Nm+a1tTzWvv377eb1oLnqONr2tnPUUFoXU0LCwuFAQMGCNOmTRPOnj0rnDhxQpg0aZJw++23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\n"
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# These views are passed to PyPortfolioOpt in the form of a Python dictionary. Each symbol is mapped to an absolute return. Then, we create a sample covariance matrix.\n",
    "\n",
    "# Finally, we’re ready to set up the Black-Litterman model.\n",
    "\n",
    "bl = BlackLittermanModel(\n",
    "cov_matrix,\n",
    "absolute_views=viewdict,\n",
    "pi=\"equal\"\n",
    ")\n",
    "\n",
    "rets = bl.bl_returns()\n",
    "ef = EfficientFrontier(rets, cov_matrix)\n",
    "weights = bl.bl_weights()\n",
    "\n",
    "plotting.plot_efficient_frontier(ef, show_tickers=True)"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2023-08-06T11:10:35.437097Z",
     "start_time": "2023-08-06T11:10:35.065787Z"
    }
   },
   "id": "45b231e952d44db2"
  },
  {
   "cell_type": "markdown",
   "source": [
    "The pi argument is the estimate of the priors. You can think of the prior as the “default” estimate, in the absence of any information. Black and Litterman provide the insight that a natural choice for this prior is the market’s estimate of the return, which is embedded into the market capitalization of the asset.\n",
    "\n",
    "We can use whatever priors we want. PyPortfolioOpt has a built-in option equal-weighted priors, so we’ll use that.\n",
    "\n",
    "From there, we generate the returns and build an efficient frontier using the default return optimization."
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "e668a8cd05efcb6f"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [],
   "metadata": {
    "collapsed": false
   },
   "id": "6503f89de16ae92b"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}