This page is focused on the features of the IDE related to the workflow of writing a trading algorithm. To learn how to write an algorithm using the Algorithm API, see the Algorithm API (Tool) or Algorithm API Reference documentation.
Writing your algorithm is the first step in the development workflow. The IDE has a few basic features to make the experience of writing an algorithm as smooth as possible.
Autosave. Your work is automatically saved every 10 seconds, and you can click "Save" to manually save at any time. The IDE will warn you if you navigate away from the IDE page with unsaved changes.
Tab completion. You can press the "tab" key to view a list of suggested methods, namespaces, or functions. You can then use the up/down keys to highlight the correct suggestion, then press "Enter" to fill it in. The IDE will also autofill SIDs and symbols in manual asset lookup. For example:
View settings. In the IDE, click the Settings wheel (looks like a gear) in the upper right-hand corner to customize your font size and color theme. You can also select "Go Fullscreen" for a fullscreen development environment.
Once you've written your algorithm, you can "build" it.
Pressing "Build" will check your code for syntax errors and run a backtest within the IDE. This is a more lightweight version of a full backtest; it allows you to explore returns and simple metrics, but does not display the full performance/risk breakdown that the full backtest does. Importantly, building an algorithm uses the exact same backtest engine as running a full backtest. The primary reason to build an algorithm is to quickly determine if your backtest runs without an error on the first day.
Unlike a full backtest, this backtest will not be saved and thus will not be accessible for future analysis.
The console output in the bottom right-hand corner can have up to three tabs: "Build Errors", "Logs", and "Runtime Errors".
Build Errors: This tab appears if and only if there are "build errors" with your algorithm's code. Build errors are errors found within your algorithm's syntax -- for example, undefined variables or incorrect indentation.
Logs: This tab is always visible and displays any logged output.
Runtime Errors: This tab is always visible and displays any errors that prevent your algorithm from running to completion. If your algorithm runs successfully, this tab will be empty.
Sometimes, an algorithm might raise a warning instead of (or in addition to) error messages. Warnings usually tell you about a problem of some kind that isn't preventing the algorithm from running. While it might not present an immediate issue, it is generally advisable to address warning messages.
As you build your algorithm, the plot will show algorithm performance plotted against a benchmark and a summary of returns, Sharpe, and more.
If you recorded other variables beyond algorithm performance, there will be another plot below the algorithm performance plot that displays these timeseries.
In all plots, you can click on a variable name in the legend to remove it from the chart, allowing you to zoom in on the other time series. You can then click the variable name again to restore it on the chart.
To create a new backtest, click the "Run Full Backtest" button from the IDE. This will run a backtest that is saved and accessible for future analysis.
Closing the browser will not stop a full backtest from running. Quantopian runs in the cloud and it will continue to execute your backtest until it finishes running. If you want to stop the backtest, press the Cancel button.
Full Backtest Screen¶
Once you begin running a full backtest, the Full Backtest screen will open. In this screen, you can see which contest criteria are met by the algorithm and which need more work.
The full backtest screen has six tabs:
Overview. A summary of the contest criteria met and a plot of your algorithm's returns, as well as a benchmark (if desired). You can click on the benchmark label in the plot legend to toggle the visibility of the benchmark.
Structure. Simple yes/no checks to see whether a backtest is using the APIs required in the contest. Currently, algorithms are required to use the Optimize API and Quantopian Tradable Universe (
Risk. Risk exposures that a backtest should control. The metrics on the risk tab need to be kept within certain bounds to be eligible for the contest - for example, beta-to-SPY needs to be between -0.3 and 0.3.
Performance. Returns-driven metrics, like total returns or Sharpe ratio, that don’t have specific constraints placed upon them.
Activity. Miscellaneous information about a backtest, like its logs, source code, and transaction history. Note that the "Custom Data" tab contains data from recorded variables.
The contest tests the criteria on a two-year backtest looking back from the day you submit. It is possible that an algorithm might pass the criteria in a backtest and then fail one or more criteria in the contest if the backtset time period or duration are different.
Saving and Accessing Backtests¶
Your full backtests are automatically saved. Saved backtests are accessible from the Algorithms page (click the number of backtests that have been run) or from within the IDE editor (click All Backtests).
Once you are viewing all backtests for a given algorithm, you can name your backtest by clicking the pencil icon next to your backtest's name in the upper left-hand corner of the full backtest screen. You can delete your backtest by checking the box next to your backtest's name, then clicking the red trash can icon.
In addition to viewing backtest results in the IDE, you might also need to access the results of your backtest programmatically (for example, when analyzing your backtest with Pyfolio). In this case, you'll need to retrieve the ID of your backtest. You can find the ID of a backtest in the URL of its full backtest page, which will be of the form
/algorithms/<algorithm ID>/<backtest ID>.
Corporate Actions In Backtests¶
This section details how splits and dividends affect your portfolio in a backtest. This concept is distinct from how data is adjusted for corporate actions.
A stock split involves a change in the total number of shares outstanding. For example, a company may issue a 2-for-1 stock split to double the numebr of shares outstanding. A split also affects the price of the stock (since the split event doesn't double the value of the company!). In the example of a 2-for-1 split, the price per share of the company would be cut in half, thereby preserving the market capitalization of the company.
If you hold an asset during a split, the number of shares you hold will be affected. For example, AAPL underwent a 7:1 stock split on June 9, 2014. If you held one AAPL share on June 1, 2014, the backtester would adjust your portfolio to hold seven AAPL shares on June 10, 2014 (for 1/7th the price per share).
A dividend is the distribution of reward from a portion of the company's earnings and is paid to a class of its shareholders.
Dividends specify four dates:
- The ex date (dividend expiry date). If a holder sells the equity before this date, they are not paid the dividend. The ex date is when the price of the equity is typically most affected.
- The pay date is the date on which a shareholder receives the cash for a dividend.
- The declared date is the date on which the company announced the dividend.
- The record date is the date by which shareholders must be registered in the company's record in order to be paid the dividend. Registration in most countries is essentially automatic for shares purchased before the ex-dividend date.
In Quantopian backtesting, the only two dates that impact a simulation are the ex date and the pay date. Security prices are marked down by the dividend amount on the market open following the ex date. The portfolio's cash position is increased by the amount of the dividend on the pay date. Quantopian chose this method so that cash positions are correctly maintained.
In order for your algorithm to receive dividend cash payments, you must have a long position (positive amount) in the equity as of the close of market on the trading day prior to the ex date. If your simulation ends before the dividend's pay date (typically about 60 calendar days later), the dividend payment will remain unrealized and not be considered in your backtest's final portfolio value.
If you are short the equity at market close on the trading day prior to the ex date, your algorithm will be required to pay the dividends due. As with long positions, the cash balance will be debited by the dividend payments on the pay date. This is to reflect the short seller's obligation to pay dividends to the entity that loaned the equity.
Quantopian's IDE has extensive syntax and validation checks. It makes sure your algorithm is written using valid Python, fulfills requirements of Quantopian's APIs, and has no obvious runtime exceptions (such as dividing by zero). You can run the validation checks by clicking on the Build button (or pressing
CTRL+B), and Quantopian will run the checks automatically right before starting a new backtest.
Errors and warnings are shown in the window on the right side of the IDE under the "Build Errors" and "Runtime Errors" tabs.
When all errors and warnings are resolved, the Build button kicks off a backtest. Running a backtest via the Build button is a way to make sure that the algorithm roughly does what you want it to, without any errors.
Once the algorithm is running roughly the way you'd like, click the 'Full Backtest' button to kick off a full backtest.
The debugger gives you a powerful way to inspect the details of a running backtest. By setting "breakpoints", you can pause execution and examine variables, order state, positions, and any other data from your algorithm.
In the IDE, click on a line number in the gutter to set a breakpoint (left hand side where the line numbers are listed) . A breakpoint can be set on any line except comments and method definitions. A blue marker appears once the breakpoint is set.
To set a conditional breakpoint, right-click on a breakpoint's blue marker and click "Edit Breakpoint". Enter some Python code, and the breakpoint will hit when this condition evaluates to
True. Conditional breakpoints are shown in yellow in the left-hand gutter.
You can set an unlimited number of breakpoints. Once the backtest has started, it will stop when execution gets to a line that has a breakpoint, at which point the backtest is paused and the debug window is shown. In the debugger, you can then query your variables, orders and portfolio state, data, and anything else used in your backtest. While the debugger window is active, you can set and remove other breakpoints.
To inspect an object, enter it in the debug window and press enter. Most objects will be pretty-printed into a tree format to enable easy inspection and exploration.
The following commands can be used in the debugger window:
||Resume backtest until it triggers the next breakpoint or an exception is raised.|
||Executes the next line of code. This steps over the next expression.|
||Executes the next line of code. This steps into the next expression, following function calls.|
||Execute until you are about to return from the current function call.|
||Disables all breakpoints and finishes the backtest.|
||Clears the data in the debugger window.|
||Shows the command shortcuts for the debugger.|
- The debugger is available in the IDE. It is not available on the full backtest screen.
- You can edit your code during a debugging session, but those edits aren't used in the debugger until a new backtest is started.
- After 10 minutes of inactivity in the IDE, any breakpoints will be suspended and the backtest will automatically finish running.
- After 50 seconds, the breakpoint commands will timeout. (This is the same amount of time given for 1 a scheduled function call.)
Your algorithm can easily generate log output by using the
log.debug) methods. Log output appears in the right-hand panel of the IDE or in the full backtest screen under Activity > Logs.
Logging is rate-limited (throttled) for performance reasons. Log limits are outlined here. Once the limit is exceeded, messages are discarded until the buffer has been emptied. A message explaining that some messages were discarded is shown.
You can collaborate in real-time with other Quantopian members on your algorithm.
To collaborate, press the “Collaborate” button in the IDE and enter your collaborator's email address. Your collaborator will receive an email from Quantopian letting them know that they have been invited. They will also see your algorithm listed in their Algorithms Library with a collaboration icon. If your collaborator isn't a Quantopian member, they will have to register before they can see your algorithm.
Even if your collaborator is a Quantopian member, you'll need to invite them by email address (not Quantopian user ID or contest/display name). To connect with a Quantopian member, search their profile in the forums and send them a private message. If they choose to share their email address with you, then you can invite them to collaborate.
The collaboration experience is coordinated with the following features:
- Code changes are synchronized across all screens in real time.
- When one collaborator backtests an algorithm, all of the collaborators see the backtest results, logging, and/or errors.
- Collaborators can use a built-in chat tab within the IDE.
A few important notes and restrictions on collaboration:
- Only the owner can invite other collaborators, enter the algorithm in the contest, or delete the algorithm.
- After submitting an algorithm to the contest, only the owner's contest name will be displayed.
- Any contest winnings will be sent to the owner.
- There isn't a technical limit on number of collaborators, but there is a practical limit. The more collaborators you have, the more likely that you'll notice a performance problem.
For security reasons, only specific portions of Python modules are whitelisted for import. Select portions of the modules listed on the Algorithm IDE Whitelist are available for import.
If you need a module that isn't on this list, please let us know by contacting firstname.lastname@example.org.