Visualize Wealth DocumentationRelease 0.0.1

Benjamin M. Gross

May 20, 2015

Contents

1 Modules Explained 31.1 Constructing portfolios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Analyzing portfolio performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 construct_portfolio.py documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 classify.py documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.5 analyze.py documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.6 utils.py documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.7 Sphinx Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 README.md 72.1 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.4 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.5 Portfolio Construction Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.6 ToDo List: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3 asset_class 153.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.2 Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.3 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173.4 Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173.5 To Do: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4 visualize_wealth package 194.1 Submodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.2 visualize_wealth.analyze module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.3 visualize_wealth.classify module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.4 visualize_wealth.construct_portfolio module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.5 visualize_wealth.utils module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.6 Module contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5 Indices and tables 21

i

ii

Visualize Wealth Documentation, Release 0.0.1

If you’re anything like me, you sit at home waiting with baited breath... nervously wringing your hands... waiting foryour brokerage account statement arrive. Pure adrenaline comes over you when those comprehensive illustrations of“how your portfolio has performed” over the past month, year, several years... and what exactly you’ve done well,and how to continue improving as someone who “manages your own wealth” are finally in your hot little hands.Clearly I jest, but if you want to really dig into portfolio management, there aren’t a lot of tools out there that helpyou understand academic concepts (like Sharpe Ratios, Risk Adjusted Excess Returns, etc.) within the context of yourportfolio.

So I’ve put together a fairly comprehensive “construction engine” for Constructing portfolios that can create portfoliosfor you in three different ways (more on that later). Then, I’ve also put together a module that has all of the back-end calculations for Analyzing portfolio performance. With those two basic tools, you should be able to begin theprocess of constructing more comprehensive analytical tools... that’s what I’m doing, anyway. This Git Repository isthe backend for a visualization engine that I’m creating to aid investors and financial advisors better understand theimpact of choices they make.

But enough about me... enjoy, and please feel free to email me at benjaminMgross [at] gmail [dot] com.

Contents:

Contents 1

Visualize Wealth Documentation, Release 0.0.1

2 Contents

CHAPTER 1

Modules Explained

Optimization of Functions:

In all cases, functions have been optimized to ensure the most expeditious calculation times possible, so most of thelag time the user experiences will be due to the Yahoo! API Calls.

Examples:

Fairly comprehensive examples can be found in the README section of this documentation, which also resides on theSplash Page of this project’s GitHub Repository.

Testing:

The folder under visualize_wealth/tests/ has fairly significant tests that illustrate the calculations of:

1. Portoflio construction methods

2. The portfolio statistic calculations use in the analyze module

All the files are Microsoft Excel files (extensions .xslx), so seeing cell calculations and the steps to arrive at a finalvalue should be pretty straightforward.

1.1 Constructing portfolios

In general I’ve provided for three ways to construct a portfolio using this package:

1. The Blotter Method: Provide trades given tickers, buy / sell dates, and prices. In general, this method mostclosely approximates how you would reconstruct your own portfolio performance (if you had to). Youwould essentially take trade confirmations of buys and sells, calcluate dividends and splits, and then arriveat an aggregate portfolio path. Specific examples can be found under blotter method examples.

2. The Weight Allocation Method: Provide a weighting scheme with dates along the first column with columntitles as tickers and percentage allocations to each ticker for a given date for values. Specific examples canbe found under weight allocation examples.

3. The Initial Allocation Method: with specific Rebalancing Periods provide an initial allocation scheme rep-resenting the static weights to rebalance to at some given interval, and then define the rebalancing intervalas ‘weekly’, ‘monthly’, ‘quarterly’, and ‘yearly.’ Specific examples can found under initial allocationexamples.

Much more detailed examples of these three methods, as well as specific examples of code that would leverage thispackage can be found in the Portfolio Construction Examples.

In the cases where prices are not available to the investor, helper functions for all of the construction methods areavailable that use Yahoo!’s API to pull down relevant price series to be incorporated into the portfolio series calculation.

3

Visualize Wealth Documentation, Release 0.0.1

1.2 Analyzing portfolio performance

In general, there’s a myriad of statistics and analysis that can be done to analyze portfolio performance. I don’t goreally deeply into the uses of any of these statistics, but any number of them can be “Google-ed”, if there aren’t livelinks already provided.

Fairly extensive formulas are provided for each of the performance statistics inside of the analyze. Formulas wereinserted using the MathJax rendering capability that Sphinx provides.

1.3 construct_portfolio.py documentation

Full documentation for each of the functions of visualize_wealth.construct_portfolio

1.4 classify.py documentation

Full documentation for each of the functions of visualize_wealth.classify

1.5 analyze.py documentation

Full documentation for each of the functions of visualize_wealth.analyze

1.6 utils.py documentation

Full documentation for each of the functions of visualize_wealth.utils

1.7 Sphinx Customizations

The documentation for this module was created using Sphinx. I keep a couple of commands here that I use when re-committing to GitHub, or regenerating the documentation. It serves as reference for myself, but in case other peoplemight find it useful I’ve posted that as well

1.7.1 Convert README.md to .rst format

I use Pandoc to convert my README (that’s in Markdown format) into .rst format (that can be interepreted bySphinx).

$ cd visualize_wealth$ pandoc README.md -f markdown -t rst -o docs/source/readme.rst

1.7.2 Build Sphinx Documentation

4 Chapter 1. Modules Explained

Visualize Wealth Documentation, Release 0.0.1

#rebuild the package$ cd visualize_wealth$ python setup.py install

#rebuild the documentation$ sphinx-build -b html docs/source/ docs/build/

1.7.3 Sphinx Customizations in conf.py

Current customizations I use in order to make the docs look like they currently do

#use the sphinxdoc themehtml_theme = 'sphinxdoc'

#enable todostodo_include_todos = Trueextensions = ['sphinx.ext.autodoc',..., 'sphinx.ext.todo']

1.7. Sphinx Customizations 5

Visualize Wealth Documentation, Release 0.0.1

6 Chapter 1. Modules Explained

CHAPTER 2

README.md

A library built in Python to construct, backtest, analyze, and evaluate portfolios and their benchmarks, with compre-hensive documentation and manual calculations to illustrate all underlying methodologies and statistics.

2.1 License

This program is free software and is distrubuted under the GNU General Public License version 3 (“GNU GPL v3”)

© Benjamin M. Gross 2013

2.2 Dependencies

pandas: extensively used (numpy and scipy obviously, but pandas depends on those)

urllib2: for Yahoo! API calls to append price DataFrames with Dividends

2.3 Installation

To install the visualize_wealth modules onto your computer, go into your desired folder of choice (sayDownloads), and:

1. Clone the repository

$ cd ~/Downloads$ git clone https://github.com/benjaminmgross/grind-my-ass-ets

2. cd into the grind-my-ass-ets directory

$ cd grind-my-ass-ets

3. Install the package

$python setup.py install

4. Check your install. From anywhere on your machine, be able to open iPython and import the library, forexample:

7

Visualize Wealth Documentation, Release 0.0.1

$ cd ~/$ ipython

IPython 1.1.0 -- An enhanced Interactive Python.? -> Introduction and overview of IPython's features.%quickref -> Quick reference.help -> Python's own help system.object? -> Details about 'object', use 'object??' for extra details.

In [1]: import visualize_wealth

“Ligget Se!”

2.4 Documentation

The README.md file has fairly good examples, but I’ve gone to great lengths to autogenerate documentation for thecode using Sphinx. Therefore, aside from the docstrings, when you git clone the repository, you can cd into:

$ cd visualize_wealth/docs/build/

and find full .html browseable code documentation (that’s pretty f*cking beautiful... if I do say so my damn self)with live links, function explanations (that also have live links to their respective definition on the web), etc.

Also I’ve created an Excel spreadsheet that illustrates almost all of the analyze.py portfolio statistic calculations.That spreadsheet can found in:

visualize_wealth > tests > test_analyze.xlsx

In fact, the unit testing for the analyze.py portfolio statistics tests the python calculations against this same excelspreadsheet, so you can really get into the guts of how these things are calculated.

2.5 Portfolio Construction Examples

Portfolios can (generally) be constructed in one of three ways:

1. The Blotter Method

2. Weight Allocation Method

3. Initial Allocation with specific Rebalancing Period Method

2.5.1 1. The Blotter Method

The blotter method: In finance, a spreadsheet of “buys/sells”, “Prices”, “Dates” etc. is called a “trade blotter.” Thisalso would be the easiest way for an investor to actually analyze the past performance of her portfolio, because tradeconfirmations provide this exact data.

This method is most effectively achieved by providing an Excel / .csv file with the following format:

Date Buy / Sell Price Ticker9/4/2001 50 123.45 EFA5/5/2003 65 107.71 EEM6/6/2003 -15 118.85 EEM

where “Buys” can be distinguished from “Sells” because buys are positive (+) and sells are negative (-).

8 Chapter 2. README.md

