Updated README for latest API and tearsheet.

Author: mhallsmoore

README.md

@@ -3,9 +3,9 @@
 
 # QSTrader  
 
-QSTrader is an open-source event-driven backtesting and live trading platform for use in the equities markets, currently in an early "alpha" state.
+QSTrader is an open-source event-driven backtesting platform for use in the equities markets, currently in an alpha state.
 
-It has been created as part of the Advanced Trading Infrastructure article series on QuantStart.com to provide the systematic trading community with a robust trading engine that allows straightforward equities/ETF strategy implementation and testing.
+It has been created as part of the Advanced Trading Infrastructure article series on QuantStart.com to provide the systematic trading community with a robust trading engine that allows straightforward equities strategy implementation and testing.
 
 The software is provided under a permissive "MIT" license (see below).
 
@@ -19,40 +19,40 @@ The software is provided under a permissive "MIT" license (see below).
 
 * **Software Development** - QSTrader is written in the Python programming language for straightforward cross-platform support. QSTrader contains a suite of unit tests for the majority of its calculation code and tests are constantly added for new features.
 
-* **Event-Driven Architecture** - QSTrader is completely event-driven both for backtesting and live trading, which leads to straightforward transitioning of strategies from a research/testing phase to a live trading implementation.
+* **Event-Driven Architecture** - QSTrader is completely event-driven, which leads to straightforward transitioning of strategies from a research phase to a live trading implementation.
 
 * **Backtesting** - QSTrader supports both intraday tick-resolution (top of order book bid/ask) datasets as well as OHLCV "bar" resolution data on various time scales.
 
 * **Private Components** - QSTrader allows you to include a repository of your own private strategies or components. Simply checkout your own repository within the root of QSTrader and rename the directory to `private_files`. This will ensure the QSTrader repository can be easily kept up to date without interfering with your private repository.
 
-* **Performance Metrics** - QSTrader will supports basic strategy/portfolio performance measurement and equity curve visualisation via the Matplotlib and Seaborn visualisation libraries.
+* **Performance Metrics** - QSTrader supports both portfolio-level and trade-level performance measurement. It provides a comprehensive "tearsheet" (see below) with associated strategy statistics.
 
 # Planned Features
 
-* **Transaction Costs** - Fees/commission, slippage and market impact will all be simulated using realistic assumptions. This means the costs predicted in backtests will be similar to those encountered in live trading.
+* **Transaction Costs** - Commissions are currently supported using Interactive Brokers standard fees for North American equities. Slippage and market impact are planned, but are not currently supported.
 
-* **Trading** - QSTrader will support live intraday trading using the Interactive Brokers API across a set of equities/ETFs.
+* **Trading** - QSTrader will support live intraday trading using the Interactive Brokers native Python API, initially for North American equities.
 
 # Installation and Example Usage
 
-QSTrader is in an extremely early alpha state at the moment and should only be used for exploratory backtesting research. The installation procedure is a little more involved than a standard Python package as it has not been added to the Python package repository yet.
+QSTrader is in an early alpha state at the moment. It should only be used for exploratory backtesting research. The installation procedure is a little more involved than a standard Python package as it has not yet been added to the Python package repository.
 
-Ubuntu is the recommended platform on which to install QSTrader, but it will also work on Windows or Mac OSX under the Anaconda distribution (https://www.continuum.io/downloads).
+Ubuntu Linux is the recommended platform on which to install QSTrader, but it will also work on Windows or Mac OSX under the Anaconda distribution (https://www.continuum.io/downloads).
 
-For those that wish to create their own virtual environment, the following steps are necessary to run a basic Buy And Hold strategy.
+For those that wish to create their own Python virtual environment the following steps are necessary to run both a basic Buy And Hold strategy as well as a slightly more complex Moving Average Crossover trend-following strategy.
 
-An example virtual environment directory ```~/venv/qstraderp3``` has been used for this example. If you wish to change this directory then re-name it in the following steps.
+An example virtual environment directory ```~/venv/qstraderp3``` has been used here. If you wish to change this directory then rename it in the following steps.
 
 The following steps will create a virtual environment directory with Python 3 and then activate the environment:
 
 ```
 mkdir -p ~/venv/qstraderp3
 cd ~/venv/qstraderp3
-virtualenv --no-site-packages -p /usr/bin/python3 .
+virtualenv --no-site-packages -p python3 .
 source ~/venv/qstraderp3/bin/activate
 ```
 
-At this point it is necessary to use pip to install QSTrader as a library and then manually install the requirements. The following steps will take some time as QSTrader relies on NumPy, SciPy, Pandas, Matplotlib as well as many other libraries and hence they will all need to compile:
+At this point it is necessary to use pip to install QSTrader as a library and then manually install the requirements. The following steps will take some time (5-10 minutes) as QSTrader relies on NumPy, SciPy, Pandas, Matplotlib as well as many other libraries and hence they will all need to compile:
 
 ```
 pip install git+https://github.com/mhallsmoore/qstrader.git
@@ -75,15 +75,43 @@ Finally, we can run the backtest itself:
 python buy_and_hold_backtest.py
 ```
 
-Once complete you will see performance charts indicating:
+Once complete you will see a full "tearsheet" of results including:
 
 * Equity curve
-* Period returns
-* Drawdown
+* Drawdown curve
+* Monthly returns heatmap
+* Yearly returns distribution
+* Portfolio-level statistics
+* Trade-level statistics
 
-The chart will look similar to:
+The tearsheet will look similar to:
 
-![alt tag](https://s3.amazonaws.com/quantstart/media/images/qstrader-buy-and-hold.png)
+![alt tag](https://s3.amazonaws.com/quantstart/media/images/qstrader-buy-and-hold-tearsheet.png)
+
+You can explore the buy_and_hold_backtest.py file to examine the API of QSTrader. You will see that it is relatively straightforward to set up a simple strategy and execute it.
+
+For slightly more complex buy and sell rules it is possible to consider a Moving Average Crossover strategy. 
+
+The following strategy creates two Simple Moving Averages with respective lookback periods of 100 and 300 days. When the 100-period SMA exceeds the 300-period SMA 100 shares of AAPL are longed. When the 300-period SMA exceeds the 100-period SMA the position is closed out. To obtain the data for this strategy and execute it run the following code:
+
+```
+cd ~/data
+wget https://raw.githubusercontent.com/mhallsmoore/qstrader/master/data/AAPL.csv
+cd ~/qstrader/examples
+wget https://raw.githubusercontent.com/mhallsmoore/qstrader/master/examples/moving_average_cross_backtest.py 
+```
+
+The backtest can be executed with the following command:
+
+```
+python moving_average_cross_backtest.py
+```
+
+Once complete a full tearsheet will be presented, this time with a benchmark:
+
+![alt tag](https://s3.amazonaws.com/quantstart/media/images/qstrader-moving-average-cross-tearsheet.png)
+
+Other example strategies can be found in the ```examples``` directory. Each example is self-contained in a ```****_backtest.py``` file, which can be used as templates for your own strategies.
 
 The project is constantly being developed, so unfortunately it is likely that the current API will experience backwards incompatibility until a mature beta version has been produced.
 
@@ -93,7 +121,7 @@ If you notice any bugs or other issues that you think may be due to the codebase
 
 # License Terms
 
-Copyright (c) 2015-2016 Michael Halls-Moore
+Copyright (c) 2015-2017 Michael Halls-Moore
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: