Skip to content

Latest commit

 

History

History
141 lines (98 loc) · 8.92 KB

README.md

File metadata and controls

141 lines (98 loc) · 8.92 KB
Raw

Python Portfolio Tracker (ppt)

License: MIT Build Status codecov Code Style: Black

Track the performance of your portfolio using Python!

Currently under construction... 🚧🏗️

Progress:

  • Data loading

    • Load positions from input csv containing BUY/SELL actions
    • Load stock prices for positions in input csv
    • Add support for 🇺🇸, 🇬🇧, 🇪🇺 and 🇯🇵 stocks
    • Convert foriegn stocks to USD to calculate total portfolio value in USD
    • Load dividend payments for each stock
    • Robust data input validation

  • Portfolio Analysis

    • Calculate time-weighted portfolio performance
    • Calculate total return for each holding
    • Calculate overall portfolio performance metrics
    • Calculate individual stock performance metrics

Key Features

  • simple input format: list of buy and sell positions in csv format
  • automatically calculate the daily value of your portfolio, your stock positions and cash balance from the input list of buy/sell actions
  • adjust for regular cash injections (e.g. monthly contributions to the portfolio)
  • compatible for US, EU, JP and GB listed stocks
  • quickly conduct an in-depth analysis of your overall portfolio performance or individual stocks using inbuilt functions (e.g. mean-variance, correlations, max drawdown, position weightings, profit contributions etc.) or use the base raw data for your own further analysis

Problems this library aims to solves

Online brokerage accounts only provide high level 'one-size-fits-all' metrics on your portfolio performance and (generally) do not give you access to the underlying raw data.

This makes it difficult to run custom analyses on your positions and understand the true performance of the portfolio, your overall stock/cash positions and any potential risks (correlations) between individual stock positions. This is especially a problem if you have multiple brokeage accounts.

Furthermore, most other Python libraries do not account for regular cash injections (e.g. monthly contributions to the portfolio). This makes it hard to evaluate the true performance of your portfolio.

Using a simple list of buy/sell positions in a csv file as input, this repo aims to allow the user to efficiently collect daily stock price data, calculate the value of their portfolio over time and use the raw data to complete custom in depth analysis of positions (e.g mean-variance, correlations, etc.).

QuickStart

  1. Fork this repo, clone to local computer and create a virtual environment

    # could alternatively use virtualenv
conda create --name python-portfolio-tracker --file requirements.txt

  2. Upload your input data containing the list of buy/sell actions in your portfolio (using the correct format specified in the Data Input Format below). The default location for the input data is: data/raw/purchase_info.csv, however, you can upload it anywhere and just reference the location (input_data_source) in the load data functions.

  3. Load stock price data and calculate daily running portfolio and stock position values

    from ppt.portfolio_value import Portfolio

# load portfolio data from input csv located in 'data/raw/purchase_info.csv
pf = Portfolio()

# get daily portfolio value
pf.portfolio_value_usd

  4. Use the raw stock price and portfolio value data contained in the Portfolio object to analyse your stock portfolio (in built library functions to analyse the portfolio are to come in the future...)

Data Input Format

The required data input for this analysis is a csv file containing rows for each purchase (or disposal) of a stock in your portfolio. An example is given in the ../data/raw/purchase_info.csv in this repository.

The required columns are:

  • date: the date of your transaction
  • action: BUY or SELL
  • company: the name of the company (this is not sensitive to any further analysis and can be anything of your choosing)
  • yahoo_ticker: the ticker of the stock on finance.yahoo.com (note this might be different from the actual stock market ticker)
  • currency: the currency the stock price is denominated in
  • num_shares: the number of shares involved in the transaction
  • stock_price_usd: the stock price you bought the stock at on that day
  • trading_costs_usd: the trading costs incurred
  • total_usd: the total cost of the transaction
  • total_shares_held: the total number of shares held after the transaction

Key Input Requirements

  • cash inflows and outflows (new cash injected into the portfolio and cash removed from the portfolio) should be recorded using CASH IN and CASH OUT labels in the action column
  • the first entry of the input csv should be a CASH IN action which denotes the starting cash balance (before any stocks were bought)

Example input format:

date action company yahoo_ticker currency num_shares stock_price_usd trading_costs_usd total_usd total_shares_held
0 17/07/2019 CASH IN cash cash USD 0 100000 0 100000 0
1 17/07/2019 BUY Intel INTC USD 180 49.91 4.95 8988.75 180
2 17/07/2019 BUY Applied Materials AMAT USD 268 45.9151 4.95 12310.2 268
3 17/07/2019 BUY MKS Instruments MKSI USD 120 76.7449 4.95 9214.34 120
4 17/07/2019 BUY Synopsys SNPS USD 68 136.808 4.95 9307.92 68
5 17/07/2019 BUY SOXX ETF SOXX USD 75 204.261 4.95 15324.5 75
6 18/07/2019 BUY Nvidia NVDA USD 39 166.67 4.95 6505.08 39
7 24/07/2019 BUY Tokyo Electron 8035.T JPY 100 168.413 126.31 16967.7 100
8 24/07/2019 BUY BE Semiconductor Industries BESI.AS EUR 420 29.9253 100 12668.6 420
9 26/11/2019 SELL Nvidia NVDA USD 5 217 4.95 1089.95 34
10 25/12/2019 CASH IN cash cash USD 0 10000 0 10000 0
11 25/03/2020 BUY Nvidia NVDA USD 10 205.75 4.95 2062.45 44
12 25/05/2020 CASH OUT cash cash USD 0 5000 0 5000 0

Current limitations

  • Only available for stocks which have stock price information available on yahoo finance
  • Data processing and analysis is completed in memory which may not scale we to portfolios with many different positions
  • Stock price data is loaded from yahooFinance (using the ffn library), the veracity of this data source may not be 100%
  • The library currently does not track dividend payments

Further work

  • release as a PyPI library
  • User input through webapp rather than csv/Jupyter Notebooks
  • Account for dividend payments

Running Tests

PyTest is used for running tests in this project. If running on Linux or Mac and you have Make installed you can run tests using the make test command from the Makefile.

Alternatively, tests can be run using pytest directly using the following command from the home working directory:

pytest --cov-config=.coveragerc --cov=ppt