robo-advisor.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<h1 style=\"color:#239B56;\">Robo-Advisor</h1>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview:\n",
    "\n",
    "We want to create an unusually \"safe\" portfolio. Rather than maximize returns, we want to keep returns as close as possible to zero. In other words, we want to generate the least volatile portfolio given a list of stocks, with the goal of having the ending value be as close as possible to the starting value, given some investment horizon.\n",
    "\n",
    "We will be using Python, with tools such as Pandas, NumPy, Matplotlib, and the AlphaVantage API to gather data, perform quantitative analyses, generate the portfolio, and analyze the results.\n",
    "\n",
    "Table of contents:\n",
    "\n",
    "_____________________________________________________________________________\n",
    "\n",
    "0.0 Imports\n",
    "\n",
    "0.1 Global Variables\n",
    "\n",
    "1. DATA CLEANING\n",
    "\n",
    "    1.1 Read in .csv\n",
    "\n",
    "    1.2 Collect and Filter Data\n",
    "\n",
    "2. CHOOSING THE STOCKS\n",
    "\n",
    "    2.1 Returns DataFrame\n",
    "\n",
    "    2.2 The Points System\n",
    "\n",
    "3. CREATING THE OPTIMAL PORTFOLIO\n",
    "\n",
    "    3.1 Stock Betas\n",
    "\n",
    "    3.2 Weight Generation\n",
    "\n",
    "    3.3 Monte Carlo Simulation\n",
    "\n",
    "    3.4 Final Portfolio\n",
    "\n",
    "4. ANALYSIS AND SANITY CHECKS\n",
    "\n",
    "    4.1 Value and Weights Check\n",
    "\n",
    "    4.2 Expected Returns Visualization\n",
    "\n",
    "    4.3 Returns Check With Low Volatility ETF Comparison\n",
    "\n",
    "    4.4 Graphed Returns Check With Additional Data and Low Volatility ETF Comparison\n",
    "\n",
    "5. PORTFOLIO TO CSV, CONSIDERATIONS, AND CONCLUSION\n",
    "\n",
    "    5.1 Output Final Information to .csv File\n",
    "\n",
    "    5.2 Considerations\n",
    "\n",
    "    5.3 Conclusion\n",
    "\n",
    "6. REFERENCES\n",
    "\n",
    "_____________________________________________________________________________\n",
    "\n",
    "Here's a quick overview of the architecture of this script:\n",
    "\n",
    "Data cleaning - Removing tickers that do not fit certain criteria (chosen by the user).\n",
    "\n",
    "Choosing the stocks - Picking the tickers which we will utilize in the final portfolio (based on a volatility and correlation metric).\n",
    "\n",
    "Creating the portfolio - Running a Monte Carlo simulation to generate the final portfolio, which has an expected return close to 0%. We will calculate expected return based on a <b>Multi-Security Capital Asset # Model (MSCAPM)</b> (below).\n",
    "\n",
    "![MSCAPM](pub/#_model.jpg)\n",
    "\n",
    "Analysis and sanity checks - Ensuring that the capital has been allocated correctly, as well as showing that the portfolio is indeed expected to return close to 0% over a given period of time, among other characteristics. In this section, we also compare our generated portfolio to a popular low-volatility ETF.\n",
    "\n",
    "Objective assumptions:\n",
    "\n",
    "- Fractional shares can be purchased\n",
    "- There will be no transaction costs when buying stocks.\n",
    "- Once the portfolio is set, it cannot be changed.\n",
    "- Dividends will be ignored\n",
    "\n",
    "Note: The term 'stock' and 'ticker' are often used interchangeably in this project. They both generally refer to either the string representing a stock or the underlying stock itself."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why MSCAPM?\n",
    "\n",
    "The Multi-Security Capital Asset # Model (MSCAPM for short) gives the expected return for a portfolio of assets relational to its risk with the market.\n",
    "\n",
    "One of the primary assumptions we make when deriving the portfolio is that <b>the overall market will be a good indicator for its price movements.</b> This is because we deliberately diversify the portfolio. We use this information to then attempt to offset market movements, allowing the portfolio to hover around 0% returns.\n",
    "\n",
    "With this assumption in mind, we decided that the MSCAPM was the best # model to use for two main reasons:\n",
    "\n",
    "1. CAPM is a tested and proven model.\n",
    "\n",
    "2. Including beta as a factor allows us to imply both correlation and volatility in one variable, and will bias the allocation of capital towards stocks that have lower volatility, and/or stocks that are likely to 'offset' the volatility of other stocks in the portfolio.\n",
    "\n",
    "Some issues with other viable methods:\n",
    "\n",
    "1. Picking the portfolio with the lowest volatility.\n",
    "- Doesn't consider correlation strongly. With this model, it's possible for the correlation between securities to be high, which could cause the portfolio's value to trend in one direction over time, despite low volatility. Problematic in the long-term.\n",
    "\n",
    "2. Picking the portfolio with the lowest expected return (by combining the weighted expected return of each security).\n",
    "- Doesn't consider volatility heavily. The magnitude of volatility may be strong. Problematic in the short-term."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 0.0 Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 225,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import display, Math, Latex\n",
    "\n",
    "import pandas as pd\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "from datetime import datetime\n",
    "from dateutil.relativedelta import relativedelta\n",
    "\n",
    "import threading\n",
    "from queue import Queue\n",
    "from random import uniform\n",
    "import random\n",
    "from typing import List\n",
    "\n",
    "import sys\n",
    "\n",
    "from modules.alphawrap import Stock\n",
    "import modules.alphawrap as aw"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 0.1 Global Variables"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 226,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MODIFIABLE #\n",
    "\n",
    "# AlphaVantage key\n",
    "KEY                             = ''\n",
    "aw.set_global_key(KEY)\n",
    "\n",
    "# Variables for filtering\n",
    "minimum_monthly_trading_days    = 20 # For a valid month in volume calculation\n",
    "minimum_volume                  = 200_000 # Monthly, for valid months\n",
    "required_denomination           = 'USD'\n",
    "\n",
    "# Maximum number of stocks allowed in the portfolio\n",
    "max_tickers                     = 25\n",
    "\n",
    "# Dates for data references made when looking at statistics like volatility, correlation, and beta\n",
    "#  \"Portfolio selection analysis period\"\n",
    "start                           = '2023-01-01'\n",
    "end                             = '2023-05-02'\n",
    "\n",
    "# Dates for volume calculation\n",
    "vol_date_s                      = '2022-08-01'\n",
    "vol_date_e                      = '2023-02-01' # Must be the month after the last month to be checked\n",
    "\n",
    "capital                         = 500_000 # How much money we have to spend\n",
    "\n",
    "# Lowest and highest percentage of any given security in the portfolio\n",
    "lowest_weight                   = .02\n",
    "highest_weight                  = .12\n",
    "\n",
    "numdays                         = 5 # For expected return (NUMBER OF TRADING DAYS ONLY)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 227,
   "metadata": {},
   "outputs": [],
   "source": [
    "# .csv file of tickers\n",
    "csv_file = \"csv/tickers.csv\"\n",
    "\n",
    "# Retrieve risk-free rate from alphawrap library\n",
    "try:\n",
    "    rf = aw.rf()\n",
    "except:\n",
    "    rf = 0.0383\n",
    "\n",
    "price_date = end # Date of purchase for stocks"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. DATA CLEANING: \n",
    "\n",
    "THE GOAL:\n",
    "\n",
    "• Ignore any tickers that do not reference a valid stock denominated in USD, i.e., we want to only use US-listed stocks.\n",
    "\n",
    "• Only use tickers that reference stocks with an average monthly volume of at least two-hundred thousand shares, as calculated based on a specified time interval. A month is defined as a calendar month. We will drop any month that does not have at least twenty trading days.\n",
    "\n",
    "THE PROCESS:\n",
    "\n",
    "We have two main functions (currency_check and volume_check), running on two separate threads, c and v. These functions are defined recursively; If too many tickers are passed into the function (i.e a list of tickers that is longer than 'max_length_lst' in each function), the function calls on several threads to run the function with smaller, sub-lists. When a small enough quantity of tickers is passed to the function, it will perform the criteria check for the tickers. This allows us to make faster API calls. Valid tickers get passed to the function's respective queue. Finally, the queue is cleared, and tickers that fit both criteria are saved as our list of tickers.\n",
    "\n",
    "Our code checks the tickers for the criteria mentioned,and generates two lists of valid tickers (one for each criterion). As we want stocks that fit both criteria, our final list of (valid) tickers is the intersection of the two lists.\n",
    "\n",
    "Note 1: Initially, we had volume_check and currency_check running asynchronously, and passed very small lists of tickers. Due to the limitations of AlphaVantage (an API that was not initially used for this project), we had to throttle the speed of data cleaning by running the functions in succession and increasing the max number of tickers by up to five-hundred percent.\n",
    "\n",
    "Note 2: Duplicates will be filtered out."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1.1 Read in .csv"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 228,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Make values into a list\n",
    "tickers_csv = pd.read_csv(csv_file)\n",
    "ticker_list = tickers_csv.iloc[:, 0].values.tolist()\n",
    "ticker_list.insert(0, tickers_csv.columns[0]) # Add ticker at [0,0] (column name)\n",
    "ticker_list = [*set(ticker_list)] # Remove duplicates"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1.2 Collect and Filter Data"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We first define our functions (average_volume (for volume_check), currency_check, volume_check)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 229,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Creates a series of months from vol_date_s to vol_date_e (for average_volume)\n",
    "months = list(pd.date_range(vol_date_s, vol_date_e, freq = 'MS').strftime(\"%Y-%m\").tolist())\n",
    "\n",
    "num_months_vol = len(months)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 230,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Consumes a ticker, outputs average volume over valid months\n",
    "def average_volume(ticker):\n",
    "    monthly_volumes = []\n",
    "\n",
    "    tick_obj = Stock(ticker = ticker)\n",
    "\n",
    "    # Custom DataFrame for valid months check\n",
    "    df_days = tick_obj.history(start = vol_date_s, end  = vol_date_e, interval = '1d').dropna()\n",
    "\n",
    "    # Drop months with less than minimum_monthly_trading_days days\n",
    "    for month in range(num_months_vol):\n",
    "        # Filter DataFrame for days only in the specified month\n",
    "        month_data = df_days.filter(like = months[month], axis = 0)\n",
    "\n",
    "        if len(month_data) >= minimum_monthly_trading_days:\n",
    "            # Add the sum of volume for that month\n",
    "            monthly_volumes.append(sum(month_data['Volume'].values.tolist()))\n",
    "        else:\n",
    "            pass\n",
    "\n",
    "    # Calculate average volume\n",
    "    vol_av = np.mean(monthly_volumes)\n",
    "\n",
    "    return(vol_av)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 231,
   "metadata": {},
   "outputs": [],
   "source": [
    "valid_tickers = []\n",
    "currency_valid = []\n",
    "volume_valid = []\n",
    "\n",
    "# Queue variables to store tickers while running async\n",
    "queueC = Queue()\n",
    "queueV = Queue()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 232,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Consumes a list of tickers, checks if the tickers are denominated in 'required_denomination'\n",
    "def currency_check(tickers):\n",
    "    max_length_lst = 35 # Maximum number of tickers that will be accepted by the function, else recursive call\n",
    "\n",
    "    # When there are an appropriate number of tickers in ticker_list, the function performs the currency check\n",
    "    if len(tickers) <= max_length_lst:\n",
    "\n",
    "        # Retrieve currency from each ticker\n",
    "        #  If it is 'required_denomination', it is a valid ticker. Else, we don't care so we set it as nan\n",
    "        for ticker in tickers:\n",
    "            currency = ''\n",
    "            tick_obj = Stock(ticker = ticker)\n",
    "\n",
    "            # Grab currency\n",
    "            try:\n",
    "                currency = tick_obj.info()['Currency']\n",
    "            except:\n",
    "                if currency:\n",
    "                    print(f'{ticker}: Invalid Currency: {currency}')\n",
    "                    continue # Suppress errors\n",
    "                else:\n",
    "                    print(f'{ticker}: Currency not found, ticker or key may be invalid')\n",
    "                    continue # Suppress errors\n",
    "                       \n",
    "            # Check criteria, add to list of valid tickers for currency\n",
    "            if currency == required_denomination:\n",
    "                # Pass our valid tickers to the QueueC (Queue Currency), so that they may be called on later\n",
    "                queueC.put(ticker)\n",
    "            else:\n",
    "                print(f'{ticker}: Invalid currency - {currency}')\n",
    "\n",
    "    # If there are too many tickers in ticker_lst, we run a recursive application of currency_check with \n",
    "    #  num_threads threads, with the arguments being one of num_threads equal parts of 'tickers'.\n",
    "    else:\n",
    "        num_threads = 2\n",
    "\n",
    "        ticker_split = np.array_split(tickers, num_threads)\n",
    "\n",
    "        # Start num_threads threads, add to list.\n",
    "        threads = []\n",
    "        for n in range(num_threads):\n",
    "            c_sub = threading.Thread(target = currency_check, args = (ticker_split[n], ))\n",
    "            c_sub.start()\n",
    "            threads.append(c_sub)\n",
    "\n",
    "        # Wait for threads to finish.\n",
    "        for t in threads:\n",
    "            t.join()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 233,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Consumes a list of tickers, checks if the tickers have an average monthly volume of 'minimum_volume' \n",
    "#  or more for months with 'minimum_monthly_trading_days' or more trading days\n",
    "def volume_check(tickers):\n",
    "    max_length_lst = 35\n",
    "    \n",
    "    # When there are an appropriate number of tickers in ticker_list, the function performs the volume check\n",
    "    if len(tickers) <= max_length_lst:\n",
    "\n",
    "        # Retrieve monthly average volume from each ticker\n",
    "        #  If it is greater than or equal to minimum_volume, it is a valid ticker. Else, we ignore it\n",
    "        for ticker in tickers:\n",
    "            \n",
    "            try:\n",
    "                av_vol = average_volume(ticker = ticker)\n",
    "                if av_vol >= minimum_volume:\n",
    "                    # Pass our valid tickers to the QueueV (Queue Volume), so that they may be called on later\n",
    "                    queueV.put(ticker)\n",
    "                else:\n",
    "                    print(f'{ticker}: Invalid volume - {av_vol}')\n",
    "            except:\n",
    "                pass # Suppress errors\n",
    "\n",
    "    # If there are too many tickers in ticker_lst, we run a recursive application of volume_check with num_threads threads,\n",
    "    #  with the arguments being one of num_threads equal parts of ticker_list\n",
    "    else:\n",
    "        num_threads = 2\n",
    "\n",
    "        ticker_split = np.array_split(tickers, num_threads)\n",
    "\n",
    "        # Start num_threads threads, add to list.\n",
    "        threads = []\n",
    "\n",
    "        for n in range(num_threads):\n",
    "            v_sub = threading.Thread(target = volume_check, args = (ticker_split[n], ))\n",
    "            v_sub.start()\n",
    "            threads.append(v_sub)\n",
    "\n",
    "        # Wait for all threads to finish\n",
    "        for t in threads:\n",
    "            t.join()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now run currency_check and volume_check as described in the beginning of this section. All valid tickers are housed in valid_tickers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 234,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "PSCM: Currency not found, ticker or key may be invalid\n",
      "NAC: Currency not found, ticker or key may be invalid\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "QRMI: Currency not found, ticker or key may be invalid\n",
      "TD.TO: Currency not found, ticker or key may be invalid\n",
      "MON: Currency not found, ticker or key may be invalid\n",
      "PSCM: Invalid volume - 36036.333333333336\n",
      "CIZN: Invalid volume - 114829.83333333333\n",
      "QRMI: Invalid volume - 109015.0\n",
      "CVR: Invalid volume - 49843.666666666664\n",
      "SEB: Invalid volume - 13488.333333333334\n",
      "BRK-A: Invalid volume - 64494.5\n",
      "Stock.history: MON: Something went wrong. Dates may be incorrect or out of range\n",
      "\n",
      "Valid Tickers: ['AAPL', 'ABT', 'ACN', 'ADBE', 'AEE', 'AEP', 'AMZN', 'BA', 'BAC', 'BK', 'BRK-B', 'C', 'CF', 'CMCSA', 'CMS', 'CPB', 'CSCO', 'CVS', 'D', 'ED', 'F', 'GE', 'GILD', 'GM', 'GO', 'GOOG', 'GRMN', 'IBM', 'INFY', 'JPM', 'KO', 'LMT', 'MNSO', 'MS', 'MSFT', 'NOC', 'PG', 'PM', 'REGN', 'ROP', 'SO', 'T', 'TSN', 'TXN', 'UNH', 'UPS', 'VMW', 'VZ']\n"
     ]
    }
   ],
   "source": [
    "# Creating threads for currency_check and volume_check function\n",
    "c = threading.Thread(target = currency_check, args = (ticker_list, ))\n",
    "v = threading.Thread(target = volume_check, args = (ticker_list, ))\n",
    "\n",
    "# Start thread c execution\n",
    "c.start()\n",
    "\n",
    "# Wait for c to finish, grab all elements from queue\n",
    "c.join()\n",
    "while not queueC.empty():\n",
    "    currency_valid.append(queueC.get())\n",
    "\n",
    "# Start thread v execution\n",
    "v.start()\n",
    "\n",
    "# Wait for v to finish, grab all elements from queue\n",
    "v.join()\n",
    "while not queueV.empty():\n",
    "    volume_valid.append(queueV.get())\n",
    "\n",
    "# Valid tickers are the intersection of the two lists (Must have particular denomination and average monthly volume)\n",
    "valid_tickers = sorted([value for value in currency_valid if value in volume_valid])\n",
    "\n",
    "print(f\"\\nValid Tickers: {valid_tickers}\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. CHOOSING THE STOCKS:\n",
    "\n",
    "In this section, we choose the stocks to be used in the final portfolio.\n",
    "\n",
    "THE GOAL:\n",
    "\n",
    "Since our overall goal is to have a portfolio that finishes as close to its starting value as possible, we naturally want a diversified and stable selection of stocks. With this in mind, we decided to use a system which considers correlation and volatility (\"the points system\"). \n",
    "\n",
    "Essentially, we want:\n",
    "\n",
    "• (If there are less than max_tickers tickers to choose from) Every (valid) ticker available <b>OR</b>\n",
    "  (if there are more than max_tickers tickers to choose from) 'max_tickers' tickers, comprised of the stocks which earn the most \"points\" in our points system.\n",
    "\n",
    "• Note: Volatility, as we define it in this section, is represented by the standard deviation of daily returns:\n",
    "\n",
    "\\begin{align*}\n",
    "\\sigma_X=\\sqrt{\\frac{\\sum(x_i-\\overline{X})^2}{N}}\n",
    "\\end{align*}\n",
    "\n",
    "- Where $x_i$ are individual returns of some security $X$, $N$ is the total number of observations\n",
    "\n",
    "• Note: Correlation, as we define it in this section, is as follows:\n",
    "\n",
    " \\begin{align*}\n",
    "COR(X,Y)=\\frac{COV(X,Y)}{\\sigma_X \\times \\sigma_Y}\n",
    "\\end{align*}\n",
    "\n",
    "Where COV(X,Y) is: \n",
    "\n",
    "\\begin{align*}\n",
    "COV(X,Y)=\\frac{\\sum(x_i-\\overline{X})\\times(y_i-\\overline{Y})}{N}\n",
    "\\end{align*}\n",
    "\n",
    "THE PROCESS:\n",
    "\n",
    "We will obtain closing data for each ticker, and calculate the daily returns. Then, we will use our points system to select the tickers which will be conducive to our goal."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 2.1 Returns DataFrame"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First we create the closing prices DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 235,
   "metadata": {},
   "outputs": [],
   "source": [
    "interval = '1d'\n",
    "# Dictionary of closing prices\n",
    "closing_dict = {}\n",
    "# Dictionary of returns\n",
    "returns_dict = {}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 236,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Closing Prices Preview:\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>AAPL</th>\n",
       "      <th>ABT</th>\n",
       "      <th>ACN</th>\n",
       "      <th>ADBE</th>\n",
       "      <th>AEE</th>\n",
       "      <th>AEP</th>\n",
       "      <th>AMZN</th>\n",
       "      <th>BA</th>\n",
       "      <th>BAC</th>\n",
       "      <th>BK</th>\n",
       "      <th>...</th>\n",
       "      <th>REGN</th>\n",
       "      <th>ROP</th>\n",
       "      <th>SO</th>\n",
       "      <th>T</th>\n",
       "      <th>TSN</th>\n",
       "      <th>TXN</th>\n",
       "      <th>UNH</th>\n",
       "      <th>UPS</th>\n",
       "      <th>VMW</th>\n",
       "      <th>VZ</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2023-01-03</th>\n",
       "      <td>124.706364</td>\n",
       "      <td>108.034747</td>\n",
       "      <td>267.175735</td>\n",
       "      <td>336.92</td>\n",
       "      <td>87.163629</td>\n",
       "      <td>93.139744</td>\n",
       "      <td>85.82</td>\n",
       "      <td>195.39</td>\n",
       "      <td>33.029731</td>\n",
       "      <td>45.553478</td>\n",
       "      <td>...</td>\n",
       "      <td>720.47</td>\n",
       "      <td>432.497286</td>\n",
       "      <td>70.500820</td>\n",
       "      <td>17.895453</td>\n",
       "      <td>62.496431</td>\n",
       "      <td>160.846554</td>\n",
       "      <td>514.710629</td>\n",
       "      <td>172.089197</td>\n",
       "      <td>122.32</td>\n",
       "      <td>38.161273</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-01-04</th>\n",
       "      <td>125.992614</td>\n",
       "      <td>109.641762</td>\n",
       "      <td>266.266234</td>\n",
       "      <td>341.41</td>\n",
       "      <td>87.626584</td>\n",
       "      <td>93.777890</td>\n",
       "      <td>85.14</td>\n",
       "      <td>203.64</td>\n",
       "      <td>33.650701</td>\n",
       "      <td>46.675097</td>\n",
       "      <td>...</td>\n",
       "      <td>726.49</td>\n",
       "      <td>440.739881</td>\n",
       "      <td>71.098949</td>\n",
       "      <td>18.277426</td>\n",
       "      <td>63.390641</td>\n",
       "      <td>166.720247</td>\n",
       "      <td>500.677758</td>\n",
       "      <td>173.885883</td>\n",
       "      <td>122.92</td>\n",
       "      <td>39.121963</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-01-05</th>\n",
       "      <td>124.656510</td>\n",
       "      <td>109.237543</td>\n",
       "      <td>259.978816</td>\n",
       "      <td>328.44</td>\n",
       "      <td>84.710952</td>\n",
       "      <td>92.069624</td>\n",
       "      <td>83.12</td>\n",
       "      <td>204.99</td>\n",
       "      <td>33.581705</td>\n",
       "      <td>46.448805</td>\n",
       "      <td>...</td>\n",
       "      <td>723.76</td>\n",
       "      <td>433.950691</td>\n",
       "      <td>69.010399</td>\n",
       "      <td>18.344271</td>\n",
       "      <td>63.243244</td>\n",
       "      <td>164.512684</td>\n",
       "      <td>486.247917</td>\n",
       "      <td>170.675410</td>\n",
       "      <td>121.73</td>\n",
       "      <td>39.664135</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-01-06</th>\n",
       "      <td>129.243135</td>\n",
       "      <td>110.745968</td>\n",
       "      <td>266.137718</td>\n",
       "      <td>332.75</td>\n",
       "      <td>86.996177</td>\n",
       "      <td>94.769469</td>\n",
       "      <td>86.08</td>\n",
       "      <td>213.00</td>\n",
       "      <td>33.916832</td>\n",
       "      <td>47.176874</td>\n",
       "      <td>...</td>\n",
       "      <td>737.15</td>\n",
       "      <td>442.345096</td>\n",
       "      <td>70.236074</td>\n",
       "      <td>18.649850</td>\n",
       "      <td>64.923573</td>\n",
       "      <td>172.623506</td>\n",
       "      <td>486.287614</td>\n",
       "      <td>175.692388</td>\n",
       "      <td>126.14</td>\n",
       "      <td>40.130212</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-01-09</th>\n",
       "      <td>129.771594</td>\n",
       "      <td>110.568506</td>\n",
       "      <td>270.625906</td>\n",
       "      <td>341.98</td>\n",
       "      <td>88.069839</td>\n",
       "      <td>96.163571</td>\n",
       "      <td>87.36</td>\n",
       "      <td>208.57</td>\n",
       "      <td>33.404285</td>\n",
       "      <td>47.363810</td>\n",
       "      <td>...</td>\n",
       "      <td>680.49</td>\n",
       "      <td>442.085873</td>\n",
       "      <td>70.108604</td>\n",
       "      <td>18.446927</td>\n",
       "      <td>64.569819</td>\n",
       "      <td>174.121494</td>\n",
       "      <td>486.347159</td>\n",
       "      <td>178.382509</td>\n",
       "      <td>124.27</td>\n",
       "      <td>39.970890</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>5 rows × 48 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "                  AAPL         ABT         ACN    ADBE        AEE        AEP  \\\n",
       "2023-01-03  124.706364  108.034747  267.175735  336.92  87.163629  93.139744   \n",
       "2023-01-04  125.992614  109.641762  266.266234  341.41  87.626584  93.777890   \n",
       "2023-01-05  124.656510  109.237543  259.978816  328.44  84.710952  92.069624   \n",
       "2023-01-06  129.243135  110.745968  266.137718  332.75  86.996177  94.769469   \n",
       "2023-01-09  129.771594  110.568506  270.625906  341.98  88.069839  96.163571   \n",
       "\n",
       "             AMZN      BA        BAC         BK  ...    REGN         ROP  \\\n",
       "2023-01-03  85.82  195.39  33.029731  45.553478  ...  720.47  432.497286   \n",
       "2023-01-04  85.14  203.64  33.650701  46.675097  ...  726.49  440.739881   \n",
       "2023-01-05  83.12  204.99  33.581705  46.448805  ...  723.76  433.950691   \n",
       "2023-01-06  86.08  213.00  33.916832  47.176874  ...  737.15  442.345096   \n",
       "2023-01-09  87.36  208.57  33.404285  47.363810  ...  680.49  442.085873   \n",
       "\n",
       "                   SO          T        TSN         TXN         UNH  \\\n",
       "2023-01-03  70.500820  17.895453  62.496431  160.846554  514.710629   \n",
       "2023-01-04  71.098949  18.277426  63.390641  166.720247  500.677758   \n",
       "2023-01-05  69.010399  18.344271  63.243244  164.512684  486.247917   \n",
       "2023-01-06  70.236074  18.649850  64.923573  172.623506  486.287614   \n",
       "2023-01-09  70.108604  18.446927  64.569819  174.121494  486.347159   \n",
       "\n",
       "                   UPS     VMW         VZ  \n",
       "2023-01-03  172.089197  122.32  38.161273  \n",
       "2023-01-04  173.885883  122.92  39.121963  \n",
       "2023-01-05  170.675410  121.73  39.664135  \n",
       "2023-01-06  175.692388  126.14  40.130212  \n",
       "2023-01-09  178.382509  124.27  39.970890  \n",
       "\n",
       "[5 rows x 48 columns]"
      ]
     },
     "execution_count": 236,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Fills closing_dict dictionary with closing prices for each ticker in closing_tickers\n",
    "for ticker in valid_tickers:\n",
    "    tick_obj = Stock(ticker = ticker)\n",
    "    tick_hist = tick_obj.history(start = start, end = end, interval = interval)\n",
    "\n",
    "    closing_dict[ticker] = tick_hist['Close']\n",
    "\n",
    "closing_df = pd.DataFrame(closing_dict)\n",
    "\n",
    "print(\"Closing Prices Preview:\")\n",
    "closing_df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we create the daily returns DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 237,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Percent Returns Preview:\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>AAPL</th>\n",
       "      <th>ABT</th>\n",
       "      <th>ACN</th>\n",
       "      <th>ADBE</th>\n",
       "      <th>AEE</th>\n",
       "      <th>AEP</th>\n",
       "      <th>AMZN</th>\n",
       "      <th>BA</th>\n",
       "      <th>BAC</th>\n",
       "      <th>BK</th>\n",
       "      <th>...</th>\n",
       "      <th>REGN</th>\n",
       "      <th>ROP</th>\n",
       "      <th>SO</th>\n",
       "      <th>T</th>\n",
       "      <th>TSN</th>\n",
       "      <th>TXN</th>\n",
       "      <th>UNH</th>\n",
       "      <th>UPS</th>\n",
       "      <th>VMW</th>\n",
       "      <th>VZ</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2023-01-03</th>\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>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>...</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>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-01-04</th>\n",
       "      <td>0.010314</td>\n",
       "      <td>0.014875</td>\n",
       "      <td>-0.003404</td>\n",
       "      <td>0.013327</td>\n",
       "      <td>0.005311</td>\n",
       "      <td>0.006851</td>\n",
       "      <td>-0.007924</td>\n",
       "      <td>0.042223</td>\n",
       "      <td>0.018800</td>\n",
       "      <td>0.024622</td>\n",
       "      <td>...</td>\n",
       "      <td>0.008356</td>\n",
       "      <td>0.019058</td>\n",
       "      <td>0.008484</td>\n",
       "      <td>0.021345</td>\n",
       "      <td>0.014308</td>\n",
       "      <td>0.036517</td>\n",
       "      <td>-0.027264</td>\n",
       "      <td>0.010440</td>\n",
       "      <td>0.004905</td>\n",
       "      <td>0.025174</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-01-05</th>\n",
       "      <td>-0.010605</td>\n",
       "      <td>-0.003687</td>\n",
       "      <td>-0.023613</td>\n",
       "      <td>-0.037990</td>\n",
       "      <td>-0.033273</td>\n",
       "      <td>-0.018216</td>\n",
       "      <td>-0.023726</td>\n",
       "      <td>0.006629</td>\n",
       "      <td>-0.002050</td>\n",
       "      <td>-0.004848</td>\n",
       "      <td>...</td>\n",
       "      <td>-0.003758</td>\n",
       "      <td>-0.015404</td>\n",
       "      <td>-0.029375</td>\n",
       "      <td>0.003657</td>\n",
       "      <td>-0.002325</td>\n",
       "      <td>-0.013241</td>\n",
       "      <td>-0.028821</td>\n",
       "      <td>-0.018463</td>\n",
       "      <td>-0.009681</td>\n",
       "      <td>0.013858</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-01-06</th>\n",
       "      <td>0.036794</td>\n",
       "      <td>0.013809</td>\n",
       "      <td>0.023690</td>\n",
       "      <td>0.013123</td>\n",
       "      <td>0.026977</td>\n",
       "      <td>0.029324</td>\n",
       "      <td>0.035611</td>\n",
       "      <td>0.039075</td>\n",
       "      <td>0.009979</td>\n",
       "      <td>0.015675</td>\n",
       "      <td>...</td>\n",
       "      <td>0.018501</td>\n",
       "      <td>0.019344</td>\n",
       "      <td>0.017761</td>\n",
       "      <td>0.016658</td>\n",
       "      <td>0.026569</td>\n",
       "      <td>0.049302</td>\n",
       "      <td>0.000082</td>\n",
       "      <td>0.029395</td>\n",
       "      <td>0.036228</td>\n",
       "      <td>0.011751</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-01-09</th>\n",
       "      <td>0.004089</td>\n",
       "      <td>-0.001602</td>\n",
       "      <td>0.016864</td>\n",
       "      <td>0.027739</td>\n",
       "      <td>0.012341</td>\n",
       "      <td>0.014710</td>\n",
       "      <td>0.014870</td>\n",
       "      <td>-0.020798</td>\n",
       "      <td>-0.015112</td>\n",
       "      <td>0.003962</td>\n",
       "      <td>...</td>\n",
       "      <td>-0.076864</td>\n",
       "      <td>-0.000586</td>\n",
       "      <td>-0.001815</td>\n",
       "      <td>-0.010881</td>\n",
       "      <td>-0.005449</td>\n",
       "      <td>0.008678</td>\n",
       "      <td>0.000122</td>\n",
       "      <td>0.015312</td>\n",
       "      <td>-0.014825</td>\n",
       "      <td>-0.003970</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>5 rows × 48 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "                AAPL       ABT       ACN      ADBE       AEE       AEP  \\\n",
       "2023-01-03       NaN       NaN       NaN       NaN       NaN       NaN   \n",
       "2023-01-04  0.010314  0.014875 -0.003404  0.013327  0.005311  0.006851   \n",
       "2023-01-05 -0.010605 -0.003687 -0.023613 -0.037990 -0.033273 -0.018216   \n",
       "2023-01-06  0.036794  0.013809  0.023690  0.013123  0.026977  0.029324   \n",
       "2023-01-09  0.004089 -0.001602  0.016864  0.027739  0.012341  0.014710   \n",
       "\n",
       "                AMZN        BA       BAC        BK  ...      REGN       ROP  \\\n",
       "2023-01-03       NaN       NaN       NaN       NaN  ...       NaN       NaN   \n",
       "2023-01-04 -0.007924  0.042223  0.018800  0.024622  ...  0.008356  0.019058   \n",
       "2023-01-05 -0.023726  0.006629 -0.002050 -0.004848  ... -0.003758 -0.015404   \n",
       "2023-01-06  0.035611  0.039075  0.009979  0.015675  ...  0.018501  0.019344   \n",
       "2023-01-09  0.014870 -0.020798 -0.015112  0.003962  ... -0.076864 -0.000586   \n",
       "\n",
       "                  SO         T       TSN       TXN       UNH       UPS  \\\n",
       "2023-01-03       NaN       NaN       NaN       NaN       NaN       NaN   \n",
       "2023-01-04  0.008484  0.021345  0.014308  0.036517 -0.027264  0.010440   \n",
       "2023-01-05 -0.029375  0.003657 -0.002325 -0.013241 -0.028821 -0.018463   \n",
       "2023-01-06  0.017761  0.016658  0.026569  0.049302  0.000082  0.029395   \n",
       "2023-01-09 -0.001815 -0.010881 -0.005449  0.008678  0.000122  0.015312   \n",
       "\n",
       "                 VMW        VZ  \n",
       "2023-01-03       NaN       NaN  \n",
       "2023-01-04  0.004905  0.025174  \n",
       "2023-01-05 -0.009681  0.013858  \n",
       "2023-01-06  0.036228  0.011751  \n",
       "2023-01-09 -0.014825 -0.003970  \n",
       "\n",
       "[5 rows x 48 columns]"
      ]
     },
     "execution_count": 237,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# We will use this later\n",
    "stock_returns_lists = {}\n",
    "\n",
    "# Fills returns dictionary with the pct returns for each ticker in closing_df\n",
    "for stock in closing_df.columns:\n",
    "    stock_returns = closing_df.loc[:,stock].pct_change()\n",
    "    returns_dict[stock] = stock_returns\n",
    "    \n",
    "    stock_returns_lists = stock_returns.tolist()\n",
    "\n",
    "returns_df = pd.DataFrame(returns_dict)\n",
    "\n",
    "print(\"Percent Returns Preview:\")\n",
    "returns_df.head()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 2.2 The Points System\n",
    "\n",
    "We use a volatility metric and a correlation metric to select the tickers which will use in our final portfolio. Here's how it works:\n",
    "\n",
    "1. The <i><b>standard deviation of each stock's percent returns (daily)</i></b> will be used as the <b>volatility</b> metric.\n",
    "- The least volatile stocks will receive the most points, the most volatile stock will receive 0 points.\n",
    "\n",
    "2. The <i><b>correlation of the daily % returns of each stock</i></b> with the <i><b>average of the daily % returns of every stock in the portfolio combined</i></b> will be used as the <b>correlation</b> metric.\n",
    "- The stocks that are either most or least correlated with the entire portfolio (i.e correlation metric is closest to -1 or 1) will receive the most points, and the points will converge to 0 (with the stock in the middle receiving 0 points (or 1 point if the number of tickers is even)).\n",
    "\n",
    "3. The \"score\" of each ticker is calculated by:\n",
    "\n",
    " \\begin{align*}\n",
    "S= (Pv)(Wv) + (Pc)(Wc) \n",
    "\\end{align*}\n",
    "\n",
    "Where:\n",
    "- Pv is the points earned for volatility\n",
    "- Wv is the weight of importance for volatility (Wv = 2 is recommended based on trials conducted by team, but should be changed based on market environment (e.g volatile market, increase weight))\n",
    "- Pc is the points earned for correlation\n",
    "- Wc is the weight of importance for correlation (Wc = 1 is recommended based on trials conducted by team)\n",
    "\n",
    "4. We sort the scores of each ticker in descending order, and pick the tickers with the highest scores. These tickers will be used in the final portfolio. We use this final list of the tickers to filter our existing close prices and percent return DataFrames such that each only has values for each ticker in our list, and store these as new DataFrames.\n",
    "\n",
    "- A \"weight of importance\" is simply a number that multiplies each element in the set of scores. The user of the program may choose the ratio of importance of the volatility metric to the correlation metric.\n",
    "\n",
    "Note: The score difference across placings for either volatility or correlation is linear (i.e if 1st place has 5 more points than 6th place, 6th place has 5 more points than 11th place)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 238,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MODIFIABLE #\n",
    "\n",
    "# Importance ratios\n",
    "weight_volatility = 2\n",
    "weight_correlation = 1"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We first collect the volatility of the valid tickers"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 239,
   "metadata": {},
   "outputs": [],
   "source": [
    "volatilities = {}\n",
    "\n",
    "# Calculate volatility for every column in returns_df\n",
    "for ticker in returns_df.keys():\n",
    "    stock_vol = returns_df[ticker].std()\n",
    "    volatilities[ticker] = stock_vol"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we collect the correlation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 240,
   "metadata": {},
   "outputs": [],
   "source": [
    "correlations = {}\n",
    "\n",
    "# Grab the average percent return across all tickers for each day present in corr_df\n",
    "port_returns = []\n",
    "for date in returns_df.index:\n",
    "    port_returns.append(returns_df.loc[date,:].mean())\n",
    "\n",
    "# Create a DataFrame with one column: the average percent return of the 'combined' portfolio\n",
    "port_returns_df = pd.DataFrame(pd.Series(data = port_returns, index = returns_df.index))\n",
    "port_returns_df.columns = ['portfolio']\n",
    "\n",
    "# Join the returns DataFrame to the portfolio returns DataFrame\n",
    "port_returns_df = port_returns_df.merge(returns_df, left_index = True, right_index = True)\n",
    "\n",
    "# Calculate correlation matrix \n",
    "stocks_corr = port_returns_df.corr()\n",
    "\n",
    "# Grab the correlation of each ticker with the 'combined' portfolio\n",
    "for ticker in valid_tickers:\n",
    "    correlations[ticker] = stocks_corr.loc['portfolio',ticker]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We sort the volatility and correlation rankings by their respective scores."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 241,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Sort the volatilities dictionary in ascending order, collect keys (representing the stocks, ordered from lowest to highest volatility)\n",
    "volatility_rankings = dict(sorted(volatilities.items(), key=lambda item: item[1]))\n",
    "\n",
    "# Sort the correlations dictionary in ascending order, collect keys (representing the stocks, ordered from lowest to highest correlation)\n",
    "correlation_rankings = dict(sorted(correlations.items(), key=lambda item: item[1]))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now set up the scores for volatility and correlation (based on the weights of importance) as described in the beginning of this section. Recall that stocks are awarded the most points for the least volatility, and as well the most points for correlating either the most or the least with the combined / equally weighted / aggregated portfolio."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 242,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Ceiling for scores, also number of tickers in final portfolio\n",
    "num_ticks = len(valid_tickers)\n",
    "\n",
    "# Volatility scores\n",
    "#   The ticker with the lowest volatility will receive the most points, and the points decrease for each more volatile ticker.\n",
    "vol_scores = list(reversed(list(range(0, num_ticks))))\n",
    "\n",
    "# Correlation scores\n",
    "#   The highest points are awarded to the tickers on either extreme (close to -1 or 1), and points converge to the middle (lowest points)\n",
    "#   2 Cases, we need to know whether to add a score of 0 (for the middle score of an odd number of tickers)\n",
    "#   The range for each side is the number of tickers // 2,\n",
    "#     with every value multiplied by 2 (each extreme has the same score as the highest in vol_scores)\n",
    "if num_ticks % 2 == 0:\n",
    "    corr_scores_right = list(map(lambda s: s * 2, list(range(0, num_ticks // 2))))\n",
    "    corr_scores_left = list(map(lambda s: s * 2, list(reversed(list(range(0, num_ticks // 2))))))\n",
    "else:\n",
    "    corr_scores_right = list(map(lambda s: s * 2, list(range(1, num_ticks // 2 + 1))))\n",
    "    corr_scores_left = list(map(lambda s: s * 2, list(reversed(list(range(1, num_ticks // 2 + 1))))))\n",
    "    corr_scores_left.append(0)\n",
    "\n",
    "# Add left and right score sets\n",
    "corr_scores = corr_scores_left + corr_scores_right\n",
    "\n",
    "# Account for the importance ratios\n",
    "vol_scores = [score * weight_volatility for score in vol_scores]\n",
    "corr_scores = [score * weight_correlation for score in corr_scores]\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now award each stock its appropriate score. We grab those with the highest combined score, and save them to a final ticker list. We will use these tickers in the final portfolio."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 243,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Scores:\n",
      " {'BRK-B': 136, 'CPB': 130, 'LMT': 124, 'ROP': 116, 'PG': 108, 'KO': 104, 'ED': 98, 'CVS': 98, 'AAPL': 98, 'GRMN': 96, 'IBM': 92, 'UNH': 90, 'TSN': 90, 'NOC': 90, 'GILD': 90, 'VZ': 88, 'TXN': 86, 'PM': 86, 'SO': 84, 'CSCO': 78, 'INFY': 76, 'CMS': 76, 'ACN': 74, 'REGN': 72, 'VMW': 70, 'D': 68, 'AEP': 68, 'AEE': 68, 'GO': 62, 'CMCSA': 62, 'UPS': 56, 'GE': 56, 'CF': 52, 'ABT': 50, 'BAC': 48, 'T': 46, 'MS': 46, 'ADBE': 42, 'C': 38, 'BA': 38, 'MSFT': 36, 'BK': 36, 'GM': 32, 'F': 32, 'MNSO': 28, 'JPM': 28, 'GOOG': 10, 'AMZN': 8}\n",
      "Volatility:\n",
      " {'KO': 94, 'PG': 92, 'BRK-B': 90, 'IBM': 88, 'LMT': 86, 'CPB': 84, 'PM': 82, 'ROP': 80, 'ED': 78, 'SO': 76, 'VZ': 74, 'CVS': 72, 'TSN': 70, 'CMS': 68, 'AEE': 66, 'CSCO': 64, 'AEP': 62, 'GILD': 60, 'AAPL': 58, 'D': 56, 'VMW': 54, 'GRMN': 52, 'ABT': 50, 'UNH': 48, 'NOC': 46, 'TXN': 44, 'INFY': 42, 'ACN': 40, 'GE': 38, 'REGN': 36, 'MS': 34, 'UPS': 32, 'GO': 30, 'JPM': 28, 'BK': 26, 'CMCSA': 24, 'T': 22, 'BA': 20, 'BAC': 18, 'C': 16, 'MSFT': 14, 'CF': 12, 'ADBE': 10, 'GOOG': 8, 'GM': 6, 'F': 4, 'AMZN': 2, 'MNSO': 0}\n",
      "Correlation:\n",
      " {'CPB': 46, 'NOC': 44, 'UNH': 42, 'CF': 40, 'LMT': 38, 'REGN': 36, 'INFY': 34, 'GO': 32, 'GILD': 30, 'MNSO': 28, 'CVS': 26, 'T': 24, 'MSFT': 22, 'ED': 20, 'GE': 18, 'PG': 16, 'VZ': 14, 'D': 12, 'KO': 10, 'CMS': 8, 'AEP': 6, 'PM': 4, 'GOOG': 2, 'ABT': 0, 'JPM': 0, 'AEE': 2, 'IBM': 4, 'AMZN': 6, 'SO': 8, 'BK': 10, 'MS': 12, 'CSCO': 14, 'VMW': 16, 'BA': 18, 'TSN': 20, 'C': 22, 'UPS': 24, 'GM': 26, 'F': 28, 'BAC': 30, 'ADBE': 32, 'ACN': 34, 'ROP': 36, 'CMCSA': 38, 'AAPL': 40, 'TXN': 42, 'GRMN': 44, 'BRK-B': 46}\n",
      "\n",
      "Stocks in Portfolio (25): \n",
      "['BRK-B', 'CPB', 'LMT', 'ROP', 'PG', 'KO', 'ED', 'CVS', 'AAPL', 'GRMN', 'IBM', 'UNH', 'TSN', 'NOC', 'GILD', 'VZ', 'TXN', 'PM', 'SO', 'CSCO', 'INFY', 'CMS', 'ACN', 'REGN', 'VMW']\n"
     ]
    }
   ],
   "source": [
    "# Replace the values in the correlation and volatility dictionaries with the score earned\n",
    "for rank, ticker in enumerate(volatility_rankings.keys()):\n",
    "    volatility_rankings[ticker] = vol_scores[rank]\n",
    "for rank, ticker in enumerate(correlation_rankings.keys()):\n",
    "    correlation_rankings[ticker] = corr_scores[rank]\n",
    "\n",
    "# Add the scores together for each ticker\n",
    "scores = {}\n",
    "for ticker in valid_tickers:\n",
    "    scores[ticker] = correlation_rankings[ticker] + volatility_rankings[ticker]\n",
    "\n",
    "# Sort the scores dictionary by total score (ascending)\n",
    "scores = dict(reversed(sorted(scores.items(), key=lambda item: item[1])))\n",
    "\n",
    "# Show tickers and their overall scores\n",
    "print(f\"Scores:\\n {scores}\")\n",
    "\n",
    "# Show tickers and their volatility scores\n",
    "print(f\"Volatility:\\n {volatility_rankings}\")\n",
    "\n",
    "# Show tickers and their correlation scores\n",
    "print(f\"Correlation:\\n {correlation_rankings}\")\n",
    "\n",
    "# If the number of tickers is greater than max_tickers, grab the first 'max_tickers' tickers to use in final portfolio, else use all of them\n",
    "if num_ticks > max_tickers:\n",
    "    tickers_final = list(scores.keys())[0:max_tickers]\n",
    "    num_ticks_final = max_tickers\n",
    "else:\n",
    "    tickers_final = list(scores.keys())\n",
    "    num_ticks_final = num_ticks\n",
    "\n",
    "# Get percent returns DataFrame and price DataFrame for final tickers\n",
    "returns_df_final = returns_df[tickers_final]\n",
    "closing_df_final = closing_df[tickers_final]\n",
    "\n",
    "print(f\"\\nStocks in Portfolio ({num_ticks_final}): \\n{tickers_final}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We define a uniform order for data related to our tickers here. We do this for the sake of speed and memory optimization.\n",
    "\n",
    "In the Monte-Carlo simulation, we generate many lists that implicitly reference this uniform order, and also save many of these lists in the computer's temporary memory. Therefore, using a dictionary to explicitly link data to a specific ticker would be inefficient, especially since we don't perform any O(n) searches on the data that follows the uniform order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 244,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the standard order of columns / values from the keys of the (sorted) scores dictionary\n",
    "#  To save time and space, any list of values we created related to the tickers can be referenced back to this order\n",
    "tickers_uniform_order = list(list(scores.keys())[:num_ticks_final])"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. CREATING THE OPTIMAL PORTFOLIO:\n",
    "\n",
    "THE GOAL:\n",
    "\n",
    "We want to use MSCAPM to determine which allocation of capital yields the lowest absolute expected return.\n",
    "\n",
    "THE PROCESS:\n",
    "\n",
    "Since we want to use MSCAPM as the basis for judgement, we first gather a list of custom betas, one for each ticker. We opt to not use the default beta provided by Alpha Vantage, as it is not available for all tickers, and the custom beta may be changed to bias a chosen period of market activity. \n",
    "\n",
    "We then implement multithreading to efficiently* generate five-hundred thousand hypothetical portfolios in a Monte-Carlo simulation, each with a random** allocation of capital (weight) to each security. \n",
    "\n",
    "We save the MSCAPM score (expected return) of each weighting, as well as the best MSCAPM score and the weights associated with it. Finally, we generate the final portfolio, with each security being weighted according to the \"optimal weights\" (those that yield the lowest absolute MSCAPM score).\n",
    "\n",
    "\\* Multithreading is, in theory, not the most efficient method. We will get into that soon.\n",
    "\n",
    "** The weighting of the stocks is not completely random, and is influenced by the 'score' of the stock in the points system. This is explained in the appropriate section."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.1 Stock Betas\n",
    "\n",
    "We first create a DataFrame storing the percent returns of the stock that will represent the market (the 'market stock'), and merge this DataFrame with the DataFrame containing the percent returns of the stocks to be used in the final portfolio.\n",
    "\n",
    "A beta matrix is then generated using the merged DataFrame. The beta value of each stock is stored in a dictionary.\n",
    "\n",
    "Finally, we store the beta values in a list (following the uniform order of tickers) that can be called later.\n",
    "\n",
    "Beta is calculated as follows:\n",
    "\n",
    "Consider Security $X$ with returns given by $x_i$, and let the corresponding market returns be $r_M$.  Beta is then given by:\n",
    "\n",
    "\\begin{align*}\n",
    "\\beta=\\frac{COV(x_i,r_M)}{\\sigma^2(r_M)}\n",
    "\\end{align*}\n",
    "\n",
    "We decided to use the Vanguard Total Stock Market Index Admiral Shares (VTSAX) as our market stock, as we believe it to be the most all-encompassing index fund (Alpha Vantage was not sufficient in providing tickers like ^NYA). We assume that all tickers passed are US-listed, but the market which we are taking beta relative to can be changed if that is not the case, or if other factors want to be considered (such as when all tickers are from the S&P 500)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 245,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MODIFIABLE #\n",
    "\n",
    "# Reference market stock for beta calculations\n",
    "market_ticker = \"VTSAX\"\n",
    "market_name = \"Vanguard Total Market\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 246,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Portfolio's Stocks' Betas Preview:\n",
      "{'BRK-B': 0.7727032138498806, 'CPB': -0.016274668857151283, 'LMT': 0.2412733195600808, 'ROP': 0.744033636808304, 'PG': 0.34638775536559185, 'KO': 0.2983936311718197, 'ED': 0.36314410798538094, 'CVS': 0.4538807289393901, 'AAPL': 1.0704726635255648, 'GRMN': 1.0234375154638409, 'IBM': 0.47392799888259646, 'UNH': 0.2720251696804722, 'TSN': 0.7076967828312207, 'NOC': 0.178630974475319, 'GILD': 0.39560478830462864, 'VZ': 0.46130713409284574, 'TXN': 1.0856058862837326, 'PM': 0.4749481724680164, 'SO': 0.5568378797046024, 'CSCO': 0.7435976344532864, 'INFY': 0.4953195447274111, 'CMS': 0.5076639485337893, 'ACN': 1.190783785317304, 'REGN': 0.47101696878229327, 'VMW': 0.8398183945652173}\n"
     ]
    }
   ],
   "source": [
    "# Creates a DataFrame of the percent returns of the stock representing the market\n",
    "market_obj = Stock(ticker = market_ticker)\n",
    "market_hist = market_obj.history(start = start, end = end, interval = interval)\n",
    "market_returns_series = market_hist.loc[:, 'Close'].pct_change()\n",
    "market_returns_df = pd.DataFrame({market_ticker : pd.Series(data = market_returns_series, index = market_hist.index)})\n",
    "\n",
    "# We will use this later\n",
    "market_returns_list = market_returns_series.tolist()[1:]\n",
    "\n",
    "# Merges returns_df_final and the market_returns_df together and drops the first row because there is no percent return for the first day\n",
    "all_returns_df = returns_df_final.merge(market_returns_df, left_index = True, right_index = True)\n",
    "all_returns_df.drop(index = all_returns_df.index[0], inplace = True)\n",
    "\n",
    "# Calculates the variance of the stock representing the market\n",
    "market_var = market_returns_df[market_ticker].var()\n",
    "\n",
    "# Creates the beta matrix of the merged DataFrame\n",
    "beta_matrix = all_returns_df.cov() / market_var\n",
    "\n",
    "# Prints Beta Matrix\n",
    "#print(\"Portfolio's Beta Matrix:\")\n",
    "#print(beta_matrix.head())\n",
    "\n",
    "tickers_beta_final = {}\n",
    "# Dictionary of the betas of each stock\n",
    "for ticker in beta_matrix.index:\n",
    "    # We don't want the market ticker's beta in relation to itself\n",
    "    if ticker == market_ticker:\n",
    "        continue\n",
    "    \n",
    "    beta_val = beta_matrix.loc[ticker, market_ticker]\n",
    "    tickers_beta_final[ticker] = beta_val\n",
    "\n",
    "# Prints the Beta of each stock\n",
    "print(\"Portfolio's Stocks' Betas Preview:\")\n",
    "print(tickers_beta_final)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 247,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Order the betas by the uniform order\n",
    "tickers_beta_final = {ticker: tickers_beta_final[ticker] for ticker in tickers_uniform_order}\n",
    "\n",
    "# We will use this later\n",
    "beta_list = [beta for beta in tickers_beta_final.values()]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.2 Weight Generation\n",
    "\n",
    "Here we define our weight generation function, aptly named 'weight_generation'. It will be used to select random weights for each security, for each iteration of the simulation.\n",
    "\n",
    "It operates according to the following rules:\n",
    "\n",
    "- The goal is to generate a list of num_ticks_final numbers (weights), summing to 1 (100%), all between lowest_weight and highest_weight.\n",
    "\n",
    "- The tickers are split into num_ticks_final // w groups of w (n groups), plus part of the remainder, n % w, which is dispersed evenly over the groups, starting from the left.\n",
    "\n",
    "- There is a bias in the distribution of the weight. We use a geometrical sequence to generate an allocation of weight to each group of stocks. The common ratio of the sequence is determined by the user (within a specified range), and a given group g1 will be assigned g0 * r percent of the total weight of the portfolio.\n",
    "\n",
    "- Within each group, the numbers are generated randomly, but such that they add up to the group's assigned allocation of weight.\n",
    "\n",
    "We do this so that the weight of the portfolio is biased to the stocks with higher scores (recall that the uniform order of tickers is in order of highest to lowest score (left to right), so we want the earlier indices to have higher weights).\n",
    "\n",
    "We decided to place some of the decision load for portfolio generation on the points system, since we didn't want the program to rely on only one equation (MSCAPM) to determine portfolio allocation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We first initialize some variables and calculate the minimum and maximum possible r value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 248,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Target number of weights per group (and number of weights in last group)\n",
    "w = 5\n",
    "# Number of groups\n",
    "n = num_ticks_final // w\n",
    "# Minimum allocation for the last group\n",
    "m = (w + (n % w // (n // w))) * lowest_weight"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 249,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Test variables\n",
    "# Starting minimum r\n",
    "r_min = 0.01\n",
    "# This will not change\n",
    "r_max = 1\n",
    "# Initial calculations of the first weight and last weight of the groups\n",
    "w_1_test = (1 - r_min) / (1 - r_min**w)\n",
    "w_last_test = w_1_test * r_min**(w-1) \n",
    "# Initial increment\n",
    "inc = 0.1\n",
    "\n",
    "# Continue incrementing r until the last weight is essentially equal to the minimum weight for a group\n",
    "if w_last_test < m:\n",
    "    while True:\n",
    "        # Once the increment is small enough we have a pretty accurate r_min\n",
    "        if inc <= 0.000000001:\n",
    "            break\n",
    "        r_min += inc\n",
    "\n",
    "        w_1_test = (1 - r_min) / (1 - r_min**w)\n",
    "        w_last_test = w_1_test * r_min**(w-1) \n",
    "\n",
    "        # Just in case\n",
    "        if w_last_test == m:\n",
    "            break\n",
    "        elif w_last_test > m:\n",
    "            r_min -= inc\n",
    "            inc /= 10\n",
    "\n",
    "else:\n",
    "    print(2/0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 250,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Minimum r: 0.7394289269999995\n",
      "Maximum r: 1\n"
     ]
    }
   ],
   "source": [
    "print(f'Minimum r: {r_min}\\nMaximum r: {r_max}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now initialize r, calculate the number of tickers per group, and create the groups."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 251,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MODIFIABLE #\n",
    "\n",
    "# Allocation distribution (common ratio left bias)\n",
    "#   At r = 1, all groups will be of equal allocation\n",
    "r = 0.739429"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 252,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert(r >= r_min and r <= r_max)\n",
    "\n",
    "# Compute the first term\n",
    "w_1 =  (1 - r) / (1 - r**w)\n",
    "\n",
    "# Generate the terms\n",
    "weights_per_group = [w_1 * r**(i-1) for i in range(1, n+1)]\n",
    "\n",
    "#weights_per_group"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 253,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Determine the split of the groups\n",
    "quotient, remainder = divmod(num_ticks_final, w)\n",
    "groups = [w] * quotient\n",
    "if remainder:\n",
    "    c = 0\n",
    "    while remainder:\n",
    "        groups[c] += 1\n",
    "        remainder -= 1\n",
    "        c += 1\n",
    "\n",
    "#groups"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we define the weight generation function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 254,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Returns weights for the monte-carlo simulation\n",
    "def weight_generation():\n",
    "    weights = []\n",
    "\n",
    "    for i, group_size in enumerate(groups):\n",
    "        # What the weights in the group must add to\n",
    "        curr_weight = weights_per_group[i]\n",
    "\n",
    "        # Weight selector (see @ in references)\n",
    "        adjusted_k = curr_weight - lowest_weight * group_size\n",
    "        while True:\n",
    "            endpoints = sorted(uniform(0, adjusted_k) for _ in range(group_size - 1))\n",
    "            values = [*(end - begin + lowest_weight\n",
    "                        for begin, end in zip([0] + endpoints,\n",
    "                                            endpoints + [adjusted_k]))]\n",
    "            if all(v <= highest_weight for v in values):\n",
    "                weights.extend(values)\n",
    "                break\n",
    "            \n",
    "    return weights"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.3 Monte Carlo Simulation\n",
    "\n",
    "We now begin the process of portfolio optimization.\n",
    "\n",
    "We first find the market's expected return, as well as the risk-free rate, both for the period for which we want to calculate the portfolio's expected return. \n",
    "\n",
    "Then, we run the simulation and take note of the lowest absolute MSCAPM score and the weights associated with it, and generate a portfolio (the <b>optimal</b> portfolio).\n",
    "\n",
    "Note: In the code,\n",
    "\n",
    "rm = market expected return, and\n",
    "\n",
    "rf = risk-free rate.\n",
    "\n",
    "Reminder of MSCAPM calculation:\n",
    "\n",
    "![MSCAPM](pub/#_model.jpg)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 255,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MODIFIABLE #\n",
    "\n",
    "# Number of iterations for Monte-Carlo\n",
    "num_hypothetical_portfolios = 500_000"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 256,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_rf = rf / (365 / numdays) # We assume rf to be linear"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We define a function called 'expected_return_x_days', which calculates a simple expected return based on a list of historical returns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 257,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Consumes a list of daily returns, returns the expected return for numdays amount of days (based on momentum)\n",
    "def expected_return_x_days(daily_returns_list):\n",
    "    # Compute the total compounded return\n",
    "    total_compounded_return = 1\n",
    "    for daily_return in daily_returns_list:\n",
    "        total_compounded_return *= 1 + daily_return\n",
    "        \n",
    "    # Calculate the geometric average return\n",
    "    average_daily_return = total_compounded_return ** (1 / len(daily_returns_list)) - 1\n",
    "    \n",
    "    # Calculate the expected return for numdays\n",
    "    expected_return = (1 + average_daily_return) ** numdays - 1\n",
    "    \n",
    "    return expected_return"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we initialize the queues for the simulation, the market return rm, the quantity 'rm - rf', and perform a sanity check."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 258,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Initializing queue for weights function, and list to store values\n",
    "global queueW\n",
    "queueW = Queue()\n",
    "queueW_getter = []\n",
    "\n",
    "# Initialize optimal weighting list to prevent errors\n",
    "optimal_weighting = []\n",
    "\n",
    "# Get market expected return over numdays days\n",
    "rm = expected_return_x_days(daily_returns_list = market_returns_list)\n",
    "\n",
    "# So we don't have to evaluate it 500000 times :)\n",
    "rm_minus_rf = rm - new_rf\n",
    "\n",
    "# Initial sanity check\n",
    "assert((highest_weight * num_ticks_final >= 1) and (lowest_weight * num_ticks_final <= 1))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now define the Monte-Carlo simulation, best_weighting. The function takes one argument - the number of portfolios to be generated in the simulation. It will calculate the MSCAPM of that many randomly weighted portfolios, and save the information we desire (best weights, best score, all scores). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 259,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Generates 'num_ports' random portfolios\n",
    "#  Uses MSCAPM to generate ticker weights which will yield the expected return which is closest to zero\n",
    "def best_weighting(num_ports):\n",
    "   best_weights = []\n",
    "   best_mscapm_score = 10000\n",
    "   mscapm_scores = []\n",
    "\n",
    "   # set_information[0] will hold the best MSCAPM score, set_information[1] will hold the weights that yield that score, \n",
    "   #  set_information[2] holds all mscapm scores.\n",
    "   set_information = []\n",
    "\n",
    "   # If there are an appropriate number of portfolios to be generated, function will perform the weighting checks\n",
    "   if num_ports <= 100000:\n",
    "\n",
    "      # Generate random weights\n",
    "      for _ in range(num_ports):\n",
    "         weights = weight_generation()\n",
    "\n",
    "         # Generate MSCAPM score, add to list\n",
    "         mscapm = 0\n",
    "         for m in range(num_ticks_final):\n",
    "            mscapm += weights[m] * (new_rf + beta_list[m] * (rm_minus_rf)) \n",
    "         # We use the scores for analysis later\n",
    "         mscapm_scores.append(mscapm)\n",
    "\n",
    "         # Check for best MSCAPM score (closest to 0)\n",
    "         if abs(mscapm) < abs(best_mscapm_score):\n",
    "            best_mscapm_score = mscapm\n",
    "            best_weights = weights\n",
    "\n",
    "      set_information.append(best_mscapm_score) \n",
    "      set_information.append(best_weights)\n",
    "      set_information.append(mscapm_scores)\n",
    "\n",
    "      # Puts set information into queueW to be retrieved later\n",
    "      queueW.put(set_information)\n",
    "\n",
    "   # If there are too many portfolios to be generated, function creates numthreads threads, each generating num_ports // numthreads portfolios\n",
    "   else:\n",
    "      numthreads = 10\n",
    "\n",
    "      num_ports_new = num_ports // numthreads\n",
    "\n",
    "      # Start numthreads threads\n",
    "      threads = []\n",
    "      for _ in range(numthreads):\n",
    "         w_sub = threading.Thread(target = best_weighting, args = (num_ports_new, ))\n",
    "         w_sub.start()\n",
    "         threads.append(w_sub)\n",
    "\n",
    "      # Wait for all threads to finish.\n",
    "      for t in threads:\n",
    "         t.join()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We run best_weighting on a thread, and use queueW_getter to collect the information it generates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 260,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Runs best_weighting\n",
    "run_weights = threading.Thread(target = best_weighting, args = (num_hypothetical_portfolios, ))\n",
    "run_weights.start()\n",
    "run_weights.join()\n",
    "\n",
    "# Grab information from queueW\n",
    "while not queueW.empty():\n",
    "   queueW_getter.append(queueW.get())"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now the best score and associated weights are collected to build the final portfolio, and every generated score is collected for analysis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 261,
   "metadata": {},
   "outputs": [],
   "source": [
    "best_score = 10000\n",
    "mscapm_scores = []\n",
    "\n",
    "# Gets information for MSCAPM scores from Queue, grabs best score, and optimal weights\n",
    "for set_info in range(0, len(queueW_getter)):\n",
    "   mscapm_scores.append(queueW_getter[set_info][2]) # Add list of all scores to mscapm_scores for analysis\n",
    "\n",
    "   # Check for best score\n",
    "   #  For each set_info, queueW_getter[set_info][0] is the best score from thread # set_info\n",
    "   if abs(queueW_getter[set_info][0]) < abs(best_score):\n",
    "      best_score = queueW_getter[set_info][0]\n",
    "      optimal_weighting = queueW_getter[set_info][1]\n",
    "\n",
    "# mscapm_scores is a list of lists, so we make it flat\n",
    "mscapm_scores = [item for sublist in mscapm_scores for item in sublist]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 262,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Uncomment to see how the betas of each ticker compares to their weight in the portfolio\n",
    "#weights_tickers_betas = pd.DataFrame({'Weight' : optimal_weighting,\n",
    "                   #'Ticker' : tickers_uniform_order,\n",
    "                   #'Beta' : beta_list})\n",
    "\n",
    "#weights_tickers_betas.sort_values(by = 'Weight', ascending=False)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now create the final portfolio by grabbing the price for each ticker as of 'price_date', and constructing a DataFrame with the tickers, stock prices, number of shares, total value in the portfolio, and weight in the portfolio."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 263,
   "metadata": {},
   "outputs": [],
   "source": [
    "prices = []\n",
    "shares = []\n",
    "value = []\n",
    "\n",
    "# Retrieve price for purchase from each ticker and store it in a list\n",
    "#  We use tickers_uniform_order instead of tickers_final so that we can keep a list instead of a dictionary\n",
    "#   (beta_list, optimal_weights, tickers_uniform_order, and prices will all be lined up)\n",
    "# By default the price date is the last date of analysis (Efficient Market Hypothesis)\n",
    "for ticker in tickers_uniform_order:\n",
    "    prices.append(closing_df_final[ticker][-1])\n",
    "\n",
    "# Index of final portfolio begins at 1\n",
    "index = list(range(1, (num_ticks_final + 1)))\n",
    "\n",
    "# Calculating shares, value of stock in portfolio\n",
    "for i in range(num_ticks_final):\n",
    "    shares.append((capital * optimal_weighting[i]) / prices[i])\n",
    "    value.append(prices[i] * shares[i])\n",
    "\n",
    "portfolio_final_dict = {'Ticker': tickers_uniform_order,\n",
    "                        'Price ($)': prices,\n",
    "                        'Shares': shares,\n",
    "                        'Value ($)': value,\n",
    "                        'Weight': optimal_weighting}\n",
    " \n",
    "portfolio_final = pd.DataFrame(portfolio_final_dict)\n",
    "portfolio_final.index = index"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.4 Final Portfolio"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To make it easier for the user to understand the composition of the final portfolio, we clean up some of the information from portfolio_final, and present a user-friendly version."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 264,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<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>Ticker</th>\n",
       "      <th>Price ($)</th>\n",
       "      <th>Shares</th>\n",
       "      <th>Value ($)</th>\n",
       "      <th>Weight (%)</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>CPB</td>\n",
       "      <td>54.11</td>\n",
       "      <td>1076.59</td>\n",
       "      <td>58259.37</td>\n",
       "      <td>11.65</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>LMT</td>\n",
       "      <td>450.03</td>\n",
       "      <td>123.53</td>\n",
       "      <td>55591.68</td>\n",
       "      <td>11.12</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>UNH</td>\n",
       "      <td>487.47</td>\n",
       "      <td>87.45</td>\n",
       "      <td>42628.84</td>\n",
       "      <td>8.53</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>KO</td>\n",
       "      <td>63.18</td>\n",
       "      <td>666.29</td>\n",
       "      <td>42093.05</td>\n",
       "      <td>8.42</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>ED</td>\n",
       "      <td>97.22</td>\n",
       "      <td>362.95</td>\n",
       "      <td>35287.19</td>\n",
       "      <td>7.06</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>CVS</td>\n",
       "      <td>69.52</td>\n",
       "      <td>322.29</td>\n",
       "      <td>22405.04</td>\n",
       "      <td>4.48</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>PG</td>\n",
       "      <td>155.26</td>\n",
       "      <td>141.90</td>\n",
       "      <td>22031.82</td>\n",
       "      <td>4.41</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>VZ</td>\n",
       "      <td>37.30</td>\n",
       "      <td>582.71</td>\n",
       "      <td>21736.20</td>\n",
       "      <td>4.35</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>BRK-B</td>\n",
       "      <td>323.22</td>\n",
       "      <td>55.25</td>\n",
       "      <td>17856.60</td>\n",
       "      <td>3.57</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>GILD</td>\n",
       "      <td>78.69</td>\n",
       "      <td>176.69</td>\n",
       "      <td>13904.06</td>\n",
       "      <td>2.78</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>10</th>\n",
       "      <td>SO</td>\n",
       "      <td>72.64</td>\n",
       "      <td>186.37</td>\n",
       "      <td>13537.33</td>\n",
       "      <td>2.71</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>11</th>\n",
       "      <td>ROP</td>\n",
       "      <td>455.77</td>\n",
       "      <td>29.66</td>\n",
       "      <td>13517.49</td>\n",
       "      <td>2.70</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>12</th>\n",
       "      <td>GRMN</td>\n",
       "      <td>99.40</td>\n",
       "      <td>134.46</td>\n",
       "      <td>13364.92</td>\n",
       "      <td>2.67</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>13</th>\n",
       "      <td>IBM</td>\n",
       "      <td>121.78</td>\n",
       "      <td>103.95</td>\n",
       "      <td>12659.53</td>\n",
       "      <td>2.53</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>14</th>\n",
       "      <td>NOC</td>\n",
       "      <td>441.83</td>\n",
       "      <td>26.79</td>\n",
       "      <td>11837.13</td>\n",
       "      <td>2.37</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>15</th>\n",
       "      <td>PM</td>\n",
       "      <td>94.60</td>\n",
       "      <td>119.05</td>\n",
       "      <td>11262.78</td>\n",
       "      <td>2.25</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>16</th>\n",
       "      <td>CSCO</td>\n",
       "      <td>45.61</td>\n",
       "      <td>240.38</td>\n",
       "      <td>10964.91</td>\n",
       "      <td>2.19</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>17</th>\n",
       "      <td>AAPL</td>\n",
       "      <td>167.22</td>\n",
       "      <td>62.94</td>\n",
       "      <td>10524.45</td>\n",
       "      <td>2.10</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>18</th>\n",
       "      <td>TSN</td>\n",
       "      <td>59.99</td>\n",
       "      <td>173.68</td>\n",
       "      <td>10419.06</td>\n",
       "      <td>2.08</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>19</th>\n",
       "      <td>TXN</td>\n",
       "      <td>162.14</td>\n",
       "      <td>62.41</td>\n",
       "      <td>10118.53</td>\n",
       "      <td>2.02</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>20</th>\n",
       "      <td>INFY</td>\n",
       "      <td>15.18</td>\n",
       "      <td>658.95</td>\n",
       "      <td>10000.00</td>\n",
       "      <td>2.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>21</th>\n",
       "      <td>CMS</td>\n",
       "      <td>60.71</td>\n",
       "      <td>164.73</td>\n",
       "      <td>10000.00</td>\n",
       "      <td>2.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>22</th>\n",
       "      <td>ACN</td>\n",
       "      <td>274.20</td>\n",
       "      <td>36.47</td>\n",
       "      <td>10000.00</td>\n",
       "      <td>2.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>23</th>\n",
       "      <td>REGN</td>\n",
       "      <td>803.17</td>\n",
       "      <td>12.45</td>\n",
       "      <td>10000.00</td>\n",
       "      <td>2.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>24</th>\n",
       "      <td>VMW</td>\n",
       "      <td>123.49</td>\n",
       "      <td>80.98</td>\n",
       "      <td>10000.01</td>\n",
       "      <td>2.00</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   Ticker  Price ($)   Shares  Value ($)  Weight (%)\n",
       "0     CPB      54.11  1076.59   58259.37       11.65\n",
       "1     LMT     450.03   123.53   55591.68       11.12\n",
       "2     UNH     487.47    87.45   42628.84        8.53\n",
       "3      KO      63.18   666.29   42093.05        8.42\n",
       "4      ED      97.22   362.95   35287.19        7.06\n",
       "5     CVS      69.52   322.29   22405.04        4.48\n",
       "6      PG     155.26   141.90   22031.82        4.41\n",
       "7      VZ      37.30   582.71   21736.20        4.35\n",
       "8   BRK-B     323.22    55.25   17856.60        3.57\n",
       "9    GILD      78.69   176.69   13904.06        2.78\n",
       "10     SO      72.64   186.37   13537.33        2.71\n",
       "11    ROP     455.77    29.66   13517.49        2.70\n",
       "12   GRMN      99.40   134.46   13364.92        2.67\n",
       "13    IBM     121.78   103.95   12659.53        2.53\n",
       "14    NOC     441.83    26.79   11837.13        2.37\n",
       "15     PM      94.60   119.05   11262.78        2.25\n",
       "16   CSCO      45.61   240.38   10964.91        2.19\n",
       "17   AAPL     167.22    62.94   10524.45        2.10\n",
       "18    TSN      59.99   173.68   10419.06        2.08\n",
       "19    TXN     162.14    62.41   10118.53        2.02\n",
       "20   INFY      15.18   658.95   10000.00        2.00\n",
       "21    CMS      60.71   164.73   10000.00        2.00\n",
       "22    ACN     274.20    36.47   10000.00        2.00\n",
       "23   REGN     803.17    12.45   10000.00        2.00\n",
       "24    VMW     123.49    80.98   10000.01        2.00"
      ]
     },
     "execution_count": 264,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Create a final portfolio with rounded values to show to the user\n",
    "portfolio_final_show_dict = {'Ticker': portfolio_final.loc[:, 'Ticker'].values.tolist(),\n",
    "                            'Price ($)': np.round(portfolio_final.loc[:, 'Price ($)'].values.tolist(), 2),\n",
    "                            'Shares': np.round(portfolio_final.loc[:, 'Shares'].values.tolist(), 2),\n",
    "                            'Value ($)': np.round(portfolio_final.loc[:, 'Value ($)'].values.tolist(), 2),\n",
    "                            'Weight (%)': np.round([x * 100 for x in portfolio_final.loc[:, 'Weight'].values.tolist()], 2)}\n",
    "\n",
    "# Make DataFrame, reset index\n",
    "portfolio_final_show = pd.DataFrame(portfolio_final_show_dict)\n",
    "portfolio_final_show.sort_values(by = 'Weight (%)', inplace = True, ascending = False)\n",
    "\n",
    "portfolio_final_show.reset_index(inplace = True)\n",
    "portfolio_final_show.drop(columns = 'index', inplace = True)\n",
    "\n",
    "# Final portfolio\n",
    "portfolio_final_show"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. ANALYSIS AND SANITY CHECKS:\n",
    "\n",
    "We now perform sanity checks to ensure the portfolio is correctly sized and weighted, and analyze the portfolio to show why it is the optimal portfolio for our goal. We use Matplotlib graphs to make the analysis more comprehensible."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 4.1 Value and Weights Check"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is our objective sanity check."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 265,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Total Portfolio Value:  $500000\n",
      "Total Portfolio Weight: 100.0%\n",
      "\n",
      "Everything is correct!\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    # Total value and weight of portfolio\n",
    "    val = int(np.round(sum(portfolio_final['Value ($)'], 0)))\n",
    "    weight = np.round(sum(portfolio_final['Weight'], 0))\n",
    "\n",
    "    print(f\"Total Portfolio Value:  ${val}\")\n",
    "    print(f\"Total Portfolio Weight: {weight * 100}%\")\n",
    "\n",
    "    # Print message depending on whether or not portfolio values are correct\n",
    "    if val == capital and weight == 1:\n",
    "        print(\"\\nEverything is correct!\")\n",
    "    else:\n",
    "        print(\"\\nWeight or Total Value is incorrect.\")\n",
    "except:\n",
    "    print(\"Something went wrong when trying to calculate the value and weight of the portfolio.\")\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 4.2 Expected Returns Visualization"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We plot a sample of expected returns from our Monte-Carlo simulation, as well as plot the expected return of the optimal portfolio on a line graph. We mark the optimal portfolio with a star.\n",
    "\n",
    "The fact that there is a noticeable difference between the expected returns of differently weighted portfolios shows that even with a good set of tickers, the process for selecting their weight in a portfolio is important."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 266,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MODIFIABLE #\n",
    "\n",
    "# Must be less than num_hypothetical_portfolios (recommended to be less than 10 000 also)\n",
    "num_data_points = 1000"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 267,
   "metadata": {},
   "outputs": [],
   "source": [
    "# For analysis\n",
    "port_expected_return = best_score * 100\n",
    "\n",
    "frequency = f\"{numdays} Days\"\n",
    "\n",
    "# Indexes for sample of CAPM scores\n",
    "index_for_graph = np.random.randint(0, (num_hypothetical_portfolios - 1), num_data_points)\n",
    "\n",
    "# Initialize list with best score\n",
    "capm_examples = [port_expected_return]\n",
    "\n",
    "# Grab 'num_data_points' data points to graph\n",
    "for d in range(num_data_points):\n",
    "    capm_examples.append(mscapm_scores[index_for_graph[d]] * 100) # * 100 so it is represented as a %\n",
    "\n",
    "# We have 1D data, so all y values are 0\n",
    "y_values = [0] * (num_data_points + 1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 268,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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9b7PTF6c5/73v/8ZX19ft+R0YmKiiYiIMLfccourLDU11ZQqVcp06NDBrc3PPvvMSDLff/+9q+y7774zksznn3/uVrd9+/amdOnSJjU1Ndv9dCbmDhw44Fbep08fI8ksX7482/UvJD093Zw4cSLbcbZ8+XIjyUyfPv2itpFZYg4AkHPcygoAhdShQ4cUEREhHx+fDK95ebl/PEyfPl0dOnRQqVKlVKRIEcXExOjxxx/X8ePH3er169dPwcHB2rx5szp27KigoCCVKlVKL7zwgiRp5cqVatGihYKCgnT11Vdr2rRpbus7b4dZtGiR+vfvr+LFiysoKEjdunXTtm3bLrhPxhi9/fbbqlu3rooUKaJixYrp5ptvztG6krR8+XJde+21CgkJUWBgoJo1a6bvvvvO9frYsWNVtmxZSdKIESNydPvk+X2ZlVmzZqlq1apq2rSpq8zHx0d33nmnfvvtN9ftnXv37tXq1avVp08ft2PXrFkzXX311Zo1a5arbPbs2TLGqH///m7b6t+/v06ePKkFCxZkG9O4cePkcDg0efJk+fv7Z3jdz89P3bt3dytLSUnR559/rgYNGui1116TJH344Yc56gNJatKkiSRp586dbuXt27dXuXLl3NpKT0/XtGnTdNddd+Won48fP65Tp06pVKlSmb5+fhunTp3SM888o5iYGAUEBCg8PFxt27bVihUrXHVSUlI0cuRIVaxYUX5+fipTpoweeOCBDLegRUdHq2vXrvrmm29Ur149BQQE6Omnn5YkxcfH67777lPZsmVdt7E9/fTTSk1NdWvjnXfeUZ06dRQcHKyQkBBVq1ZNo0aNynJ/nbcB//vvv5o/f77rVrkdO3a4Xvvkk080fPhwlSlTRv7+/vr3338lWcesTp06CggIUPHixXXjjTdq06ZNbu1f6vs9M7NmzdLGjRv1xBNPKCYmJtM6FSpU0A033OBWlpSUpEcffdTtOAwdOjTDOcrhcOjBBx/UJ598opiYGAUGBqpOnTqaN29ehu38888/uv3221WyZEn5+/srJiZGb731VqZ9nFk/HjhwQIMHD1b16tUVHByskiVLql27dlq2bJlr/R07dqhEiRKSpKefftp1jPr16ycp61tZPTk+//77r7p06aLg4GCVK1dOw4cPz9GtwOnp6ZowYYKqVasmf39/lSxZUn379tWePXtcdaKjo/Xkk09KkiIjI+VwODR27NgLtn0heXWemzVrltq1a6cKFSq4ykJDQ9WzZ099++23rvfcypUrFRcXl6HNXr16KTg42G37s2bNUnBwsHr16pVh+/v27dOqVasuqg/OPxcePnxYgwcPVpkyZeTn56errrpKTzzxRIZj6Rzj7777rmJiYuTv769p06ZlOc769eunFi1aSJJuvfXWDI9cmDt3rut24pCQELVv316xsbEXjD+zW1lzer5cvHix2rRpo/DwcBUpUkTly5fXTTfdpBMnTnjShQBwxSAxBwCFVNOmTbVq1SoNGTJEq1at0pkzZ7Ks+88//6hLly6aMmWKFixYoKFDh+qrr75St27dMtQ9c+aMevbsqeuvv15z5sxR586dNXLkSI0aNUp33XWX7r77blcSql+/flqzZk2GNgYMGCAvLy99/vnnmjhxon777Te1adPmgs/bue+++zR06FBdd911mj17tt5++239/fffatasmfbv35/tukuXLlW7du2UmJioKVOm6IsvvlBISIi6deum6dOnS5LuueceffPNN5Kkhx56SLGxsW4/0C7FX3/9pdq1a2cod5b9/fffrnrnlp9f1/m6s26JEiUUFRWVaZvn1j1fWlqaFi9erAYNGqhcuXI53o9vvvlGR44c0d13360qVaqoRYsWmj59eqbPZcqMMzHk/BHp5OXlpX79+unjjz9WWlqaJGnhwoXas2dPhh/PWYmIiFDlypX19ttv69VXX9XmzZtljMm0bmpqqjp37qxnn31WXbt21axZszR16lQ1a9ZMu3btkmQlgm+44Qa9/PLL6tOnj7777jsNGzZM06ZNU7t27TL8YF67dq3+97//aciQIVqwYIFuuukmxcfH65prrtEPP/yg0aNHa/78+RowYIDGjx+vgQMHutb98ssvNXjwYLVu3VqzZs3S7Nmz9cgjj2RIPJ2rfv36io2NVVRUlJo3b67Y2FjFxsa6JSZHjhypXbt26d1339W3336rkiVLavz48RowYIBq1Kihb775Rq+//ro2bNigpk2b6p9//nHbRm6838+1aNEiScqQ8M3OiRMn1Lp1a02bNk1DhgzR/PnzNWLECE2dOlXdu3fPcIy/++47TZo0Sc8884xmzpzpSmydm8DfuHGjGjVqpL/++kuvvPKK5s2bp+uvv15DhgxxJVTPlVk/Op+/OGbMGH33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ffvUp08ft9v8g4ODddNNN2nlypUe3Vqa0/Nl3bp15efnp3vvvVfTpk3L8aMoAOBKRmIOAAq5hg0basSIEfr666+1b98+PfLII9qxY4cmTJggSTp27JhatmypVatW6bnnntOSJUu0evVq1y2dJ0+edGsvMDBQAQEBbmV+fn4qXrx4hm37+fkpJSUlQ/n5tyQ5yw4dOpTlfuzfv1/GGEVGRrr9gPf19dXKlSuzTWQcOXJExphMnz1WunRpScp227khPDw80204b4dz9l94eHiW8Rw+fNitn7Nq8/jx4zp9+nSmx8QpIiJCgYGB2r59e4734cMPP5QxRjfffLOOHj2qo0ePum6l+/XXX7V58+YM63z88cdavXq1/vjjD+3bt08bNmxQ8+bNs9zGgAED9O233+rVV19VkSJFMvxQzQlfX1917NhRzz//vH744Qft3r1bbdq00bx58zR//nxJ0oEDB1S6dOlsn1136NAh+fj4ZLjt1uFwZDpeMxtf+/fv17fffpthzNaoUUOSXOO2T58++vDDD7Vz507ddNNNKlmypBo3buy69fNinR+TM+as3gvn71NuvN/PVb58eUkZnzF4++23a/Xq1Vq9erXq16/v9tr+/fu1YcOGDH0YEhIiY0yG977zPXQuf39/17ns0KFDSk1N1ZtvvpmhTWcS8vw2M+uvV199Vffff78aN26smTNnauXKlVq9erU6deqU4byZU7lxfPz9/S94HDzdzqWIjo5WixYt3JKdeXGeK1asmBwOx2U7z57f5oX8+OOPWr16tdatW6eDBw9q+fLlql69uiuOqKioDEm+kiVLysfHJ0fnGk9daAykp6fryJEjHrWXk/NlpUqV9OOPP6pkyZJ64IEHVKlSJVWqVEmvv/76JewNAORvGZ/4DQAotHx9fTVmzBi99tprrufiLF68WPv27dOSJUtcV8lJuuDz3i5FfHx8pmWVK1fOcp2IiAg5HA4tW7Ys04kKMitzKlasmLy8vBQXF5fhtX379rnaz0u1atXSn3/+maHcWVazZk23//75559uVyo5y5yvO9v88ssvFR8f75bsPL/NzHh7e+vaa6/V/PnztWfPHtekF1lJT0/X1KlTJSnTZx5JVuLOmfB1iomJUcOGDbNt+1w9e/bUAw88oBdeeEEDBw5UkSJFcrxuVsLDwzV06FAtWbJEf/31l7p06aISJUpo+fLlSk9PzzI5Fx4ertTUVB04cMDtx6YxRvHx8WrUqJFb/cyunImIiFDt2rX1/PPPZ7oNZ2JYsh4m379/fx0/fly//PKLxowZo65du2rr1q1uD7P3xPkxORMSWb0X8vp90L59e02ePFlz587Vo48+6iovWbKkSpYsKUkKCQlxe35fRESEihQpkuVVmZ7GXKxYMdfVsg888ECmdSpWrOj2d2bH9tNPP1WbNm30zjvvuJUnJyd7FM+5LtfxOXc757/382IcGGPc3md5cZ4rUqSIKleunOV5tkiRIrrqqqtcbTrLnckxyXr25ObNm9W7d2+37X/xxRdKTU11e85cTs6z56pTp06W/RoeHq5Vq1bJGOM21hISEpSampphvdy4GvpCY83Ly8ujq/I8OV+2bNlSLVu2VFpamn7//Xe9+eabGjp0qCIjI3Xbbbddwl4BQP7EFXMAUEhl9mVbOntrqjMh4PyCf35i67333suz2D777DO3v1esWKGdO3e6zRR3vq5du8oYo71796phw4YZFucPrcwEBQWpcePG+uabb9yuZElPT9enn36qsmXLZrgFMbfdeOON2rx5s9sMfqmpqfr000/VuHFj1/EoU6aMrrnmGn366aeuSRAkaxbBLVu2uCXFevToIYfDkenst0WKFFGnTp2yjWnkyJEyxmjgwIGZPnT7zJkz+vbbbyVJP/zwg/bs2aMHHnhAP//8c4alRo0a+vjjjzPMNOqpIkWKaPTo0erWrZvuv/9+j9Y9c+ZMllf6nD/uO3furJSUFFeyMTPXXnutJCsBc66ZM2fq+PHjrtez07VrV/3111+qVKlSpuP23MScU1BQkDp37qwnnnhCp0+fdk0MkhuaNm2qIkWKZNinPXv2aPHixTnap0tx4403qnr16ho3blymV1hmpmvXrvrvv/8UHh6eaR9eaObk8wUGBqpt27b6448/VLt27UzbzOyqu/M5HI4M580NGzZkmNHSWScnV9FdruPTrl07SRnH9urVq7Vp06ZcHQfbt2/Xr7/+6pqFVMq789yNN96oxYsXa/fu3a6y5ORkffPNN+revbsrsda4cWOVKlUqw/t/xowZOnbsmNv2b7zxRh07dkwzZ850qztt2jSVLl1ajRs3vohecXfttdfq2LFjmj17tlv5xx9/7Hr9QjwZZ5JUtWpVlSlTRp9//rnbBCrHjx/XzJkzXTO15tTFnC+9vb3VuHFj1+QUa9euzfH2AOBKwhVzAFBIdezYUWXLllW3bt1UrVo1paena926dXrllVcUHByshx9+WJL1fLdixYpp0KBBGjNmjHx9ffXZZ59p/fr1eRbb77//rnvuuUe9evXS7t279cQTT6hMmTIaPHhwlus0b95c9957r/r376/ff/9drVq1UlBQkOLi4rR8+XLVqlUr20TO+PHj1b59e7Vt21aPPvqo/Pz89Pbbb+uvv/7SF198cdFXIPz+++/asWOHJCkpKUnGGM2YMUOS9bwz55VOd999t9566y316tVLL7zwgkqWLKm3335bW7Zs0Y8//ujW5osvvqj27durV69eGjx4sBISEvT444+rZs2abjOU1qhRQwMGDNCYMWPk7e2tRo0aaeHChZo8ebKee+65C95i1bRpU73zzjsaPHiwGjRooPvvv181atTQmTNn9Mcff2jy5MmqWbOmunXrpilTpsjHx0ejRo3KNJl03333aciQIfruu+/Uo0ePi+pLp2HDhmnYsGEer5eYmKjo6Gj16tVL1113ncqVK6djx45pyZIlev311xUTE+P6wd27d2999NFHGjRokLZs2aK2bdsqPT1dq1atUkxMjG677Ta1b99eHTt21IgRI5SUlKTmzZtrw4YNGjNmjOrVq6c+ffpcMKZnnnlGixYtUrNmzTRkyBBVrVpVKSkp2rFjh77//nu9++67Klu2rOvqwObNm6tUqVKKj4/X+PHjFRYWluHKvEtRtGhRPfXUUxo1apT69u2r3r1769ChQ3r66acVEBCgMWPG5Nq2MuPt7a3Zs2erY8eOuuaaazRw4EC1adNGxYoV09GjR7Vq1SqtX79eMTExrnWGDh2qmTNnqlWrVnrkkUdUu3Ztpaena9euXVq4cKGGDx/ucXLk9ddfV4sWLdSyZUvdf//9io6OVnJysv799199++23rudlZadr16569tlnNWbMGLVu3VpbtmzRM888o4oVK7olqENCQlShQgXNmTNH1157rYoXL66IiIhME4qX6/hUrVpV9957r9588015eXmpc+fO2rFjh5566imVK1dOjzzyyEW1e91116lVq1aqXbu2QkND9eeff2rChAlyOBx69tln3ermxXnu0Ucf1SeffKLrr79ezzzzjPz9/fXCCy8oJSVFY8eOddXz9vbWhAkT1KdPH913333q3bu3/vnnHz322GNq3769W7Kvc+fOat++ve6//34lJSWpcuXK+uKLL7RgwQJ9+umn8vb2vqi+Olffvn311ltv6a677tKOHTtUq1YtLV++XOPGjVOXLl103XXXXbANT8aZZM2EPWHCBN1xxx3q2rWr7rvvPp06dUovvfSSjh49qhdeeMGjfcjp+fLdd9/V4sWLdf3116t8+fJKSUlxXQ2bk/0EgCuSLVNOAABsN336dHP77bebKlWqmODgYOPr62vKly9v+vTpYzZu3OhWd8WKFaZp06YmMDDQlChRwtxzzz1m7dq1RpL56KOPXPXuuusuExQUlGFbrVu3NjVq1MhQfv5skc6Z3RYuXGj69OljihYt6pqB8J9//nFb9/wZ35w+/PBD07hxYxMUFGSKFCliKlWqZPr27Wt+//33C/bJsmXLTLt27VzrNmnSxHz77bdudTydldU5M2Jmy7l9Z4w1O2Tfvn1N8eLFTUBAgGnSpIlZtGhRpu0uXLjQNGnSxAQEBJjixYubvn37mv3792eod/r0aTNmzBhTvnx54+fnZ66++mrzxhtv5Ch2p3Xr1pm77rrL1UZQUJCpV6+eGT16tElISDAHDhwwfn5+5oYbbsiyDedskt26dTPGnD3W58+keb7MZgvMTE5mZT116pR5+eWXTefOnU358uWNv7+/CQgIMDExMeaxxx4zhw4dcqt/8uRJM3r0aFOlShXj5+dnwsPDTbt27VwzNzrrjBgxwlSoUMH4+vqaUqVKmfvvv981K61TZjOjOh04cMAMGTLEVKxY0fj6+prixYubBg0amCeeeMIcO3bMGGPMtGnTTNu2bU1kZKTx8/MzpUuXNrfccovZsGFDtvuc1bYv1K8ffPCBqV27tvHz8zNhYWGmR48erhlinS71/Z6dxMREM27cONOoUSMTGhpqfHx8TMmSJU379u3NW2+9ZY4fP+5W/9ixY+bJJ580VatWdcVcq1Yt88gjj7hm+DXGmrHygQceyDS2u+66y61s+/bt5u677zZlypQxvr6+pkSJEqZZs2Zus0Nn14+nTp0yjz76qClTpowJCAgw9evXN7Nnz8703PXjjz+aevXqGX9/fyPJFUtms10ac2nHxzkL6IWkpaWZF1980Vx99dXG19fXREREmDvvvNPs3r070/ZyMivr0KFDTfXq1U1ISIjx8fExpUuXNnfeeWeG2Yqd8uI89++//5obbrjBhIaGmsDAQHPttdeaNWvWZFr3888/d/VzVFSUGTJkSKazlicnJ5shQ4aYqKgo4+fnZ2rXrm2++OKLC/aHMTnvv0OHDplBgwaZUqVKGR8fH1OhQgUzcuTIDDMYZzXGjcl6nGU3jmfPnm0aN25sAgICTFBQkLn22mvNr7/+6lYnJ7OyGpOz82VsbKy58cYbTYUKFYy/v78JDw83rVu3NnPnzs22fwDgSuYw5pxrkwEAsNHUqVPVv39/rV692qPnjgEAAADAlYhnzAEAAAAAAAA2IDEHAAAAAAAA2IBbWQEAAAAAAAAbcMUcAAAAAAAAYAMScwAAAAAAAIANSMwBAAAAAAAANvCxO4CCID09Xfv27VNISIgcDofd4QAAAAAAAMAmxhglJyerdOnS8vLK/po4EnO5YN++fSpXrpzdYQAAAAAAACCf2L17t8qWLZttHRJzuSAkJESS1eGhoaE2RwMAAAAAAAC7JCUlqVy5cq58UXZIzOUC5+2roaGhJOYAAAAAAACQo8edMfkDAAAAAAAAYAMScwAAAAAAAIANSMwBAAAAAAAANuAZcwAAAAAAALkoLS1NZ86csTsM5CE/Pz95eV369W4k5gAAAAAAAHKBMUbx8fE6evSo3aEgj3l5ealixYry8/O7pHZIzAEAAAAAAOQCZ1KuZMmSCgwMzNGsnLjypKena9++fYqLi1P58uUv6TiTmAMAAAAAALhEaWlprqRceHi43eEgj5UoUUL79u1TamqqfH19L7odJn8AAAAAAAC4RM5nygUGBtocCS4H5y2saWlpl9QOiTkAAAAAAIBcklu3r67YvUJNPmiiFbtX5Ep7yF25dZxJzAEAAAAAAOQzb656U6v2rtKk3ybZHQryEIk5AAAAAACAfOTgiYOasWmGJOnrjV/r4ImDNkeEvEJiDgAAAAAAIB+Ztm6a0k26JCndpOvj9R/n6fb69esnh8PhWsLDw9WpUydt2LAh17YxduxY1a1b94L1jh8/rhEjRuiqq65SQECASpQooTZt2mjevHm5Fkt+wqysAAAAAAAANtmbtFf7j+93K3v797dljJEkGWP01uq31Ca6jVudyKBIlQktk2txdOrUSR999JEkKT4+Xk8++aS6du2qXbt25do2cmLQoEH67bffNGnSJFWvXl2HDh3SihUrdOjQoTzb5unTp12TOVxuXDEHAAAAAABgk94ze6vB5AZuy/Yj22X0/4k5GW07si1Dndtn3p6rcfj7+ysqKkpRUVGqW7euRowYod27d+vAgQOuOnv37tWtt96qYsWKKTw8XD169NCOHTtcry9ZskTXXHONgoKCVLRoUTVv3lw7d+7U1KlT9fTTT2v9+vWuq/KmTp2aaRzffvutRo0apS5duig6OloNGjTQQw89pLvuustV59SpU3rsscdUrlw5+fv7q0qVKpoyZYrr9aVLl+qaa66Rv7+/SpUqpccff1ypqamu19u0aaMHH3xQw4YNU0REhNq3by9J2rhxo7p06aLg4GBFRkaqT58+Ongwb28jJjEHAAAAAABgk3vq36MAnwA5dHaWT2dSLjMOORTgE6AB9QfkWUzHjh3TZ599psqVKys8PFySdOLECbVt21bBwcH65ZdftHz5cgUHB6tTp046ffq0UlNTdcMNN6h169basGGDYmNjde+998rhcOjWW2/V8OHDVaNGDcXFxSkuLk633nprptuOiorS999/r+Tk5Czj69u3r7788ku98cYb2rRpk959910FBwdLspKHXbp0UaNGjbR+/Xq98847mjJlip577jm3NqZNmyYfHx/9+uuveu+99xQXF6fWrVurbt26+v3337VgwQLt379ft9xySy71aua4lRUAAAAAAMAmfev0VcPSDXXj9Bv17+F/Xc+Wy4yXw0tVilfRN7d+o+olqudqHPPmzXMlt44fP65SpUpp3rx58vKyrun68ssv5eXlpQ8++EAOh5VE/Oijj1S0aFEtWbJEDRs2VGJiorp27apKlSpJkmJiYlztBwcHy8fHR1FRUdnGMXnyZN1xxx0KDw9XnTp11KJFC918881q3ry5JGnr1q366quvtGjRIl133XWSpKuuusq1/ttvv61y5cpp0qRJcjgcqlatmvbt26cRI0Zo9OjRrv2pXLmyJkyY4Fpv9OjRql+/vsaNG+cq+/DDD1WuXDlt3bpVV1999cV17AVwxRwAAAAAAICNqpeorrX3rlWv6r2yrXdLjVu09r61uZ6Uk6S2bdtq3bp1WrdunVatWqUOHTqoc+fO2rlzpyRpzZo1+vfffxUSEqLg4GAFBwerePHiSklJ0X///afixYurX79+6tixo7p166bXX39dcXFxHsfRqlUrbdu2TT/99JNuuukm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PHmy/vrrLx0/flxSxiQdYxKXy8KFC9W3b18tW7ZMS5Ys0S233KKXXnrJ7rBQSM2ePVtPPfWUQkNDlZKSooceekj//fefPv74Yw0aNEgffvihUlJS7A4Thcj333+vqVOn6rvvvtOgQYM0cOBATZ8+XQcOHFCDBg20e/duSVwZgstj6tSpCgkJUYUKFZSWlqY1a9aof//+6t+/vwYMGKDvv/+e75C4bD7++GMdOXJE119/vU6ePKkXXnhB119/vVq0aKGSJUtq7Nix/ANGAeUwnGngoebNm6tFixZ68cUXJUknT57UkSNHtH79en322WfaunWr3njjDTVp0sTmSFFYtGvXTsuWLVPz5s3VuHFjNWvWTLVq1VK5cuXk6+srybrK87vvviNBgjzXunVrNWrUSOPGjZOfn5/efPNNvffee/r+++9Vvnx5Sda/fq5evVq9evWyOVoUdC1atFDr1q31/PPPS5J69uypQ4cOaceOHWrUqJG2bNmi4cOHq1+/fvYGikJj7969atu2rRo1aqTo6GitXr1aJ0+eVGJiojZt2qTp06erU6dOCgwMtDtUFAINGjRQ586d9dxzz+n999/XO++8o9OnT6tBgwbav3+/EhIS9O677+qaa66xO1QUAr169VJ0dLReeuklPf300/rpp5/UsmVLdejQQcuWLdOnn36qe+65R48++qjdoSKXkZiDR1JSUtS8eXMNHz5ct99+e4bXExISdMsttyggIECzZ89WQECADVGiMElOTla9evU0cOBAJSQkaP78+Tp+/LiqV6+uVq1aqUmTJqpWrZruu+8+BQcH6/PPP7c7ZBRgR48eVeXKlbVs2TLFxMQoPT1dp06dUrt27dSpUyeNGTNGktSnTx8FBgbqvffeszliFGRHjx7VVVddpVWrVumqq66St7e3ypcvr9tuu00jR46Un5+f+vbtqyNHjmjevHkkQnDZ/PDDD5o5c6YmTpyohIQEbdiwQYMGDZKfn5/KlSsnSXriiSfUqVMnmyNFQXb48GFFRETo5MmT8vf3V61atXTrrbdq1KhR8vLy0q5du9SlSxfVrFlTX375pd3hooAzxmjEiBE6cuSI3n//fdWuXVsjR45U7969JVnPih0zZox++OEHzZo1S2XLlrU5YuQmbmWFR/z9/dW0aVONGjVKmzdvznBpd8mSJfXiiy/qv//+U0JCgk1RojD5999/ValSJdWtW1evvPKKNm7cqPfff18RERGaPHmy7rvvPg0aNEjz5s3TkCFD7A4XBdzatWtVq1Yt199eXl4qUqSIRo0apddff10HDhyQMUazZs3SnXfeaWOkKAxWrlypa665Rn5+fvL29taff/6pPXv2aMiQISpWrJiCgoI0fPhwJScn6/Dhw3aHi0LCGKO2bdsqKSlJw4cPV3R0tLp3764DBw5o3Lhx6t27tyIiIlSpUiW7Q0UB9/PPP0uSevfurVGjRun06dO6//77Xb9vypcvr8cee0y7d+/WgQMH7AwVhYDD4VCbNm30/fffa86cOapSpYrOnDnjet3b21sPP/ywEhMTdfLkSRsjRV7wsTsAXFkcDoeGDx+uTZs2afjw4erbt68aN26siIgIBQcHS5L+/PNPHT9+3HXLFpCXrr76ao0ePdr1L+yS1KFDB3Xo0EEnTpzQ7NmzNXr0aF111VXcXo08V6pUKUVERLiedWiMkcPhUOfOnVWnTh299957ql27tgICAtSyZUubo0VBV6VKFQ0aNEghISGSpOjoaP3www9u/8q+a9cuJScn8y/vuGwcDof8/Pz0yiuv6LrrrtO3336rrVu3qmrVqq67MQYMGCB/f3+bI0VBV6NGDb3zzjv6+eef9cEHH6hZs2ZKT0+Xt7e36/Pb19dXSUlJKlGihN3hooBLT09Xly5ddNttt+n1119XcnKyPvjgAzVv3tz1DxXTp0/X8ePHVaVKFZujRW7jVlZ4xPkhtWTJEo0fP14///yzKleurPbt2yskJERr1qxRXFycbrvtNj3++ON2h4tCxDk2JetSb8n6lyVJatq0qVq2bKkJEybYFh8Kj5SUFPn7+7vGY3p6ury8vPTJJ59oypQpOnz4sNq1a6eJEyfaGygKhfT0dDkcDrcJcZxSU1PVuXNn1a1bl+dv4rJKTU2Vj4+PfvnlF73++utatGiRnnzyST322GNun+dAXjPGKCEhQVu3blVKSopatWrlSgqnpaWpQ4cOqlevnl5++WWbI0VhsXv3br322muaMWOG9uzZo8qVK6tixYquqzb79++vhx56yOYokdtIzOGS/Pfff5o8ebKWLl2q4OBgBQQE6J577lHnzp35l07kC7t371ajRo20fPlyVa5c2e5wUIglJyerRYsW+vPPP7V7926VKVPG7pBQiBlj9N577+nN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XLZtAgCA3EFiDgAAFCidOnVSXFyc2/LFF1/YHZatQkNDFRcXp3379um7777T8ePHdf311+v06dOXPZZL2eaKFSv0zz//qFevXq6ye+65R+3atdPatWt19OhRjRs3zvXayy+/rBYtWqhRo0Y5an/gwIFu4+a999674DrO8bZjxw7Nnz9fbdu21cMPP6yuXbsqNTXV8528SHfccYeWLVumTZs2XbZtAgCAS0diDgAAFCj+/v6KiopyW4oVKyZJWrJkifz8/LRs2TJX/VdeeUURERGKi4uTZF059eCDD+rBBx9U0aJFFR4erieffFLGGNc6p0+f1mOPPaYyZcooKChIjRs31pIlS9zi+PXXX9W6dWsFBgaqWLFi6tixo44cOaJ+/fpp6dKlev31111XW+3YsUOStHHjRnXp0kXBwcGKjIxUnz59dPDgQVebx48fV9++fRUcHKxSpUrplVdeyVGfOBwORUVFqVSpUmrYsKEeeeQR7dy5U1u2bHHVWbFihVq1aqUiRYqoXLlyGjJkiI4fP+7qk507d+qRRx5xxSxJY8eOVd26dd22NXHiREVHR7v+7tevn2644QaNHz9epUuX1tVXX60dO3bI4XDom2++Udu2bRUYGKg6deooNjY22/348ssv1aFDBwUEBLjKNm3apIEDB+rqq69W7969tXHjRknStm3b9OGHH+r555/PUR9JUmBgoNu4CQsLu+A6zvFWpkwZ1a9fX6NGjdKcOXM0f/58TZ061VXv1VdfVa1atRQUFKRy5cpp8ODBOnbsmCTruIaGhmrGjBlubX/77bcKCgpScnKyTp8+rQcffFClSpVSQECAoqOjNX78eFfd8PBwNWvWrNAnoQEAuNKQmAMAAIWG8xbSPn36KDExUevXr9cTTzyh999/X6VKlXLVmzZtmnx8fLRq1Sq98cYbeu211/TBBx+4Xu/fv79+/fVXffnll9qwYYN69eqlTp066Z9//pEkrVu3Ttdee61q1Kih2NhYLV++XN26dVNaWppef/11NW3a1O3qrHLlyikuLk6tW7dW3bp19fvvv2vBggXav3+/brnlFtd2//e//+nn/2vv7mOqLN84gH8FOex4eBNlwEZwGsjLKN6mhrGhKUIrjWklsRQyKZmESPkCUlmUNmnGwhyFrTNRUmhic0036Qgi03wj5CXeRHwJx1QOGQtCOFy/P/zx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",
      "text/plain": [
       "<Figure size 1500x500 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Plot the data, pinpoint best score\n",
    "plt.scatter(capm_examples, y_values, color = 'r')\n",
    "plt.plot(port_expected_return, 0, marker = '*', color = 'g', ls = 'none', ms = 10, label = 'Best Score')\n",
    "\n",
    "# Set axis and title\n",
    "plt.title(f'Sample of {num_data_points} CAPM Scores from Generation of {num_hypothetical_portfolios} Portfolios')\n",
    "plt.xlabel(f'Expected Return (% {frequency})')\n",
    "plt.xticks(rotation = 70)\n",
    "plt.ylabel('Y-Axis Not Applicable')\n",
    "\n",
    "# Change size of graph\n",
    "plt.gcf().set_size_inches(15, 5)\n",
    "\n",
    "plt.legend(loc = 'best')\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 4.3 Returns Check With Low Volatility ETF Comparison"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We provide a \"performance check\", where we can input two days (one_period_start and one_period_end) and track the return of our portfolio in comparison to a low volatility ETF (referred to as the \"fund\" or the \"benchmark\"). This section is a precursor to section 4.4 where we will graph more detailed information.\n",
    "\n",
    "We use an analysis period that begins after the end of the portfolio creation analysis period, to prevent look-ahead bias."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are using the \"iShares MSCI USA Min Vol Factor ETF\" (USMV) as the reference fund because it is a US total-market, broad-based, multi-factor fund. It is about as close of a security as we will get to our portfolio in terms of scope and goals. It also has over 29 billion USD net assets, and is owned by iShares, so it's reputable and well-funded. We set it as our \"benchmark\".\n",
    "\n",
    "<b>If we are able to outperform* a multi-billion dollar ETF, skillfully curated by the world's largest asset manager, which shares comparable investment objectives and portfolio characteristics to ours, with a portfolio comprised of stocks we barely researched (and with way fewer stocks overall), crafted by quantitative analysis, we consider this project a success. </b>\n",
    "\n",
    "\\* Outperform in terms of our goal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 269,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MODIFIABLE #\n",
    "\n",
    "fund_ticker = 'USMV'\n",
    "fund_name = 'iShares MSCI USA Min Vol Factor ETF'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We first define a simple percent change function. We do this for the sake of clarity and cleanliness, since we use its functionality multiple times in our analysis. It returns the actual percentage, since we use it mostly for analysis and not calculation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 270,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Provides the percent change from the first price to the last price of a list of prices\n",
    "def get_pct_change(prices):\n",
    "    # First and last price\n",
    "    start = prices[0]\n",
    "    end = prices[-1]\n",
    "\n",
    "    # Calculate\n",
    "    diff = end - start\n",
    "    pctchange = diff / start * 100\n",
    "\n",
    "    return(pctchange)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we define our analysis dates, and retrieve the closing prices for the fund and the portfolio across those dates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 271,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MODIFIABLE #\n",
    "\n",
    "# For graphing the returns between two dates over multiple periods (4.4)\n",
    "#   MUST BE VALID TRADING DAYS\n",
    "returns_check_start = '2023-05-03' # Recommended to be as close as possible to variable 'end'\n",
    "returns_check_end = '2023-07-07'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 272,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MODIFIABLE #\n",
    "\n",
    "# Subset of returns_check_* to check for one period (should be numdays trading days, 5 trading days here)\n",
    "#   MUST BE VALID TRADING DAYS\n",
    "one_period_start = '2023-06-08'\n",
    "one_period_end = '2023-06-15'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 273,
   "metadata": {},
   "outputs": [],
   "source": [
    "# For analysis, how many trading days per period\n",
    "tdays_per_period = numdays"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 274,
   "metadata": {},
   "outputs": [],
   "source": [
    "analysis_portfolio_closing_dict = {}\n",
    "\n",
    "# Get ticker prices for analysis dates\n",
    "for ticker in valid_tickers:\n",
    "    tick_obj = Stock(ticker = ticker)\n",
    "    tick_hist = tick_obj.history(start = returns_check_start, end = returns_check_end, interval = '1d')\n",
    "\n",
    "    analysis_portfolio_closing_dict[ticker] = tick_hist['Close']\n",
    "\n",
    "analysis_portfolio_closing_df = pd.DataFrame(analysis_portfolio_closing_dict)\n",
    "\n",
    "# Get fund prices for analysis dates\n",
    "analysis_fund_closing_dict = {}\n",
    "\n",
    "fund_obj = Stock(ticker = fund_ticker)\n",
    "analysis_fund_closing_df = fund_obj.history(start = returns_check_start, end = returns_check_end, interval = '1d')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 275,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Grab number of implied periods, edit end date of DataFrames to reflect tdays_per_period * num_periods trading days (slice to new end date)\n",
    "\n",
    "analysis_index = analysis_fund_closing_df.index\n",
    "num_periods = (len(analysis_index) - 1) // tdays_per_period\n",
    "returns_check_end = analysis_index[num_periods * tdays_per_period]\n",
    "\n",
    "analysis_fund_closing_df = analysis_fund_closing_df.loc[returns_check_start : returns_check_end, :]\n",
    "analysis_portfolio_closing_df = analysis_portfolio_closing_df.loc[returns_check_start : returns_check_end, :]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We collect the prices for the weighted portfolio and the fund across the one_period_start and one_period_end dates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 276,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get prices from start date to end date\n",
    "one_period_fund_prices = analysis_fund_closing_df['Close'].loc[one_period_start:one_period_end].values.tolist()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 277,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Reorder the columns of the DataFrame according to tickers_uniform_order\n",
    "analysis_portfolio_closing_df = analysis_portfolio_closing_df[tickers_uniform_order]\n",
    "\n",
    "# We will scale each price such that the first price of each ticker is 'capital' multiplied by their weight in the portfolio\n",
    "#  (Which is the allocation of capital to that security)\n",
    "for c in range(num_ticks_final):\n",
    "    column = analysis_portfolio_closing_df.iloc[:, c]\n",
    "    # If startPrice * scale = allocation = weight * capital, then scale = (weight * capital) / startPrice\n",
    "    scale = (optimal_weighting[c] * capital) / column[0]\n",
    "\n",
    "    # Applying scale\n",
    "    for row in range(0, len(column.index)):\n",
    "        column[row] *= scale\n",
    "\n",
    "# Grab a sum of the rows (portfolio value)\n",
    "analysis_portfolio_closing_df['WEIGHTED TOTAL'] = analysis_portfolio_closing_df.sum(axis = 1)\n",
    "analysis_portfolio_closing_df = analysis_portfolio_closing_df[['WEIGHTED TOTAL']]\n",
    "\n",
    "one_period_portfolio_prices = analysis_portfolio_closing_df.loc[one_period_start:one_period_end, 'WEIGHTED TOTAL'].values.tolist()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we calculate the percent change of the portfolio and fund over the specified time frame, and present the results. Here, the user can see how the portfolio's performance compares to the estimated performance, as well as the benchmark."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 278,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Return of portfolio from 2023-06-08 to 2023-06-15: 0.35%.\n",
      "Expected return for time period \"5 Days\" for reference: 0.2%.\n",
      "Return of fund \"iShares MSCI USA Min Vol Factor ETF\" during this time period for reference: 2.24%.\n"
     ]
    }
   ],
   "source": [
    "# Get returns\n",
    "fund_return = get_pct_change(one_period_fund_prices)\n",
    "port_return = get_pct_change(one_period_portfolio_prices)\n",
    "\n",
    "# Summary\n",
    "print(f\"Return of portfolio from {one_period_start} to {one_period_end}: {np.round(port_return, 2)}%.\")\n",
    "print(f\"Expected return for time period \\\"{frequency}\\\" for reference: {np.round(port_expected_return, 2)}%.\")\n",
    "print(f\"Return of fund \\\"{fund_name}\\\" during this time period for reference: {np.round(fund_return, 2)}%.\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 4.4 Graphed Returns Check With Additional Data and Low Volatility ETF Comparison"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this section, we graph metrics related to portfolio performance over a time period following the portfolio creation analysis period.\n",
    "    \n",
    "We use this information to assess our portfolio. Specifically, 6 main characteristics should be present:\n",
    "     \n",
    "1. The average return of the portfolio (blue line) should be close to the expected return of the portfolio (blue dotted line).\n",
    "2. The average return of the portfolio should be closer to 0% (yellow dotted / dashed line) than the fund's average return (red line).\n",
    "3. The average distance from a 0% return of our portfolio should be smaller than that of the fund.\n",
    "4. The portfolio should have a greater percentage of returns closer to 0% than the fund.\n",
    "5. The standard deviation of portfolio returns should be relatively low.\n",
    "6. The absolute total return of the portfolio should be lower than that of the fund.\n",
    "\n",
    "If all of these characteristics are present, we consider the portfolio a success, as this would indicate we have made a good prediction of expected return, beat the benchmark in terms of our goal, and have a system that is likely to perform well if run with different information, or over a different time period."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, we gather a list of closing prices."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 279,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Grab price information across all dates (DataFrame)\n",
    "many_periods_fund_prices = analysis_fund_closing_df['Close'].values.tolist()\n",
    "many_periods_portfolio_prices = analysis_portfolio_closing_df['WEIGHTED TOTAL'].values.tolist()\n",
    "\n",
    "# For reference when adding dates for x axis\n",
    "portfolio_prices_series = analysis_portfolio_closing_df.loc[:, 'WEIGHTED TOTAL']"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, we grab a list of daily returns for every specified number of trading days over the specified number of intervals from the specified start date (returns_check_start) to the specified end date (returns_check_end). We also calculate the total return for the portfolio and fund."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 280,
   "metadata": {},
   "outputs": [],
   "source": [
    "fund_returns = []\n",
    "port_returns = []\n",
    "x_axis = []\n",
    "\n",
    "# Grab the daily returns for each period specified by the user, add to list\n",
    "for p in range(num_periods):\n",
    "    start_index = p * tdays_per_period\n",
    "    end_index = start_index + tdays_per_period + 1\n",
    "\n",
    "    # Grabbing price data for the current interval\n",
    "    fund_interval = many_periods_fund_prices[start_index : end_index]\n",
    "    portfolio_interval = many_periods_portfolio_prices[start_index : end_index]\n",
    "\n",
    "    # Convert to percent change\n",
    "    fund_returns.append(get_pct_change(fund_interval))\n",
    "    port_returns.append(get_pct_change(portfolio_interval))\n",
    "\n",
    "    # Grab end date of interval for graphing purposes\n",
    "    x_axis.append(portfolio_prices_series[start_index : end_index].index[-1])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 281,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the total return (%)\n",
    "portfolio_total_return = get_pct_change(many_periods_portfolio_prices)\n",
    "fund_total_return = get_pct_change(many_periods_fund_prices)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we plot all of the data, along with some additional statistics."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 282,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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+OILde/eXZcuXVJoaKgeeughvf3223rttdf08ccfq1atWpKU4ylkI0eOVP369TV9+nQ5OTnJz89PknXU2yOPPKL+/fvrpZde0vr16zVhwgT5+vpq9OjRkqQvvvhCgwYN0gsvvKD33ntPTk5OOnLkiPbv35/pMa9cuaJmzZrp6NGjGjdunKpVq6YNGzZo4sSJCg8P1/Lly21T4wYNGqTY2Fh9/vnnkm484is8PFxDhw7V2LFj5e/vr88//1xDhgzR1atXNXz4cEnWv4w2aNBAV69e1YQJExQcHKxly5Zp+PDhOnr0aJqpnB9++KHKly+v9957Tz4+PipWrJhmz56tvn376vXXX9dDDz0kSSpRooS6deumhQsX6s0337RNKS5atKgkaeLEiXrttdf0xBNPaOLEifrnn380duxY1a9fX9u3b1e5cuWyfN+ycg0zc/ToUdWvX19PPfWUfH19dezYMf3nP//Rgw8+qN9++02urq529bt06aLu3burf//++u233zRy5EhJsiW0jDHq1KmTNm3apNGjR6tu3brauHFjlkbdPPTQQ9q8ebPq16+vrl276qWXXsrydbjenj179NJLL+nVV19VsWLF9Omnn6p///4qW7asGjduLMk6PbtFixYKDg5WWFiYvLy8NHXqVC1YsCBLx1iwYIF69uyp1q1ba+HChYqPj9ekSZPUtGlTrVmzRg8++KA6dOggPz8/zZ49Wy1atLDbPywsTLVq1VK1atUkZe13n1q/fv300EMPad68ebp48WKae5UVN7qfmzdvVvPmzdWsWTNbcszHx0eSNeFWr149OTk5afTo0SpTpow2b96sN998U8eOHdPs2bPtjnX976dcuXLq0KGD5syZo3HjxsnJ6dq/r8+ePVtubm62ka1nz56VJI0ZM0b+/v66cOGClixZYrvWmb3ncNiwYZo3b57efPNN1axZUxcvXtS+ffv0zz//ZHptDh48qAYNGsjPz08ffvihChcurPnz5ys0NFSnTp3SiBEjcvzMrl+/Xvnz59eVK1dUrlw59e/fX0OHDpWzs3OW9s9IYGCgateurU2bNikxMVEuLi5ZunYWi0UvvPCChg4dqsOHD9v1QXPnzlVcXJwt6TZp0iSNHTtWr7/+uho3bqyEhAQdOHAgW++rBADcpgwAAHeo2bNnG0lmy5YtJiEhwZw/f96sWLHC+Pv7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AHl6eqphw4YKCAhQTEyMJk6cKF9fX9WtWzfD/Xr37q2PP/5Yffr00bFjx3Tffffp119/1dtvv6327durZcuWOY4pMDBQjzzyiMaOHauAgADNnz9fq1ev1jvvvGNLhrz44ouaO3euHnroIY0fP16lSpXS8uXLNXXqVD377LN2K8pmpEyZMvL09NTnn3+uSpUqKV++fAoMDMww4VCgQAG98cYbeu2119S7d2898cQT+ueffzRu3Dh5eHhozJgx2TrPm7mGFStWVJkyZfTqq6/KGKNChQrp+++/v+G04My0bt1ajRs31ogRI3Tx4kXVqVNHGzdu1Lx583LcpiS1b99ehQoVUv/+/TV+/Hi5uLgoLCxMJ06cyHGbr7/+ur777js1b95co0ePlpeXlz7++GPb+6wy4+TkpEmTJqlnz57q0KGDnnnmGcXHx+vdd9/VuXPn9H//93929QsUKKBHH31UYWFhOnfunIYPH55mVFNWf/e32n333ad169bp+++/V0BAgPLnz68KFSpo/PjxWr16tRo0aKDBgwerQoUKunLlio4dO6YffvhB06dPV4kSJbJ0jH79+umZZ57RyZMn1aBBgzSj+jp06KAJEyZozJgxatKkiQ4ePKjx48crJCREiYmJmbZ9//33q0OHDqpWrZoKFiyoiIgIzZs3L01i9Hpjxoyxvbdu9OjRKlSokD7//HMtX75ckyZNkq+vb5bOLbUFCxZo8eLFeuihh1SqVCmdO3dOX3/9tb744guFhoameQ9lRqKiorRlyxYlJycrNjZWu3fvtk3xf//99+0Sutm9dq1atVLlypW1du1aPfnkk7aVrFM8/PDDqlq1qurUqaOiRYvq+PHjmjx5skqVKpWtlZcBALehPFzEAQCAm5LeSpYpLl++bEqWLGnKlStnEhMTjTHG7Nmzx3Tr1s34+fkZV1dX4+/vb5o3b26mT59ut+/kyZNNSEiIcXZ2tluhMDk52UyaNMmULl3aeHh4mDp16piff/45w9VLv/766zRx9enTx3h7e6cpv34lyTlz5phmzZqZYsWKGTc3NxMYGGi6detm9u7de8Pr8s8//5iBAweagIAA4+LiYkqVKmVGjhxprly5Ylcvu6uXPvTQQ+abb74xVapUMW5ubiY4ONj85z//SVP3+PHjpkePHqZw4cLG1dXVVKhQwbz77rt2K1LeaMXAhQsX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mzbV888/r2HDhqlIkSJq1aqV7flas2aN6tSpIy8vLzVo0EAHDx7M8BwsFot27typ8ePHy2Kx2EZ0/fbbb2revLk8PT1VuHBhPf3007pw4YJtv5QYJ06cqMDAQJUvXz7d9lNGcc6YMUNBQUHy8vLSY489pnPnztnVmz17tipVqiQPDw9VrFhRU6dOtX2XMiLrq6++UtOmTeXh4aH58+enO7102rRpKlOmjNzc3FShQgXNmzfP7vvDhw+rcePG8vDwUOXKlbV69eoMr01WFShQwO534enpecN98ufPL39/f5UsWVKNGzfWzJkz9cYbb2j06NG2+5WUlKT+/fsrJCREnp6eqlChgqakvFRV0vr16+Xq6qqYmBi7tl966SU1btxYknT8+HE9/PDDKliwoLy9vVWlShX98MMPN33OAAAAAJCb7pik28SJE1W3bl3lz59ffn5+6tSpU6Z/CU/xyy+/2CULbjRlylEuXrR+jLlWdvWqtSw+Pv26ycnXyhISrGVXrty4riN4enoqISFBkjRixAgtWrRIc+bM0a5du1S2bFm1adNGZ8+etdtnxIgRmjhxoiIiItS6dWu99NJLtlFT0dHR6t69u7Zv3662bduqW7duio6O1pQpU2SMUadOnXT27Fn98ssvWr16tY4eParu3btnOd6sxpgdvXv3Vvv27dWzZ08lJiZqxYoVmjFjhj7//HN5e3vb6r377ruqVq2adu3apZEjR+rFF1+0JT2MMXrooYcUExOjH374QTt37lStWrXUokULW2zLly9X586d9dBDD2n37t225JIkLV68WCVKlLCNIIqOjpZkTR61adNGnTt31t69e/Xll1/q119/1fPPP2+LKzQ0VMeOHdPPP/+sb775RlOnTtXp06ezdQ1iYmK0ePFiOTs7y/l/w35XrlypJ598UoMHD9b+/fs1Y8YMhYWF2UYzpSQ7U0ZKZSX5mdqcOXPk4uKijRs3asaMGbbyUaNG6f3339eOHTvk4uKifv36ZdhGdHS0qlSpopdeeknR0dEaPny4Ll26pLZt26pgwYLavn27vv76a/30009210yS1qxZo4iICK1evVrLli3L8BhHjhzRV199pe+//14rVqxQeHi4nnvuOdv3n3zyiUaNGqW33npLERERevvtt/XGG29ozpw5du288sorGjx4sCIiItSmTZs0x1myZImGDBmil156Sfv27dMzzzyjvn37au3atZKk5ORkde7cWc7OztqyZYumT5+uV155JfOLnAXPP/+8ihQporp162r69OlKzmEnM2TIEBlj9O2339riLVGihL766ivt379fo0eP1muvvaavvvpKktS4cWOVLl3aLrGYmJio+fPnq2/fvpKk5557TvHx8Vq/fr1+++03vfPOO8qXL99NnjEAAAAA5DJzh2jTpo2ZPXu22bdvnwkPDzcPPfSQKVmypLlw4UKG+/zxxx/Gy8vLDBkyxOzfv9988sknxtXV1XzzzTdZPm5sbKyRZGJjY9N8d/nyZbN//35z+fLlNN9Z023GnD59rezNN61lTz1lX9fLy1oeGXmt7IMPrGU9etjXLVLEWr5vX5ZPIY0+ffqYjh072ra3bt1qChcubLp162YuXLhgXF1dzeeff277/urVqyYwMNBMmjTJGGPM2rVrjSSzdOlSu3bHjBljqlevnuZ4HTt2NH369LFtr1q1yjg7O5uoqChb2e+//24kmW3btqXbVuqYsxJjepo0aWJcXV2Nt7e33ScsLMxW5+zZs6ZEiRLm2WefNcWKFTNvvvmmXRulSpUybdu2tSvr3r27adeunTHGmDVr1hgfHx9z5coVuzplypQxM2bMMMYYU79+fdOzZ88M4yxVqpT54IMP7Mp69eplnn76abuyDRs2GCcnJ3P58mVz8OBBI8ls2bLF9n1ERISRlKat1MaMGWOcnJyMt7e38fT0NJKMJDN48GBbnUaNGpm3337bbr958+aZgIAA27Yks2TJErs61z9nxhgzZMgQ06RJE9t2kyZNTI0aNezqpDxfP/30k61s+fLlRlK6v7UU1atXN2PGjLFtz5w50xQsWNCuj1i+fLlxcnIyMTExthiLFStm4uPjM2zXGOt1cnZ2NidOnLCV/fjjj8bJyclER0cbY4wJCgoyCxYssNtvwoQJpn79+sYYYyIjI40kM3nyZLs6s2fPNr6+vrbtBg0amAEDBtjVeeyxx0z79u2NMcasXLky3VjSuwdZNWHCBLNp0yaze/du89577xkvLy8zYcKETPdJ7zlNUaxYMfPss89muO+gQYNMly5dbNvvvPOOqVSpkm176dKlJl++fLZ7d99995mxY8dm44zSl1mfDQAAAABZlVmuKDWXPMn05cCKFSvstmfPni0/Pz/t3LnTNgXpetOnT1fJkiVtL6WvVKmSduzYoffee09dunTJ7ZBva8uWLVO+fPmUmJiohIQEdezYUR999JGOHj2qhIQENWzY0FbX1dVV9erVU0REhF0bKaOzsisiIkJBQUEKCgqylVWuXFkFChRQRESE6tatm+n+2Ynxej179tSoUaPsylK/T6tgwYL67LPP1KZNGzVo0ECvvvpqmjbq16+fZjvlGdu5c6cuXLiQ5p1ily9f1tGjRyVJ4eHhGjBgQKZxXm/nzp06cuSI3ZRRY4ySk5MVGRmpQ4cOycXFxe6eVKxYMUvvwatQoYK+++47xcfH69tvv9XXX39t906unTt3avv27XZlSUlJunLlii5duiQvL69sncv1MnqOqlWrZvtzQECAJOsU2pIlS2ap3YiICFWvXt1ulGLDhg2VnJysgwcPqlixYpKk++67T25ubjdsr2TJkipRooRtu379+ra2nJ2ddeLECfXv39/u3iYmJsrX19eunRv9biIiIvT000/blTVs2NA2JTMiIiLdWG7G66+/bvtzymIo48ePtyvPDmOM3dTo6dOn69NPP9Xx48d1+fJlXb16Nc3qxK+//rq2bNmiBx54QLNmzVK3bt1s927w4MF69tlntWrVKrVs2VJdunSxez4AAAAA4HZ0xyTdrhcbGytJKlSoUIZ1Nm/erNatW9uVtWnTRp999pkSEhLk6uqaZp/4+HjFp5r/mfq9VtmR8tqo1PmIl1+Whg6VXK676ikzAFO/Qum556QBA9Iu7JGy4GAWXreUqWbNmmnatGlydXVVYGCg7VqkTGdM/RdmKe1foiXZJTOyI722MitPr15WY7yer6+vypYtm2md9evXy9nZWSdPntTFixdt73zLTMpxk5OTFRAQoHXr1qWpk5IAy8q7sq6XnJysZ555RoMHD07zXcmSJW1TrbNy/a7n5uZmuyZVqlTR4cOH9eyzz9qm+yUnJ2vcuHG2986l5uHhkWG7Tk5OtnuVImUKc2oZPUepf5+pr29WZfY8pC7P6XOc0obFYrHF9cknn+j++++3q+d83Y84K8fL7Nm+/pqmV/9mPfDAA4qLi9OpU6dsycms+ueff/T3338rJCREkvTVV1/pxRdf1Pvvv6/69esrf/78evfdd7V161bbPn5+fnr44Yc1e/ZslS5dWj/88IPdb+ipp55SmzZttHz5cq1atUoTJ07U+++/rxdeeMEh5wsAAAAAueGOeadbasYYDRs2TA8++KCqVq2aYb2YmJg0f2EsVqyYEhMTdebMmXT3mThxonx9fW2f1KOxssPb2/pJ/XdhNzdrmbt7+nWdUt0NV1dr2fU5jfTq5iw+b5UtW1alSpWyS26ULVtWbm5u+vXXX21lCQkJ2rFjhypVqpRpm25ubkpKSrrhsStXrqyoqCidOHHCVrZ//37Fxsbe8Bg3G+ONbNq0SZMmTdL3338vHx+fdP9Sv2XLljTbFStWlCTVqlVLMTExcnFxUdmyZe0+RYoUkWQdwbVmzZoMY0jvOtaqVUu///57mjZTrkWlSpWUmJioHTt22PY5ePBgmhf9Z8Ubb7yhhQsXateuXbZjHzx4MN1jO/3vQXR1dU0Tc9GiRW1J3BTh4eHZjienKleurPDwcLvFJjZu3CgnJ6cMF0zITFRUlE6ePGnb3rx5s62tYsWKqXjx4vrjjz/SXKOU5FNWVapUye7ZlqzPZcqznfL7uT4WR9q9e7c8PDxytGLwlClT5OTkZFtEY8OGDWrQoIEGDRqkmjVrqmzZsrZRn6k99dRT+uKLLzRjxgyVKVPGbiSrJAUFBWngwIFavHixXnrpJX3yySc5OTUAAAAAuGXuyJFuzz//vPbu3ZvmL6bpSW/ESHrlKUaOHKlhw4bZtuPi4nKceLsTeXt769lnn9XLL7+sQoUKqWTJkpo0aZIuXbqk/v37Z7pvcHCwIiMjFR4erhIlSih//vxyvz7DKKlly5aqVq2aevbsqcmTJysxMVGDBg1SkyZNsjRl9WZivHTpUppVEt3d3VWwYEGdP39evXr10gsvvKB27dqpZMmSqlOnjjp06KDHHnvMVn/jxo2aNGmSOnXqpNWrV+vrr7/W8uXLbedWv359derUSe+8844qVKigkydP6ocfflCnTp1Up04djRkzRi1atFCZMmX0+OOPKzExUT/++KNGjBhhu47r16/X448/Lnd3dxUpUkSvvPKKHnjgAT333HMaMGCAvL29bS///+ijj1ShQgW1bdtWAwYM0MyZM+Xi4qKhQ4fmaFRd6dKl1bFjR40ePVrLli3T6NGj1aFDBwUFBemxxx6Tk5OT9u7dq99++01vvvmmLeY1a9aoYcOGtuvZvHlzvfvuu5o7d67q16+v+fPna9++fapZs2a2Y8qJnj17asyYMerTp4/Gjh2rv//+Wy+88IJ69eqV7dFbknVUX58+ffTee+8pLi5OgwcPVrdu3eTv7y/JusLp4MGD5ePjo3bt2ik+Pl47duzQv//+a9en3MjLL7+sbt262Rbg+P7777V48WL99NNPkqzPWIUKFdS7d2+9//77iouLSzNlOju+//57xcTEqH79+vL09NTatWs1atQoPf300+n+flM7f/68YmJilJCQoMjISM2fP1+ffvqpJk6caBs9WbZsWc2dO1crV65USEiI5s2bp+3bt6dJRrZp00a+vr568803NX78eLvvhg4dqnbt2ql8+fL6999/9fPPP990gh0AAAAAcl3uvVYudzz//POmRIkS5o8//rhh3UaNGtm9EN4YYxYvXmxcXFzM1atXs3S8nC6kcDtL7wX3qV2+fNm88MILpkiRIsbd3d00bNjQtsCBMddedP/vv//a7XflyhXTpUsXU6BAASPJzJ492xiTdiEFY4w5fvy4eeSRR4y3t7fJnz+/eeyxx2wvtzcm84UUshJjepo0aWJbKCD1p02bNsYYY/r27Wvuu+8+u0UQpkyZYgoVKmT+/PNPY4z15fHjxo0z3bp1M15eXqZYsWJpXowfFxdnXnjhBRMYGGhcXV1NUFCQ6dmzp93CEYsWLTI1atQwbm5upkiRIqZz58627zZv3myqVatm3N3dTeqf6LZt20yrVq1Mvnz5jLe3t6lWrZp56623bN9HR0ebhx56yLi7u5uSJUuauXPnZvqy+/Suc4qNGzfaLcywYsUK06BBA+Pp6Wl8fHxMvXr1zMyZM231v/vuO1O2bFnj4uJiSpUqZSsfPXq0KVasmPH19TUvvviief7559MspDBkyBC7Y6f3fO3evdtIMpGpVxu5zvULKRhjzN69e02zZs2Mh4eHKVSokBkwYIA5f/687fsb/RZSpFynqVOnmsDAQOPh4WE6d+5szp49a1fv888/t93XggULmsaNG5vFixcbY64tpLB79267fa5fSMEYY6ZOnWpKly5tXF1dTfny5c3cuXPtvj948KB58MEHjZubmylfvrxZsWJFjhdS+PHHH02NGjVMvnz5jJeXl6lataqZPHmySUhIyHS/UqVK2X5Dbm5upmTJkqZbt27m559/tqt35coVExoaanx9fU2BAgXMs88+a1599dV0n7s33njDODs7m5MnT9qVP//886ZMmTLG3d3dFC1a1PTq1cuc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cXZ2TnfE1NChQ9W0aVPbdtOmTTV48GCNGDFChQoVkr+/v8aOHWu3z+HDh9W4cWN5eHiocuXKWr16dZbiunjxor766is9++yz6tChg8LCwmzf1a9fX6+++qpd/b///luurq5au3atJOnq1asaMWKEihcvLm9vb91///1at26drX5YWJgKFCigZcuWqXLlynJ3d9fx48e1fft2tWrVSkWKFJGvr6+aNGmiXbt22R3rwIEDevDBB23n9NNPP6WZMvvXX3+pe/fuKliwoAoXLqyOHTvq2LFjNzzvwoULy9/fXxUrVtRbb72lhIQE2zndqN2xY8dqzpw5+vbbb20j5tatW6d169bJYrHo3LlztnbCw8NlsVhs+2Z0PYKDg/X222+rX79+yp8/v0qWLKmZM2fe8DwAAAAAAIAVSTdHu3RJypfv1n8uXbqlpzlnzhx5e3tr69atmjRpksaPH29LrCUnJ6tz585ydnbWli1bNH36dL3yyitZavfLL79UhQoVVKFCBT355JOaPXu2zP8Sij179tTChQtt2yn1ixUrpiZNmkiS+vbtq40bN+qLL77Q3r179dhjj6lt27Y6fPiwbZ9Lly5p4sSJ+vTTT/X777/Lz89P58+fV58+fbRhwwZt2bJF5cqVU/v27XX+/HnbOXXq1EleXl7aunWrZs6cqVGjRtnFfunSJTVr1kz58uXT+vXr9euvvypfvnxq27atrl69mqXzT0hI0CeffCJJcnV1zVK7w4cPV7du3exGLzZo0CBLx8voekjS+++/rzp16mj37t0aNGiQnn32WR04cCDL7QIAAAAAcC9zyesAkDeWLVumfPny2bbbtWunr7/+Osv7V6tWTWPGjJEklStXTv/973+1Zs0atWrVSj/99JMiIiJ07NgxlShRQpL09ttvq127djds97PPPtOTTz4pyToF9sKFC1qzZo1atmyp7t2768UXX9Svv/6qRo0aSZIWLFigHj16yMnJSUePHtXChQv1559/KjAwUJI0fPhwrVixQrNnz9bbb78tyZrYmjp1qqpXr247bvPmze3imDFjhgoWLKhffvlFHTp00KpVq3T06FGtW7dO/v7+kqS33npLrVq1su3zxRdfyMnJSZ9++qksFoskafbs2SpQoIDWrVun1q1bZ3jeDRo0kJOTky5fvqzk5GQFBwerW7duWW7X09NT8fHxttiyI73rIUnt27fXoEGDJEmvvPKKPvjgA61bt04VK1bM9jEAAAAAALjXkHRzNC8v6cKFvDluNjRr1kzTpk2zbXt7e2dr/2rVqtltBwQE6PTp05KkiIgIlSxZ0pZwk6xTQ2/k4MGD2rZtmxYvXixJcnFxUffu3TVr1iy1bNlSRYsWVatWrfT555+rUaNGioyM1ObNm23nsWvXLhljVL58ebt24+PjVbhwYdu2m5tbmvhPnz6t0aNH6+eff9apU6eUlJSkS5cu2d4pd/DgQQUFBdklterVq2fXxs6dO3XkyBHlz5/frvzKlSs6evRopuf+5ZdfqmLFijp06JCGDh2q6dOnq1ChQjfdblakdz0k+3tssVjk7+9vu8cAAAAAACBzJN0czWKRspnAygve3t4qW7ZsmnInJye76ZuSdSTU9VKmPqawWCy2F/Bfv3/K9zfy2WefKTExUcWLF7eVGWPk6uqqf//9VwULFlTPnj01ZMgQffTRR1qwYIGqVKliG6GVnJwsZ2dn7dy5U87OznZtpx7V5+npmSae0NBQ/f3335o8ebJKlSold3d31a9f3zYt1Bhzw3NITk5W7dq19fnnn6f5rmjRopnuGxQUpHLlyqlcuXLKly+funTpov3798vPzy/H7To5OdliT5HevUzvekiZ32MAAAAAAJA53ukGO0WLFlV0dLRdWXh4eLbaqFy5sqKionTy5Elb2ebNmzPdJzExUXPnztX777+v8PBw22fPnj0qVaqULeHUqVMnXblyRStWrNCCBQtsU1ElqWbNmkpKStLp06dVtmxZu8+Npl1u2LBBgwcPVvv27VWlShW5u7vrzJkztu8rVqyoqKgonTp1yla2fft2uzZq1aqlw4cPy8/PL83xfX19b3zh/qdJkyaqWrWq3nrrrSy36+bmpqSkJLt2UhJyqe9ndu8lAAAAAADIGZJusNO8eXPt2LFDc+fO1eHDhzVmzBjt27cvW220bNlSFSpUUO/evbVnzx5t2LAhzaID11u2bJn+/fdf9e/fX1WrVrX7dO3aVZ999pkk6wi9jh076o033lBERIR69Ohha6N8+fLq2bOnevfurcWLFysyMlLbt2/XO++8ox9++CHT45ctW1bz5s1TRESEtm7dqp49e8rT09P2fatWrVSmTBn16dNHe/fu1caNG23nlDJKrGfPnipSpIg6duyoDRs2KDIy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vLEyjsXy1FNP5dBDD81bb72VOXPmpKamJs8880xefvnlvPjii+nRo0c23XTTSo9JFWrtHYTSjYXsvPPOqampyfnnn5+VVlopb7zxRp544oncfffdueOOO9KxY8dcfvnlfqrBlzZs2LCstNJKOe2007LXXnvl4Ycfzplnnpn99tsvyyyzTJqamlwKwWKZMGFCRowYkY033jgzZszISy+9lAEDBmSVVVbJVVddlXvuuScbbrhh2rdvX+lRqTI//OEPc+WVV2bEiBHZY4898r3vfS/dunVbaM2rr76a++67L3vssYdijkW2yy67pGPHjrn00kuTJAcccEAmT56cv//979lss83yyiuvZLfddsuxxx5b4UmpNsOHD0/nzp1z+eWX56677sqoUaPy6KOPpnPnzimVShkwYEAuu+yy9O7du9KjUmUW/D13/vnnZ/nll8+OO+6Y7t2759prr82KK66Ynj175qyzzlK88aW19g5C6cZCvvnNb+bnP/95dtppp0/te+655zJy5MgMGjQoV199dQWmo5ots8wyuffee7PBBhskSY4//vhcd911Of744/PjH/+4wtNR7caMGZN//OMfGTVqVB566KGWy7bmz5+fLbbYIoMHD87IkSOr+qdkfP1WX331/Pu//3tee+213H777enSpUuGDRuWvfbaKxtuuGGWW265HHrooZkyZUpuvvnmSo9LFfm3f/u3jB49OltuuWWSZIMNNsigQYPyq1/9Kh06dMiJJ56YcePG5bbbbstqq61W4WmpJksttVSefPLJfPOb38zWW2+dXr165bjjjsvAgQPz2GOPZfjw4fn+97+fyy67rNKjUmW6du2av/zlL9lkk02SJIMHD0737t3zy1/+Mt27d8/IkSPTsWPH3H777RWelGrT2jsIp5XQ4oMPPsjgwYNz9tln5913303SfIPfxsbGJMnAgQMzatSo/OMf/8hLL71UyVGpMhdddFFWWmmlbLDBBpk/f36S5Oijj852222Xgw46KAceeGBee+21Ck9JNdtqq63y0EMP5YILLshGG22U0047LY2NjTnmmGPStWvX/PrXv87bb79d6TGpIs8880xWWWWV7LDDDrn55pszadKknHzyyXniiSdaitzjjz8+Y8aMya677lrpcakiDQ0N+cY3vpHLL788kydPzmOPPZbHH388Rx11VFZaaaUst9xyOe6447L00kvnzTffrPS4VJHbbrstjY2N+ctf/pKrrroqTz75ZH76059m4MCBSZL1118/RxxxRCZNmiRbfCn33HNPVl999ayyyipJknfeeSd///vf8+tf/zrf+ta30qtXr5x00kmZM2dOJk2aVNlhqSptoYNQutFimWWWyYEHHpj6+vqcfPLJmTx5cmpra1NbW9uyZoUVVsjUqVOz+uqrV3BSqs2LL76Y/fffP0la8rTSSitl9OjRufzyy3PvvffmF7/4RSVHpMqttNJKOf300/OrX/0qjz/+eMaNG5eOHTvmlFNOyaWXXprp06dn8803r/SYVJEuXbpkt912a7mUoUePHjnssMPyyCOP5Jlnnsluu+2WCy+8MEmy9957V3JUqkyXLl0ycuTI3H///dlll11y/PHHZ80118zkyZNb1kyaNClTp07NxhtvXMFJqTbt27fPyJEjc+edd+b444/Peuutl65duy60ZtCgQXnjjTfSvXv3Ck1JNVpmmWUyfPjwlh+eT58+PWedddZCVxB07Ngx9fX16devX4WmpBq1hQ7C5aW0WBCFa6+9NieeeGKmTp2aLbfcMrvttltWX3313HXXXbntttuy+uqrt9yDBBbXgnu4ffjhh7nuuuuy11575fjjj88ZZ5xR6dGoQgvydOGFF+b+++/PI488ks022yznn39+GhsbU1tb60m5fGlNTU1pampa6H6AH8/RDjvskE6dOuXKK6+s1IhUoVKplKamplx//fV55pln8uMf/zjnnXdepk6dmrPOOisPPvhgLrzwwvTs2TMXX3xxpcelysyfPz+PP/547r777iy11FLZb7/90qVLl5b9++23X957771ce+21FZySatTU1JQkadeuXUqlUj788MMsvfTSLfv333//zJ49W7b4Uhbk6pprrslJJ52UadOmtboOQunGZ3r//fdz44035qqrrsqECRNSU1OTHj16ZNiwYflf/+t/pVevXpUekSqx4B8XH/9pxWe5/fbb841vfCP9+/f/miajNZo5c2b+4z/+I3/7298ybtw4Z4lQNk1NTSmVSi3/L3vrrbeyzjrr5I9//GO22GKLCk9HtXv00UczfPjwvPHGG+nUqVO22WabnH766VX7U30qY8EPmRaYO3du6urqWl6PGTMmxx13XK655pp85zvfqcSIVKFF+aHl1VdfnRNPPDF//OMfPUiBxbagg7jyyiszYcKEtGvXrlV0EEo3FvLJgqRUKqVUKuWll15K+/btFSIUwhlILK433ngjtbW1WWGFFVr+v1VfX5/HH388W2+9tSeWslhKpVJefPHFTJ48ObNmzcomm2ySHj16LLR/5syZuffee7PddttVcFKqzYJsvfrqq5kxY0a++93vZuWVV27Zf/fdd+fdd9/Njjvu6IneLJYFx/Lt2rVb6Njqgw8+yO9///tMnDgx559/fgUnpBp98njr48fuH3zwQS699NK89NJLOfPMMys8KdVk7ty5eeaZZ/Lee+9l3XXXTefOnRfa/9xzz6Wurq7qOwilG/nwww8za9asrLDCCooPykq2KEpDQ0MuvvjinH766UmSESNG5Oyzz17oEhpYHNOnT8+oUaNy3nnnpVevXunWrVsaGhqy7rrrZp999sl2222nzGWxfF621llnney1117Zcccds9RSS1V6TKqQ4y2K4niLokyfPj2nnXZafvvb32bFFVfMyJEjc/7556e2tjYvvPBCVl111YUuX65mfoRGfv/73+eAAw7In/70p7z00kv54IMPPrXmnXfeyfPPP1+B6ahmi5KtGTNm5IUXXqjAdFSz0aNHZ8yYMTn11FNzxRVX5P7778+hhx6a5KN7QzQ1NaWhoaGSY1KFfvnLX+aee+7JX/7yl9xxxx059dRTc/DBB6exsTGnnHJKTj311EqPSJX6vGw1NTXl5z//eU477bRKj0iVWpTjrXfffTfPPfdcBaajmn3R8dYCjY2Neeeddyo0IdXq7LPPzhNPPJEJEybksssuy5NPPplrrrkmG2ywQfbbb78ccsghmTp1aqXHLAtnupG+fftmzpw5aWhoSPfu3bPjjjtm+PDhWXvttdOjR4+0b98+5557bu6///5cffXVlR6XKiJbFKV37945//zzM2zYsCTJ+PHjs+uuu+ayyy7LtttumyQZO3ZsJk6cmBNOOKGSo1Jl+vfvn1GjRmX33Xdv2bbgksCxY8fm9NNPz7HHHpuTTz65glNSjWSLoizK8dbo0aNz//3355prrqn0uFSRRTneuv766/P888873uJL6d27dy644ILssMMOSZLvfOc7ef/997PNNttkxRVXzLnnnpvtt98+v/vd7yo86VfnTLc2buLEienatWtuvfXWvPvuuzn66KMzfvz4/OAHP8jWW2+dn//857n77rtz5plnZvDgwZUelyoiWxTlySefTIcOHbLeeuu1bBs6dGh23XXXXHjhhS2Psz/++ONbPodFMXPmzAwcODBPP/30Qttramqyxhpr5LjjjstPf/rTTJgwwU/1+VJki6Is6vHWWWedtdDfm/CvLOrx1gknnOB4iy/lsccey9JLL71Qth588MGccsopGTVqVP7rv/4rRx11VCZNmpS33nqrgpOWh9KtjWtqaso222yTWbNmpWPHjjnqqKPy7LPP5vnnn8+WW26Z3/3ud9l8880zbdq0T51KDF9EtijKm2++ma5du6a+vj5JWg70DjnkkDzxxBOZOHFiXn755UyaNCmHH354JUelipRKpXTu3DlbbrllLrvsslx77bWZPXv2p9Ztttlmeeyxx7LMMstUYEqqkWxRJMdbFMXxFkV58803M3z48JbXDz74YL73ve9l2223TWNjY5JkvfXWy8svv5wOHTpUaMrycXlpG9fY2JipU6emR48eWWaZZfLhhx+mtrZ2oSdm7bjjjmlsbMy4ceMqOCnVRrYoynvvvZcrrrgiO+64Y8ujw+fPn5/27dtnt912yworrJB+/frl+uuvzyOPPFLhaak2M2bMyFFHHZVrr7023//+97Pvvvtm8ODBWXbZZfP222/n7LPPzvPPP5977rmn0qNSZWSLIjjeoiiOtyjKnDlz8sorr2T11VdPXV1dGhsb89577y309NKTTjopDzzwQO68884KTloeSjc+U1NTU5qamjJr1qz07t07v/vd7/KjH/2o0mPRCsgWRbr33nvzwx/+MJMnT861116bnXfeudIjUaX+9re/5de//nXuvvvudOrUKYMGDcrDDz+c7373uzn99NOz0UYbVXpEqpRs8XVwvEWRHG9RpJdffjnbb799TjnllOy6666VHucrU7qxkHnz5i30aN633noro0ePbnlMNCwu2aJcSqVSampqWl5/MlvbbbddbrnllpanmMKX0dTUlJqampaMvfPOO7n99tvzwgsvZL311stGG22Url27VnhKqpFs8XVwvEW5ON7i6zJ37tzU1dUlab4H6gknnJCXXnopt956a4UnKw+lG0maDwTbtWuXs88+O9tuu20GDhzYsu/DDz/MUkstVcHpqGayRVE+L1uzZ8/Oww8/nC222KLCE1KtFmTrrLPOyo477pg11lhjof2f/IcILCrZoiiOtyiK4y2K8nnZmjNnTl5//fX079+/whOWh9KNlgO8adOmZZVVVsmLL77YagJOZckWRfm8bPkHK1/VJ7P1wgsvpH///nLFVyZbFMXxFkVxvEVR2lK2PL2UllOCzz333HznO9/xlzRlI1sU5fOy1dr+kubr98lsrbbaanJFWcgWRXG8RVEcb1GUtpQtpRupra1N0nzPhwMPPLDC09CayBZFkS3KZf78+Zk7d27L6wXZmj59eg466KBKjUUrIFsURbYoimxRlLacLZeXtkF//vOfs9Zaa2XNNddcaPvHb4L58ceMw6KSLYoiWxTlmmuuyTvvvJNhw4alV69eC+1rbGxM0pyt1viTV4olWxRFtiiKbFGUtpwt/0Jpg0aMGJGJEye2vJ42bVpuu+223HfffWnXrp1/uLLYZIuiyBZF+a//+q/U1dWlV69emT17di6//PLsv//+Oe+88zJ9+vTU1ta2ygNAiidbFEW2KIpsUZQ2na0Sbcodd9xRWnHFFUulUqk0d+7c0v/8z/+UlltuudLAgQNLq6++eul73/te6bHHHqvwlFQj2aIoskVR7r777lK3bt1KH374Yem9994rjRw5stSnT5/S1ltvXerdu3eptra29H/+z/8pNTY2VnpUqoxsURTZoiiyRVHaeracGtDGjB49OjvvvHOS5NJLL815552Xk046KZdffnl+/vOfZ86cOfnpT3+aefPmVXhSqo1sURTZoihPP/101l9//bRv3z4XXHBB6uvrc9NNN+XWW2/NCy+8kNNOOy0XXXRR3njjjUqPSpWRLYoiWxRFtihKW8+W0q2Nufnmm/Otb30rSfKnP/0pe++9d0488cRsuOGG2X333XP00Udn0qRJefnllys7KFVHtiiKbFGU7373u3n11Vcza9aszJgxI9///vczePDgNDU1Zdlll80+++yT5ZdfPrfcckulR6XKyBZFkS2KIlsUpa1nS+nWhkydOjWbbbZZjj766Ky44op54IEHsuWWWyZJSv//eRpDhgxJU1NTpk+fXslRqTKyRVFkiyKtueaaWWWVVTJ06NBMnTo19913X5KPHsrRp0+fTJ8+Pd26davkmFQh2aIoskVRZIuitPVseXppG1IqlTJjxoy8+uqruemmm/Laa6/lkEMOybrrrtuyZsKECRk+fHjefvvtCk5KtZEtiiJbFO3NN9/M8ccfn8ceeyxPP/10RowYkf333z+rrbZafvOb3+SGG27ItGnTKj0mVUi2KIpsURTZoihtOVtKtzbqww8/TENDQzp16pS6urokzX8QDj300NTV1WXMmDEVnpBqJVsURbYop1Kp1PKUrOeffz433XRTbrnllrz44ot577338s4772TrrbfOYYcdlu23377C01JNZIuiyBZFkS2KIltKtzblww8/zJQpU7Laaqt95v7/+Z//yU033ZRRo0Zl0KBBX/N0VDPZoiiyRVHmz5+fKVOmpH///i3b5s2blyeeeCKzZs1Kv3790q1btyy//PKVG5KqJFsURbYoimxRFNlSurUZN998c37/+9/n+eefz+uvv571118/O++8c3baaaf06tUrSTJjxoy8/vrrGThwYIWnpZrIFkWRLYryyWwNHjw4I0eOzO67757u3btXejyqmGxRFNmiKLJFUWSrmdKtDXj++eez9dZbZ6ONNsoOO+yQdu3a5a9//Wtuvvnm1NTU5D//8z9z3HHHpUOHDpUelSojWxRFtijKF2UrSQ477LCceOKJssWXJlsURbYoimxRFNn6iNKtDTjqqKMyceLEjBs3bqHts2bNysUXX5zf/OY32WuvvXLqqadWaEKqlWxRFNmiKLJFUWSLosgWRZEtiiJbH2lf6QEo3owZM7LCCiu0vG5sbEySdOrUKUcccUTmzZuX8847L7vsskvWXnvtSo1JFZItiiJbFEW2KIpsURTZoiiyRVFk6yPtKj0AxRs5cmSuv/763HjjjUmS2tra1NbWtuw/4ogj0qVLl7z88suVGpEqJVsURbYoimxRFNmiKLJFUWSLosjWR1xe2gY0NTXlyCOPzI033phtttkmW265ZTbccMOsssoqSZJbb701w4cPz1tvvZWOHTtWeFqqiWxRFNmiKLJFUWSLosgWRZEtiiJbH1G6tRHvvPNOLr744owbNy4zZ85Mjx49kiRz5szJW2+9lc022yznn39+haekGskWRZEtiiJbFEW2KIpsURTZoiiy1Uzp1sZMmzYtDz74YCZMmJDZs2dnzpw52XPPPbPFFltk2WWXrfR4VDHZoiiyRVFki6LIFkWRLYoiWxSlrWdL6dZGzJs3L0svvXT+/ve/Z7nllssaa6yRuXPnpq6urtKjUeVki6LIFkWRLYoiWxRFtiiKbFEU2WrmQQptRPv2zQ+qPeigg/KXv/wlSVJXV5empqZKjkUrIFsURbYoimxRFNmiKLJFUWSLoshWM2e6tQGlUik1NTWZOnVq1lprrTz11FPp379/pceiFZAtiiJbFEW2KIpsURTZoiiyRVFk6yPOdGsD5s+fnyS54oorsv7667fZsFN+skVRZIuiyBZFkS2KIlsURbYoimx9xJlurdQHH3yQKVOmZI011mjZ9sYbb6ShoSEDBgyo4GRUO9miKLJFUWSLosgWRZEtiiJbFEW2Ppsz3Vqhu+++OwcccEDWWWed9O3bNw888ECSpEePHi1/ANraddSUh2xRFNmiKLJFUWSLosgWRZEtiiJbn0/p1godddRRKZVKueaaa7Leeuvl7rvvziWXXJJNNtkke+yxRx599NG0a+c/PV+ebFEU2aIoskVRZIuiyBZFkS2KIlufr32lB6C87rjjjkybNi333HNPOnTokK5du2bkyJHp27dvtt1229x+++0ZOnRo7r///qyzzjqVHpcqIlsURbYoimxRFNmiKLJFUWSLosjWF2ubVWMrdvXVV2f48OHp0KFDkmTixIlp165drrrqqpx66qn5v//3/2aNNdbI448/XuFJqTayRVFki6LIFkWRLYoiWxRFtiiKbH0xpVsr88Ybb6RPnz4tTwu57777csQRR+Qb3/hGSqVSlltuuQwePDjPPPNMhSel2sgWRZEtiiJbFEW2KIpsURTZoiiy9cU8vbSVmTlzZl577bUMHDgwpVIpjzzySAYMGJDll18+SfPNC1dfffWcffbZ2WmnnSo7LFVFtiiKbFEU2aIoskVRZIuiyBZFka0vpnRrRUqlUmpqaj53//z58/PnP/85hx56aN58882vcTKqnWxRFNmiKLJFUWSLosgWRZEtiiJb/5rLS1uRT4a9sbFxodfPPPNMrrzyyuy///5f51i0ArJFUWSLosgWRZEtiiJbFEW2KIps/WvOdGsl5syZkwkTJuT666/PBhtskAMOOCDt2rVbqHmeOnVqXnvttayxxhpZYYUVKjwx1UK2KIpsURTZoiiyRVFki6LIFkWRrUWjdGsljjzyyNx0003p1atXXnzxxQwePDh//OMfs+KKK1Z6NKqcbFEU2aIoskVRZIuiyBZFkS2KIluLxuWlrcCzzz6bK6+8MhdeeGHGjRuXG2+8Mc8991zOPffcJB+d4vnYY49l3rx5lRyVKiNbFEW2KIpsURTZoiiyRVFki6LI1pdQouodc8wxpWHDhi207brrriutscYapXfeeadUKpVK06dPL9XU1JQmT55cgQmpVrJFUWSLosgWRZEtiiJbFEW2KIpsLTpnurUCr7zySr71rW+l9P+vFJ4/f36GDRuWbt265be//W2S5I9//GPWWGON9O3bt5KjUmVki6LIFkWRLYoiWxRFtiiKbFEU2Vp0Srcq9+GHH2bzzTfP9OnTW25W2L59+7Rv3z777bdfLr300sydOzdjxozJgQceWOFpqSayRVFki6LIFkWRLYoiWxRFtiiKbH05HqTQCsyZMyezZs1K9+7dM3/+/LRv3z5JMnfu3Gy44Yb57ne/mwsvvDDvvvtuOnbsWOFpqSayRVFki6LIFkWRLYoiWxRFtiiKbC269pUegK9u2WWXzbLLLpskC4W9rq4uhx12WA455JBsu+22bT7sfHmyRVFki6LIFkWRLYoiWxRFtiiKbC06pVuVe+aZZ/Lss8+moaEhyy67bDbZZJP0798/dXV1SZKRI0fmjjvuyH/8x39UeFKqjWxRFNmiKLJFUWSLosgWRZEtiiJbX47LS6vYf//3f2fMmDF56aWX0qdPn3Tt2jWlUimDBw/Onnvume985ztp165dGhoa0qVLl0qPSxWRLYoiWxRFtiiKbFEU2aIoskVRZOvLU7pVqbfffjv9+vXLWWedlYMOOihTp07No48+mgceeCCPPfZY3n///ZxxxhkZOnRopUelysgWRZEtiiJbFEW2KIpsURTZoiiytZhKVKXf/e53pQ033PAz9z311FOlXXbZpdSpU6fSiy+++DVPRrWTLYoiWxRFtiiKbFEU2aIoskVRZGvxtKt06cfi6dq1a956663ce++9SZLGxsY0NjYmSQYNGpQrrrgi3/zmN3PbbbdVckyqkGxRFNmiKLJFUWSLosgWRZEtiiJbi0fpVqW22267rLrqqjnnnHPy7LPPpra2NrW1tSn9/6uF6+rqUltbm7fffrvCk1JtZIuiyBZFkS2KIlsURbYoimxRFNlaTJU7yY7F1dTUVCqVSqXx48eX1lprrVJdXV1p5MiRpXHjxpUmT55cevzxx0vnnXdeafnlly+98sorlR2WqiJbFEW2KIpsURTZoiiyRVFki6LI1uLzIIVW4Morr8wll1yS++67L7W1tenZs2dqampy2GGH5fDDD6/0eFQx2aIoskVRZIuiyBZFkS2KIlsURbYWndKtCjU1NaVdu3aZM2dOll122TQ1NWXu3LlpaGjIP//5z7zzzjsZMmRIevToUelRqTKyRVFki6LIFkWRLYoiWxRFtiiKbC0+pVuVee6553LOOefkzjvvzCabbJKf/exnWW211So9Fq2AbFEU2aIoskVRZIuiyBZFkS2KIltfjdKtymy00Ubp2LFjtthii/z5z3/O9OnTM378+PTr169lzdy5c1NXV1e5IalKskVRZIuiyBZFkS2KIlsURbYoimx9NZ5eWkX+8Ic/5P3338+f/vSnnHTSSRk/fnxWWWWV/Pd//3eStDw15Jxzzkl9fX0lR6XKyBZFkS2KIlsURbYoimxRFNmiKLJVBl//sxtYXDvuuGPpuOOOK5VKpdK8efNKpVKpdNttt5UGDBhQmjRpUqlUKpXuuuuuUk1NTcVmpDrJFkWRLYoiWxRFtiiKbFEU2aIosvXVOdOtSsydOzdLLbVUll9++ZRKpSy11FKZP39+ttpqq/Tp0ycXXHBBkuTCCy/MrrvuWuFpqSayRVFki6LIFkWRLYoiWxRFtiiKbJWH0q1KLL300jnxxBOz9NJLp6amJqVSKe3bt0+SHH744bnooosyZcqUjBs3Lv/5n/9Z4WmpJrJFUWSLosgWRZEtiiJbFEW2KIpslYcHKVSpUqmUmpqaJMm8efMyfPjwTJ48OTNnzszkyZMrPB3VTLYoimxRFNmiKLJFUWSLosgWRZGtxeNMtyq1IOylUilLL710fvjDH+af//xnfvzjH1d4MqqdbFEU2aIoskVRZIuiyBZFkS2KIluLx5lurUSpVMqjjz6a1VZbLV27dq30OLQiskVRZIuiyBZFkS2KIlsURbYoimwtGqUbAAAAAJSZy0sBAAAAoMyUbgAAAABQZko3AAAAACgzpRsAAAAAlJnSDQAAAADKTOkGANCG7LvvvqmpqUlNTU2WWmqp9OjRI1tuuWUuueSSNDU1LfLvc9lll2X55ZcvblAAgCqndAMAaGO22Wab1NfXZ9KkSbnllluy+eab5/DDD8/222+f+fPnV3o8AIBWQekGANDG1NXVZeWVV07v3r2z3nrr5cQTT8yNN96YW265JZdddlmS5Oyzz86gQYPSoUOH9O3bN4ceemhmz56dJBk/fnz222+/NDQ0tJw1d8oppyRJ5s2bl2OPPTa9e/dOhw4dstFGG2X8+PGV+UYBACpI6QYAQLbYYousu+66GTt2bJKkXbt2Offcc/OPf/wjf/jDH3LnnXfm2GOPTZJsuummOeecc9K5c+fU19envr4+xxxzTJJkv/32y3333Zerr746Tz31VHbZZZdss802eeGFFyr2vQEAVEJNqVQqVXoIAAC+Hvvuu29mzJiRP//5z5/at/vuu+epp57KP//5z0/t+9Of/pRDDjkkb731VpLme7odccQRmTFjRsual156KWussUamTp2aXr16tWz/93//93z729/OGWecUfbvBwBgSdW+0gMAALBkKJVKqampSZLcddddOeOMM/LPf/4zM2fOzPz58/PBBx/kvffeS4cOHT7z/Y8//nhKpVIGDBiw0Pa5c+ema9euhc8PALAkUboBAJAkefbZZ9O/f/+8+uqr2XbbbXPwwQfn9NNPz4orrph77703BxxwQD788MPPfX9TU1Nqa2vz2GOPpba2dqF9HTt2LHp8AIAlitINAIDceeedefrpp3PkkUfm0Ucfzfz583PWWWelXbvmWwBfe+21C61feuml09jYuNC2wYMHp7GxMW+++WaGDBnytc0OALAkUroBALQxc+fOzeuvv57Gxsa88cYbufXWWzNq1Khsv/322WefffL0009n/vz5Oe+887LDDjvkvvvuywUXXLDQ79GvX7/Mnj07d9xxR9Zdd90st9xyGTBgQPbaa6/ss88+OeusszJ48OC89dZbufPOOzNo0KBsu+22FfqOAQC+fp5eCgDQxtx6663p2bNn+vXrl2222SZ33XVXzj333Nx4442pra3Nt771rZx99tn55S9/mbXXXjtjxozJqFGjFvo9Nt100xx88MHZbbfdstJKK+VXv/pVkuTSSy/NPvvsk6OPPjprrrlmdtxxxzz00EPp27dvJb5VAICK8fRSAAAAACgzZ7oBAAAAQJkp3QAAAACgzJRuAAAAAFBmSjcAAAAAKDOlGwAAAACUmdINAAAAAMpM6QYAAAAAZaZ0AwAAAIAyU7oBAAAAQJkp3QAAAACgzJRuAAAAAFBmSjcAAAAAKLP/BwkCGJcFFvBPAAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 1500x800 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Absolute average distance from 0% return; portfolio: 0.73%\n",
      "Absolute average distance from 0% return; iShares MSCI USA Min Vol Factor ETF: 1.29%\n",
      "\n",
      "% of weekly returns in portfolio closer to 0% than iShares MSCI USA Min Vol Factor ETF: 87.5%\n",
      "\n",
      "Standard deviation of portfolio returns: 0.83%\n",
      "\n",
      "Portfolio's total return: -1.26%\n",
      "Fund's total return: 2.01%\n"
     ]
    }
   ],
   "source": [
    "# Plot the data, set reference lines for portfolio expected return and 0% return\n",
    "plt.scatter(x_axis, port_returns, color = 'b', label = 'Portfolio Returns')\n",
    "plt.scatter(x_axis, fund_returns, color = 'r', label = 'Fund Returns')\n",
    "\n",
    "plt.axhline(y = port_expected_return, color = 'b', linestyle = ':', label = f'Portfolio Expected Return for period \\\"{frequency}\\\"')\n",
    "\n",
    "plt.axhline(y = np.mean(port_returns), color = 'b', linestyle = '-', label = 'Portfolio Average Return')\n",
    "plt.axhline(y = np.mean(fund_returns), color = 'r', linestyle = '-', label = 'Fund Average Return')\n",
    "\n",
    "plt.axhline(y = 0, color = 'y', linestyle = '-.', label = '0%')\n",
    "\n",
    "# Set axis and title\n",
    "plt.title(f'Returns of portfolio and fund over intervals of {frequency}')\n",
    "plt.xlabel(f'Date')\n",
    "plt.xticks(rotation = 70)\n",
    "plt.ylabel(f'Return (%)')\n",
    "plt.legend(loc = 'best')\n",
    "\n",
    "# Change size of graph\n",
    "plt.gcf().set_size_inches(15, 8)\n",
    "plt.show()\n",
    "\n",
    "#--------------------------------------------------------------------------------------------------------------------------------------------#\n",
    "\n",
    "# Grab average distance of data points from 0%\n",
    "returns_abs = [abs(x) for x in port_returns]\n",
    "fund_returns_abs = [abs(x) for x in fund_returns]\n",
    "returns_adf0 = np.round(np.mean(returns_abs), 2)\n",
    "fund_returns_adf0 = np.round(np.mean(fund_returns_abs), 2)\n",
    "\n",
    "# Calculate amount of times our portfolio is closer to 0% return than the fund\n",
    "closer = 0\n",
    "\n",
    "for i in range(len(returns_abs)):\n",
    "    if returns_abs[i] < fund_returns_abs[i]:\n",
    "        closer += 1\n",
    "\n",
    "closer = np.round(closer / len(returns_abs) * 100, 2)\n",
    "\n",
    "# Conclusion\n",
    "print(f\"Absolute average distance from 0% return; portfolio: {returns_adf0}%\")\n",
    "print(f\"Absolute average distance from 0% return; {fund_name}: {fund_returns_adf0}%\")\n",
    "\n",
    "print(f\"\\n% of weekly returns in portfolio closer to 0% than {fund_name}: {closer}%\")\n",
    "\n",
    "print(f\"\\nStandard deviation of portfolio returns: {np.round(np.std(port_returns), 2)}%\")\n",
    "\n",
    "print(f\"\\nPortfolio's total return: {np.round(portfolio_total_return, 2)}%\")\n",
    "print(f\"Fund's total return: {np.round(fund_total_return, 2)}%\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. PORTFOLIO TO CSV, CONSIDERATIONS, AND CONCLUSION"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 5.1 Output Final Information to .csv File"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 283,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Final DataFrame, output to csv\n",
    "stocks_final = portfolio_final[['Ticker', 'Shares']]\n",
    "stocks_final.to_csv(\"csv/final_portfolio.csv\", encoding='utf-8')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 5.2 Considerations\n",
    "\n",
    "Stock selection - It's hard to make something out of nothing. For this program to run well, the stocks must be selected with low volatility and offsetting correlation in mind. Low volatility is especially important.\n",
    "\n",
    "Beta - Low beta DOES NOT equal low volatility in all cases. This was one of the reasons we used the points system as part of the consideration when selecting the final portfolio weights. Sometimes, beta can sway the simulation to more heavily favour correlation as a factor, since lower correlation = lower beta.\n",
    "\n",
    "Analysis period - It was found that a mid-sized portfolio selection analysis period relative to the investment horizon was generally more successful for creating a performant portfolio than a shorter or longer analysis period. We can never really be certain which length of period (or which timeframe) is the best though."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 5.3 Conclusion\n",
    "\n",
    "Our goal was to consume a list of stock tickers, and generate a portfolio that will yield a return as close to 0% as possible. \n",
    "\n",
    "We first cleaned up our data to ensure each ticker met certain criteria. Then, we chose the best stocks to use, considering volatility and correlation. We generated five-hundred thousand hypothetical portfolios, and used a Multi-Security Capital Asset # Model to obtain the portfolio whose expected return was the closest to zero. Finally, we performed some data analysis, and explained why the portfolio that our code generated is optimal for achieving our goal.\n",
    "\n",
    "The portfolio delivered a low absolute average return, with less volatility in the short term, and low momentum in the long term, when compared to the fund. For the given time period, we conclude that we outperformed the fund.\n",
    "\n",
    "We conclude that our method of creating a portfolio which will yield near-zero returns is efficient, accurate, and performant."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. REFERENCES\n",
    "- Various Code and Concepts: Notes of Professor James Thompson\n",
    "- Capital Asset # Model: https://www.investopedia.com/terms/c/capm.asp#toc-the-capm-and-the-efficient-frontier\n",
    "- Robot Image: http://www.onlinewebfonts.com\n",
    "- USMV Information: https://www.ishares.com/us/products/239695/ishares-msci-usa-minimum-volatility-etf and https://etfdb.com/advisor_reports/USMV/\n",
    "- iShares and BlackRock information: https://www.blackrock.com/il/intermediaries/en/themes/ishares-etf\n",
    "- \\#Combining scores and sorting: https://stackoverflow.com/questions/74891387/combining-elements-of-two-lists-based-on-the-indexes-of-two-separate-lists-in-py\n",
    "- @Weight Generation: https://stackoverflow.com/questions/74527506/creating-a-list-of-n-numbers-between-x-and-y-who-sum-up-to-z"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.4"
  },
  "vscode": {
   "interpreter": {
    "hash": "a1c3729c138d461e47acb27942119b3e6dc1eee1d6b566d1cf82ebc5db795064"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}