Quick Start

Let’s create a returns heatmap for SPY (S&P 500 Spider ETF).

First, let’s download SPY’s daily close prices from Google finance.

from pandas_datareader import data
prices = data.get_data_google("SPY")['Close']
returns = prices.pct_change()

Next, we’ll import monthly_returns_heatmap and plot the monthly return heatmap:

import monthly_returns_heatmap as mrh

returns.plot_monthly_returns_heatmap()
# mrh.plot(returns) # <== or using direct call

Getting heatmap data only (no plotting)

heatmap = prices.get_monthly_returns_heatmap()
# heatmap = mrh.get(returns) # <== or using direct call

print(heatmap)

# prints:

Month       Jan        Feb        Mar        Apr  ...        Dec
Year
2010   0.000000   0.031195   0.056529   0.015470  ...   0.061271
2011   0.023300   0.034737  -0.004807   0.030413  ...   0.003117
2012   0.045498   0.043137   0.028129  -0.006751  ...   0.001759
2013   0.051190   0.012759   0.033375   0.019212  ...   0.020387
2014  -0.035248   0.045516   0.003865   0.006951  ...  -0.008012
2015  -0.029629   0.056205  -0.020080   0.009834  ...  -0.023096
2016  -0.049787  -0.001910   0.062943   0.003941  ...   0.014293
2017   0.017895   0.039292  -0.003087   0.009926  ...   0.000000

Get Parameters (optional)

• is_prices - set to True if the data used is price data instead of returns data

• compounded - set to False if the you don’t want the calculation to use compounded returns

• eoy - set to True to add a End Of Year column with total yearly returns

Plot Parameters (optional)

• title - Heatmap title (defaults to "Monthly Returns (%)")

• title_color - Heatmap title color (defaults to "black")

• title_size - Heatmap title font size (defaults to 12)

• annot_size - Returns boxes font size (defaults to 10)

• figsize - Heatmap figure size (defaults to None)

• cmap - Color map (defaults to "RdYlGn")

• cbar - Show color bar? (defaults to True)

• square - Force squere returns boxes? (defaults to False)

• is_prices - set to True if the data used is price data instead of returns data

• compounded - set to False if the you don’t want the calculation to use compounded returns

• eoy - set to True to add a End Of Year column with total yearly returns

Installation

Install monthly_returns_heatmap using pip:

$ pip install monthly_returns_heatmap --upgrade --no-cache-dir

Requirements

• Python >=3.4

• Pandas (tested to work with >=0.18.1)

• Matplotlib (tested to work with >=1.5.3)

• Seaborn (tested to work with >=0.7)

Legal Stuff

monthly-returns-heatmap is distributed under the GNU Lesser General Public License v3.0. See the LICENSE.txt file in the release for details.

P.S.

Please drop me an note with any feedback you have.

Ran Aroussi