Visualize Wealth Documentation, Release 0.0.1

For example, let’s say I wanted to generate a random portfolio containing the following tickers and respective assetclasses, using the generate_random_portfolio_blotter method

Ticker Description Asset Class Price StartIWB iShares Russell 1000 US Equity 5/19/2000IWR iShares Russell Midcap US Equity 8/27/2001IWM iShares Russell 2000 US Equity 5/26/2000EFA iShares EAFE Foreign Dev Equity 8/27/2001EEM iShares EAFE EM Foreign EM Equity 4/15/2003TIP iShares TIPS Fixed Income 12/5/2003TLT iShares LT Treasuries Fixed Income 7/31/2002IEF iShares MT Treasuries Fixed Income 7/31/2002SHY iShares ST Treasuries Fixed Income 7/31/2002LQD iShares Inv Grade Fixed Income 7/31/2002IYR iShares Real Estate Alternative 6/19/2000GLD iShares Gold Index Alternative 11/18/2004GSG iShares Commodities Alternative 7/21/2006

I could construct a portfolio of random trades (i.e. the “blotter method”), say 20 trades for each asset, by executing thefollowing:

#import the modulesIn [5]: import vizualize_wealth.construct_portfolio as vwcp

In [6]: ticks = ['IWB','IWR','IWM','EFA','EEM','TIP','TLT','IEF','SHY','LQD','IYR','GLD','GSG']

In [7]: num_trades = 20

#construct the random trade blotterIn [8]: blotter = vwcp.generate_random_portfolio_blotter(ticks, num_trades)

#construct the portfolio panelIn [9]: port_panel = vwcp.panel_from_blotter(blotter)

Now I have a pandas.Panel. Before we constuct the cumulative portfolio values, let’s examine the dimensions ofthe panel (which are generally the same for all construction methods, although the columns of the minor_axis aredifferent because the methods call for different optimized calculations) with the following dimensions:

#tickers are `panel.items`In [10]: port_panel.itemsOut[10]: Index([u'EEM', u'EFA', u'GLD', u'GSG', u'IEF', u'IWB', u'IWM', u'IWR',

u'IYR', u'LQD', u'SHY', u'TIP', u'TLT'], dtype=object)

#dates are along the `panel.major_axis`In [12]: port_panel.major_axisOut[12]:<class 'pandas.tseries.index.DatetimeIndex'>[2000-07-06 00:00:00, ..., 2013-10-30 00:00:00]Length: 3351, Freq: None, Timezone: None

#price data, cumulative investment, dividends, and split ratios are `panel.minor_axis`In [13]: port_panel.minor_axisOut[13]: Index([u'Open', u'High', u'Low', u'Close', u'Volume', u'Adj Close',

u'Dividends',u'Splits', u'contr_withdrawal', u'cum_investment',u'cum_shares'], dtype=object)

There is a lot of information to be gleaned from this data object, but the most common goal would be to convertthis pandas.Panel to a Portfolio pandas.DataFrame with columns [’Open’, ’Close’], so it can be

2.5. Portfolio Construction Examples 9

Visualize Wealth Documentation, Release 0.0.1

compared against other assets or combination of assets. In this case, use pfp_from_blotter(which stands for“portfolio_from_panel” + portfolio construction method [i.e. blotter, weights, or initial allocaiton] which in this casewas “the blotter method”).

#construct_the portfolio seriesIn [14]: port_df = vwcp.pfp_from_blotter(panel, 1000.)

In [117]: port_df.head()Out[117]:

Close OpenDate2000-07-06 1000.000000 988.7447542000-07-07 1006.295307 1000.1907672000-07-10 1012.876765 1005.7230062000-07-11 1011.636780 1011.0644792000-07-12 1031.953453 1016.978253

2.5.2 2. The Weight Allocation Method

A commonplace way to test portoflio management strategies using a group of underlying assets is to construct aggre-gate portofolio performance, given a specified weighting allocation to specific assets on specified dates. Specifically,those (often times) percentage allocations represent a recommended allocation at some point in time, based on some“view” derived from either the output of a model or some qualitative analysis. Therefore, having an engine that iscapable of taking in a weighting file (say, a .csv) with the following format:

Date Ticker 1 Ticker 2 Ticker 3 Ticker 41/1/2002 5% 20% 30% 45%6/3/2003 40% 10% 40% 10%7/8/2003 25% 25% 25% 25%

and turning the above allocation file into a cumulative portfolio value that can then be analyzed and compared (bothin isolation and relative to specified benchmarks) is highly valuable in the process of portfolio strategy creation.

A quick example of a weighting allocation file can be found in the Excel File visualize_wealth/tests/panelfrom weight file test.xlsx, where the tab rebal_weights represents one of these specific weightingfiles.

To construct a portfolio of using the Weighting Allocation Method, a process such as the following would be carriedout.

#import the libraryimport visualize_wealth.construct_portfolio as vwcp

If we didn’t have the prices already, there’s a function for that

#fetch the prices and put them into a pandas.Panelprice_panel = vwcp.fetch_data_for_weight_allocation_method(weight_df)

#construct the panel that will go into the portfolio constructor

port_panel = vwcp.panel_from_weight_file(weight_df, price_panel,start_value = 1000.)

Construct the pandas.DataFrame for the portfolio, starting at start_value of 1000 with columns [’Open’,Close’]

portfolio = vwcp.pfp_from_weight_file(port_panel)

10 Chapter 2. README.md

Visualize Wealth Documentation, Release 0.0.1

Now a portfolio with index of daily values and columns [’Open’, ’Close’] has been created upon whichanalytics and performance analysis can be done.

2.5.3 3. The Initial Allocation & Rebalancing Method

The standard method of portoflio construction that pervades in many circles to this day is static allocation with agiven interval of rebalancing. For instance, if I wanted to implement Oppenheimers’ The New 60/40 static portfolio,rebalancing on a yearly interval, my weighting scheme would be as follows:

Ticker Name Asset Class AllocationIWB iShares Russell 1000 US Equity 15%IWR iShares Russell Midcap US Equity 7.5%IWM iShares Russell 2000 US Equity 7.5%SCZ iShares EAFE Small Cap Foreign Dev Equity 7.5%EFA iShares EAFE Foreign Dev Equity 12.5%EEM iShares EAFE EM Foreign EM Equity 10%TIP iShares TIPS Fixed Income 5%TLT iShares LT Treasuries Fixed Income 2.5%IEF iShares MT Treasuries Fixed Income 2.5%SHY iShares ST Treasuries Fixed Income 5%HYG iShares High Yield Fixed Income 2.5%LQD iShares Inv Grade Fixed Income 2.5%PCY PowerShares EM Sovereign Fixed Income 2%BWX SPDR intl Treasuries Fixed Income 2%MBB iShares MBS Fixed Income 1%PFF iShares Preferred Equity Alternative 2.5%IYR iShares Real Estate Alternative 5%GLD iShares Gold Index Alternative 2.5%GSG iShares Commodities Alternative 5%

To implement such a weighting scheme, we can use the same worksheet visualize_wealth/tests/panelfrom weight file test.xlsx, and the tab. static_allocation. Note there is only a single row ofweights, as this will be the “static allocation” to be rebalanced to at some given interval.

#import the construct_portfolio libraryimport visualize_wealth.construct_portfolio as vwcp

Let’s use the static_allocation provided in the panel from weight file.xlsx workbook

f = pandas.ExcelFile('tests/panel from weight file test.xlsx')static_alloc = f.parse('static_allocation', index_col = 0,

header_col = 0)

Again, assume we don’t have the prices and need to donwload them, use thefetch_data_for_initial_allocation_method

price-panel = vwcp.fetch_data_for_initial_allocation_method(static_alloc)

Construct the panel for the portoflio while determining the desired rebalance frequency

panel = vwcp.panel_from_initial_weights(weight_series = static_alloc,static_alloc, price_panel = price_panel, rebal_frequency = 'quarterly')

Construct the final portfolio with columns [’Open’, ’Close’]

2.5. Portfolio Construction Examples 11

Visualize Wealth Documentation, Release 0.0.1

portfolio = vwcp.pfp_from_weight_file(panel)

Take a look at the portfolio series:

In [10:] portfolio.head()Out[11:]

Close OpenDate2007-12-12 1000.000000 1007.8859322007-12-13 991.329125 990.7179152007-12-14 978.157960 983.0578292007-12-17 961.705069 969.7971672007-12-18 969.794966 972.365687

2.6 ToDo List:

• occassionally generate_random_asset_path will return with an Assertion Error

• Add the following statistics to the analyze.py library:

• [STRIKEOUT:Absolute Alpha:

𝑅𝑝 −𝑅𝑏

]

• Treynor ratio:

𝑡𝑒𝑥𝑡𝑟𝑚𝑇.𝑅.

𝑡𝑟𝑖𝑎𝑛𝑔𝑙𝑒𝑞

𝑓𝑟𝑎𝑐𝑟𝑖 − 𝑟𝑓

𝑏𝑒𝑡𝑎𝑖

• Information Ratio or Appraisal Ratio:

𝑡𝑒𝑥𝑡𝑟𝑚𝐼.𝑅.

𝑡𝑟𝑖𝑎𝑛𝑔𝑙𝑒𝑞

𝑓𝑟𝑎𝑐

𝑎𝑙𝑝ℎ𝑎

𝑜𝑚𝑒𝑔𝑎

, or absolute alpha / tracking error. Other formulations include Jensens’s Alpha / Idiosyncratic Vol

• Up / Down beta (or Dual-Beta)

• Best broad asset classes to determine “best fit portfolio”

Ticker Name Price Data BeginsVTSMX Vanguard Total Stock Market 6/20/1996VBMFX Vanguard Total Bond Market 6/4/1990VGTSX Vanguard Total Intl Stock 6/28/1996

• Rebuild Process:

12 Chapter 2. README.md

Visualize Wealth Documentation, Release 0.0.1

1. If the README.md file is altered, run:

$ pandoc -f markdown -t rst README.md -o docs/source/readme.rst

2. Then rebuild the Sphinx documentation

$ sphinx-build -b html docs/source/ docs/build/

2.6. ToDo List: 13

Visualize Wealth Documentation, Release 0.0.1

14 Chapter 2. README.md

CHAPTER 3

asset_class

A simple library that uses r-squared maximization techniques and asset sub class ETFs (that I personally chose) todetermine asset class information, as well as historical asset subclass information for a given asset

3.1 Installation

$git clone https://github.com/benjaminmgross/asset_class$ cd asset_class$python setup.py install

3.2 Quickstart

Let’s say we had some fund, for instance the Franklin Templeton Growth Allocation Fund A – ticker FGTIX – againstwhich we we wanted to do historical attribution.

In just a couple of key strokes, we can come up with quarterly attribution analysis to see where returns were comingfrom

import pandas.io.data as webimport asset_class

fgtix = web.DataReader('FGTIX', 'yahoo', start = '01/01/2000')['Adj Close']rolling_weights = asset_class.asset_class_and_subclass_by_interval(fgtix, 'quarterly')

And that’s it. Let’s see the subclass attributions that the adjusted r-squared optimization algorithm came up with.

import matplotlib.pyplot as plt

#create the stacked area graphfig = plt.figure()ax = plt.subplot2grid((1,1), (0,0))stack_coll = ax.stackplot(rolling_attr.index, rolling_attr.values.transpose())ax.set_ylim(0, 1.)proxy_rects = [plt.Rectangle( (0,0), 1, 1,

fc = pc.get_facecolor()[0]) for pc in stack_coll]ax.legend(proxy_rects, rolling_attr.columns.values.tolist(), ncol = 3,

loc = 8, bbox_to_anchor = (0.5, -0.15))plt.title("Asset Subclass Attribution Over Time", fontsize = 16)plt.show()

15

Visualize Wealth Documentation, Release 0.0.1

Fig. 3.1: sub_classes

16 Chapter 3. asset_class

Visualize Wealth Documentation, Release 0.0.1

3.3 Dependencies

3.3.1 Obvious Ones:

pandas numpy scipy.optimize (uses the TNC method to optimize the objective function of r-squared)

3.3.2 Not So Obvious:

Another one of my open source repositories ‘visualize_wealth <https://github.com/benjaminmgross/wealth-viz>‘__ > But that’s just for adjusted r-squared functionality, you could easily clone and hack it yourself without thatlibrary

3.4 Status

Still very much a WIP, although I’ve added [Sphinx]http://sphinx-doc.org/) docstrings to auto generate documentation

3.5 To Do:

• Given a pandas.DataFrame of asset prices, and asset price weights, return an aggregated asset classpandas.DataFrame on a quarterly basis

• Write the Best Fitting Benchmark algorithm, either for use in this library or from the privatestrat_check repository that uses this module

3.3. Dependencies 17

Visualize Wealth Documentation, Release 0.0.1

18 Chapter 3. asset_class

CHAPTER 4

visualize_wealth package

4.1 Submodules

4.2 visualize_wealth.analyze module

4.3 visualize_wealth.classify module

4.4 visualize_wealth.construct_portfolio module

4.5 visualize_wealth.utils module

4.6 Module contents

19

Visualize Wealth Documentation, Release 0.0.1

20 Chapter 4. visualize_wealth package

CHAPTER 5

Indices and tables

• genindex

• modindex

• search

21