Holy Hand Grenade of Antioch

From Quantitative Analysis Software Courses
(Redirected from HolyHandgrenade)
Jump to navigation Jump to search

Updates / FAQs

  • 2019-08-08 First draft
  • 2019-08-23 Revision to count only cash at EOD.
  • 2019-09-16 Revision for utilities to visualize the order book and final cash holdings.
  • 2019-09-20 Revision to the Hhg_utils.zip file to include contributed_traders modifications.
  • 2020-03-19 Revision to the git clone command.

This assignment is subject to change up until 3 weeks prior to the due date. We do not anticipate further changes; any changes will be logged in this section.

Overview

First use of the Holy Hand Grenade. From the documentary film "Monty Python and the Holy Grail."

In this optional project you will implement an agent that trades in a simulated High Frequency Trading (HFT) environment that includes dozens of other trading agents. The success of your contributed code and your score on the project will depend on how profitable your agent's trading is. The following rules apply:

  • Your agent starts each morning with $100,000 in cash.
  • You will trade only one asset, JPM.
  • Trading begins at 9:30AM, the market closes at 4:00PM.
  • Your score depends on the value of the cash component of your portfolio as of market close. Stock positions don't count. This is to incentivize you to exit your positions before the end of the day.
  • Your agent should never initiate a trade that will cause your portfolio to exceed a leverage of 1.0.

About the ABIDES simulator and getting started

You will implement your trading agent to run within the Agent-Based Interactive Discrete Event Simulation (ABIDES). ABIDES was designed by Prof. Tucker Balch and David Byrd at Georgia Tech with Prof. Maria Hybinette of UGA. Byrd is the lead architect and developer of ABIDES. The development of ABIDES has been supported by the NSF and It is now available as open source at GitHub.

ABIDES is used in research at Georgia Tech and at J.P. Morgan to develop and evaluate trading algorithms and models of market structure.

Get the ABIDES simulation distribution at GitHub here: https://github.com/abides-sim/abides

Get the zip file that contains an updated SimpleAgent and utilities here. Important: This zip file will update/replace files within abides and it's very important you unzip it from within abides

The ABIDES python environment is compatible with the course environment. Nothing is required to be installed/configured on the buffet machines to run ABIDES. If you've followed the instructions on the software setup for the course, they should be compatible as well.

Note that you should never issue a pull request to this repo. It will expose your code to others and you will be perceived as uncool. To get ABIDES configured, run the following commands: 

git -c advice.detachedHead=false clone -b v1.0 https://github.com/abides-sim/abides
cd abides
wget https://quantsoftware.gatech.edu/images/9/99/Hhg_utils.zip
unzip -o Hhg_utils.zip

To run the example trading agent, run this following command: 

sh ./scripts/rmsc.sh contributed_traders.SimpleAgent

As an example analysis plot, you may run the following command after running the simulation with the SimpleAgent: 

python rmsc_book_plot.py ./log/rmsc01/orderbook_JPM.bz2

A file, OrderBook.png, will be created that depicts the order book data (volume) and the mid-prices (in black).

You will find a subdirectory in the distribution: 

ABIDES/contributed_traders

The contributed_traders directory is where we collect agents that will contribute to our ecosystem of traders. We hope, perhaps to include yours there in the future. There is a subdirectory for each participating agent. Note that the contributed_traders contains a basic example agent (SimpleAgent.py) after which you can pattern the trading agent you design.

What you should do

Create your own directory: 

ABIDES/contributed_traders/yourID_agentname

Where ID is a set of characters that uniquely identify you. If you are a Georgia Tech student for instance, this should be your login ID (e.g., mine is tb34). "agentname" is your specific name for this agent. We should have separate names for agents submitted by the same person because in the future you might improve the one you wrote, or you might want to contribute a new one with a different name. An example directory and agent name then might be tb34_shark. Copy the template code into that subdirectory and rename it "yourID_agentname.py" and be sure also that your agent's class name is "yourID_agentname" You would then invoke the test scenario, including your agent, with the following command: 

 sh ./scripts/rmsc.sh contributed_traders.yourID_agentname.yourID_agentname

N.B. The rmsc.sh script hard codes a random seed. You'll need to change the seed variable (line 3) to a different random seed if you want to capture different runs. You may also want to change the log directory to save the results of different runs.

You can assume that your agent will have read access to "your" subdirectory. So you can store a learned policy there. However you will not have write access. Do not attempt to read from any other directory. It is required that you follow the path name conventions used by the example agent provided, namely that the subdirectory location is relative. If you do not follow that convention, your code will break and we will not grade it. An example of how to read any configuration files/stored policies can be found in SimpleAgent.py. Note: it makes use of abides/contributed_agents/util.py to read a configuration file. You are to also use the util.py file in abides/contributed_agents/util.py (do not make a copy). You can reference this utility in the same manner as SimpleAgent.py. Assuming: your gtid was tb34, you named your agent myAgent, and you had a configuration file myagent.cfg, you'd end up with the following directory structure: 

contributed_traders/
├── __init__.py
├── simple_agent.cfg
├── SimpleAgent.py
├── tb34_myAgent
│   ├── myagent.cfg
│   └── tb34_myAgent.py
└── util.py

Inside of tb34_myAgent.py, you'd have a line like this (assuming you had the same parameters and type of configuration as SimpleAgent.py has): 

with open(get_file('tb34_myAgent/myagent.cfg'), 'r') as f:             
    self.window1, self.window2 = [int(w) for w in f.readline().split()]

Take advantage of the Agent.kernelInitializing() method to initialize your agent. This is where, for instance, you can read in a policy if you have trained one up. Also use Agent.kernelTerminating() if you are training a policy to save it as the trading day wraps up to save any logs or new learning results. Remember though, that your submitted code should never ever write to a file!

Be sure to update the author(), agentname(), and number_of_counting() methods to report yourID, your agent's full name (i.e., yourID_agentname) and the correct number of counting. We will call them at evaluation time in order to build a report that describes the performance of the contributed agents.

Now, build an agent that performs well through a trading day.

At the end of the day, we will call your agent's getHoldings() method to see how profitable it's trading has been. Remember that only the cash component counts.

For convenience, we've provided you with a tool to evaluate your final cash holdings at the end of a run. For example: 

 python get_fch.py log/rmsc01/contributed_traders.SimpleAgent.bz2

Your final cash holdings - initial cash holdings will be considered your profit amount.

README.txt

Please include a plain text README.txt file with your submission that describes the approach your trader follows. The description should be sufficiently detailed that one of your peers could reproduce your approach. A few paragraphs should be sufficient.

How to submit your entry

When you are ready to submit your code take the following steps to create a zip file of your code. Note that this may be the only situation in this course for which we allow submission of a zip file. 

 cd ABIDES/contributed_traders
 zip -ry yourID_youragentname.zip yourID_youragentname

You should submit that zip file to us for assessment. Note that we will copy your zip file to our own copy of ABIDES/contributed_traders and unzip it there. It will be irritating if the wrong stuff appears at that time, so please be sure you zip it correctly.

Strategy, evaluation and scoring

Visualization of the the order book in a simulated trading day in ABIDES. Note the mean-reverting nature of the price time series. Image produced by Mahmoud Mahfouz.

Your trader will be evaluated in two ways, first we will run it in the provided environment of other trading agents and evaluate whether or not it is profitable. The majority of agents populating the simulation are ZI or Zero Intelligence agents. The ZI agents assume a mean reverting market, and they trade based on that assumption. You can exploit that information for your own profitability.

Note that our intent is to exercise your agent across an entire day of trading, but if the simulation takes too long to run we may need to shorten that time. You can assume the market will close at 4:00PM, but don't assume it will open at 9:30AM. Also, in the distributed configuration, the market always opens at 100,000 cents ($100.00), but you should not depend on that in your strategy. We may choose for the market to open at a different price.

There is no leverage allowed. You are to trade only with the available cash/shares in your portfolio.

Scoring Part 1 (up to 50 points): We will run your trader 10 times and count the number of times it is profitable. Note that we would expect a trader that acts randomly to be profitable 50% of the time, so you must do better than random to get any points. outperforms the SimpleAgent trader. We will have 10 different random seeds (1 for each run) and we will run your agent with the scenario and then run SimpleAgent with the same scenario (and seed). You must have a higher ending cash value than the SimpleAgent.

The Part 1 scoring will work as follows:

  • +25 points if profitable it outperforms more than 50% of the time.
  • +5 points * (number of times profitable outperforms - 5). Minimum 0 points, maximum 25 points for this part.

Examples: Profitable Outperforms 6 times, Part 1 score = 20 points. OutperformsProfitable 2 times, score = 0 points.

Scoring Part 2 (up to 50 points): Your trader is only eligible for this phase if it scored more than 0 points in Part 1. We will add your trader together with the other traders that scored more than 0 points in Part 1. They will trade against each other along with the other agents present in the provided environment. We will group the traders by quintiles, and award points as follows:

  • +50 points if in top quintile
  • +40 points if in second quintile
  • +30 points if in third quintile
  • +20 points if in fourth quintile
  • +10 points if in fifth quintile

Scoring Part 3

README.txt. Should describe the code that was submitted. Should be sufficiently detailed that your peers could reproduce the work.

  • Up to 10 points.
  • Is README.txt a Word document? -10 points.
  • Is README.txt a PDF document? -10 points.
  • Is README.txt something other than plain text? -10 points.
  • Are there any shrubberies? -10 points.

Grading policies

  • Late submissions cannot be considered.
  • Please attempt this project only for the fun of it, because you enjoy the trading problem. It is likely to require a lot of effort that may not be worth it in terms of the points received. Do not count on points from this assignment to make a change in your grade.
  • We will test your code on one of the buffet servers. If your submitted code does not work because you did not test it on a buffet server, we will not consider it further.
  • If your code fails to run for other reasons, we may not grade it, even if it is not your fault.
  • There are many ways to cheat on this project, such as to "forge" the component that returns your profit, or to use extra leverage. We will check for these things and treat them as violations of the honor code.

Can we use your code?

One motivation for this effort is to create an "ecosystem" of trading agents that will combine to provide a realistic environment for trading research. If your agent performs well (and runs fast) we may want to add it to our publicly distributed collection of trading agents. We would be pleased if you would let us, and we will credit you appropriately. Note that it is our intention to include the best agents from this semester into the distribution for use next semester, so the next group of students will have to compete against your contributed agents. We may also use your code in future experiments for which we need realistic scenarios.

If you are willing to allow us to use and distribute your agent code, please add the following comment to all of the files you submit: 

# Author: Your Name
# Agent Name: 
#
# The author of this code hereby permits it to be included as a part of the ABIDES distribution, 
# and for it to be released under any open source license the ABIDES authors choose to release ABIDES under.

Note that if you include other people's code (e.g., snippets from scikit learn) we may not be able to use your contribution.

Required, Allowed & Prohibited

Required:

  • Your project must be coded in Python 3.x.
  • Your code must run on one of the university-provided computers (e.g. buffet03.cc.gatech.edu).
  • All code required to run the agent must be submitted. We will not debug your code.
  • All code in your submitted agent must be written by you.

Allowed:

  • You can develop your code on your personal machine, but it must also run successfully on one of the university provided machines or virtual images.
  • Your code may use standard Python libraries.
  • You may use the NumPy, SciPy, matplotlib and Pandas libraries. Be sure you are using the correct versions.
  • You may reuse sections of code (up to 5 lines) that you collected from other students or the internet.
  • Code provided by the instructor, or allowed by the instructor to be shared.
  • You may reuse code from the internet that you include as support files (it must be credited and cited).

Prohibited:

  • Any libraries not listed in the "allowed" section above.

Mythology

As you know, the course includes an occasional reference to medieval Britain. For instance, a previous extra credit assignment was patterned after the Killer Rabbit of Caerbannog (see http://quantsoftware.gatech.edu/MC3-Project-5). In British mythology, the Holy Hand Grenade of Antioch was used to kill the Rabbit of Caerbannog. It is designed after the Sovereign's Orb of the United Kingdom, and may refer to the mythical Holy Spear of Antioch. In a the documentary film "Monty Python and the Holy Grail" the Holy Hand Grenade is described as one of the "sacred relics" carried by Brother Maynard (played by Eric Idle). Despite its ornate appearance and long-winded instructions, it functions much the same as any other hand grenade. At King Arthur's prompting, instructions for its use are read aloud (by actor Michael Palin) from the Book of Armaments, Chapter 2, verses 9–21, an apocryphal chapter of the King James Bible and the Athanasian Creed.

References:

FAQs

  • Q: I'm using a Mac. When I try to plot the order book, I get a strange exception with a stack trace, including a mention of libtk and tkinter.
  • A: Run the following commands from the terminal to change the default back end
$ mkdir -p ~/.matplotlib

$ echo "backend: TkAgg" > ~/.matplotlib/matplotlibrc
Retrieved from "http://quantsoftware.gatech.edu/index.php?title=Holy_Hand_Grenade_of_Antioch&oldid=3845"