API Reference

Tip: get help directly from the CLI/Python client

The API documentation shown below for the command line interface (CLI) and Python client is auto-generated and can be referenced at any time from the clients themselves. To view the API documentation for the CLI, use the -h/--help option with any command or subcommand:

$ quantrocket history create-usstock-db -h

To view Python documentation in a Jupyter Notebook or Console, use the question mark syntax:

In [1]: from quantrocket.history import create_usstock_db
In [2]: create_usstock_db?

quantrocket.account

account service

QuantRocket account CLI

usage: quantrocket account [-h] {balance,portfolio,rates} ...

subcommands¶

subcommand: Possible choices: balance, portfolio, rates

Sub-commands:¶

balance¶

query account balances

quantrocket account balance [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD] [-l]
                            [-a [ACCOUNT [ACCOUNT ...]]]
                            [-b [FIELD:AMOUNT [FIELD:AMOUNT ...]]]
                            [-o OUTFILE] [-j] [-f [FIELD [FIELD ...]]]
                            [--force-refresh]

Named Arguments¶

--force-refresh

refresh account balances to ensure the latest data (default is to query the database, which is refreshed every minute)

Default: False

filtering options¶

-s, --start-date

limit to account balance snapshots taken on or after this date

-e, --end-date

limit to account balance snapshots taken on or before this date

-l, --latest

return the latest account balance snapshot

Default: False

-a, --accounts

limit to these accounts

-b, --below

limit to accounts where the specified field is below the specified amount (pass as field:amount, for example Cushion:0.05)

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)
-f, --fields: only return these fields. By default a core set of fields is returned. Pass a list of fields, or ‘*’ to return all fields. Pass ‘?’ or any invalid fieldname to see available fields.

Query account balances.

Examples:

Query the latest account balances.

quantrocket account balance –latest

Query the latest NLV (Net Liquidation Value) for a particular account:

quantrocket account balance –latest –fields NetLiquidation –accounts U123456

Check for accounts that have fallen below a 5% cushion and log the results, if any, to flightlog:

quantrocket account balance –latest –below Cushion:0.05 | quantrocket flightlog log –name quantrocket.account –level CRITICAL

Query historical account balances over a date range:

quantrocket account balance –start-date 2017-06-01 –end-date 2018-01-31

portfolio¶

download current portfolio

quantrocket account portfolio [-h] [-b [BROKER [BROKER ...]]]
                              [-a [ACCOUNT [ACCOUNT ...]]]
                              [-t [SEC_TYPE [SEC_TYPE ...]]]
                              [-e [EXCHANGE [EXCHANGE ...]]]
                              [-i [SID [SID ...]]] [-s [SYMBOL [SYMBOL ...]]]
                              [-z] [-o OUTFILE] [-j] [-f [FIELD [FIELD ...]]]

filtering options¶

-b, --brokers

Possible choices: alpaca, ibkr

limit to these brokers. Possible choices: [‘alpaca’, ‘ibkr’]

-a, --accounts

limit to these accounts

-t, --sec-types

limit to these security types

-e, --exchanges

limit to these exchanges

-i, --sids

limit to these sids

-s, --symbols

limit to these symbols

-z, --zero

include zero position rows (default is to exclude them). Only supported for Interactive Brokers.

Default: False

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)
-f, --fields: only return these fields. By default a core set of fields is returned. Pass a list of fields, or ‘*’ to return all fields. Pass ‘?’ or any invalid fieldname to see available fields.

Download current portfolio.

Examples:

View current portfolio in terminal:

quantrocket account portfolio | csvlook

Download current portfolio for a particular account and save to file:

quantrocket account portfolio –accounts U12345 -o portfolio.csv

rates¶

query exchange rates for the base currency

quantrocket account rates [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD] [-l]
                          [-b [CURRENCY [CURRENCY ...]]]
                          [-q [CURRENCY [CURRENCY ...]]] [-o OUTFILE] [-j]

filtering options¶

-s, --start-date

limit to exchange rates on or after this date

-e, --end-date

limit to exchange rates on or before this date

-l, --latest

return the latest exchange rates

Default: False

-b, --base-currencies

limit to these base currencies

-q, --quote-currencies

limit to these quote currencies

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)

Query exchange rates for the base currency.

The exchange rates in the exchange rate database are sourced from the European Central Bank’s reference rates, which are updated each day at 4 PM CET.

Examples:

Query the latest exchange rates.

quantrocket account rates –latest

quantrocket.account.download_account_balances(filepath_or_buffer=None, output='csv', start_date=None, end_date=None, latest=False, accounts=None, below=None, fields=None, force_refresh=False)¶

Query account balances.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json or csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to account balance snapshots taken on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to account balance snapshots taken on or before this date
latest (bool) – return the latest account balance snapshot
accounts (list of str, optional) – limit to these accounts
below (dict of FIELD:AMOUNT, optional) – limit to accounts where the specified field is below the specified amount (pass as {field:amount}, for example {‘Cushion’:0.05})
fields (list of str, optional) – only return these fields. By default a core set of fields is returned. Pass a list of fields, or ‘*’ to return all fields. Pass [‘?’] or any invalid fieldname to see available fields.
force_refresh (bool) – refresh account balances to ensure the latest data (default is to query the database, which is refreshed every minute)

Returns

Return type

None

Examples

Query latest balances. You can use StringIO to load the CSV into pandas.

>>> f = io.StringIO()
>>> download_account_balances(f, latest=True)
>>> balances = pd.read_csv(f, parse_dates=["LastUpdated"])

quantrocket.account.download_account_portfolio(filepath_or_buffer=None, output='csv', brokers=None, accounts=None, sec_types=None, exchanges=None, sids=None, symbols=None, include_zero=False, fields=None)¶

Download current portfolio.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json or csv, default is csv)
brokers (list of str, optional) – limit to these brokers. Possible choices: alpaca, ibkr
accounts (list of str, optional) – limit to these accounts
sec_types (list of str, optional) – limit to these security types
exchanges (list of str, optional) – limit to these exchanges
sids (list of str, optional) – limit to these sids
symbols (list of str, optional) – limit to these symbols
include_zero (bool) – include zero position rows (default is to exclude them). Only supported for Interactive Brokers.
fields (list of str, optional) – only return these fields. By default a core set of fields is returned. Pass a list of fields, or ‘*’ to return all fields. Pass ‘?’ or any invalid fieldname to see available fields.

Returns

Return type

None

Examples

Download current portfolio. You can use StringIO to load the CSV into pandas.

>>> f = io.StringIO()
>>> download_account_portfolio(f)
>>> portfolio = pd.read_csv(f, parse_dates=["LastUpdated"])

quantrocket.account.download_exchange_rates(filepath_or_buffer=None, output='csv', start_date=None, end_date=None, latest=False, base_currencies=None, quote_currencies=None)¶

Query exchange rates for the base currency.

The exchange rates in the exchange rate database are sourced from the European Central Bank’s reference rates, which are updated each day at 4 PM CET.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json, csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to exchange rates on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to exchange rates on or before this date
latest (bool) – return the latest exchange rates
base_currencies (list of str, optional) – limit to these base currencies
quote_currencies (list of str, optional) – limit to these quote currencies

Returns

Return type

None

Examples

Query latest exchange rates. You can use StringIO to load the CSV into pandas.

>>> f = io.StringIO()
>>> download_exchange_rates(f, latest=True)
>>> rates = pd.read_csv(f, parse_dates=["Date"])

Account API

Resource Group ¶

Account Balances ¶

Get Account Balances
GET`/account/balances.{output}{?start_date,end_date,latest,accounts,below,fields,force_refresh}`

Query account balances.

Example URI

GET http://houston/account/balances.csv?start_date=2017-01-01&end_date=2018-01-01&latest=true&accounts=U123456&below=Cushion:0.05&fields=NetLiquidation&force_refresh=true

URI Parameters

output

str (required) Example: csv

output format

Choices: csv json

start_date

str (optional) Example: 2017-01-01

limit to account balance snapshots taken on or after this date

end_date

str (optional) Example: 2018-01-01

limit to account balance snapshots taken on or before this date

latest

bool (optional) Example: true

return the latest account balance snapshot

accounts

str (optional) Example: U123456

limit to these accounts (pass multiple times for multiple accounts)

below

str (optional) Example: Cushion:0.05

limit to accounts where the specified field is below the specified amount (pass as ‘field:amount’, for example ‘Cushion:0.05’) (pass multiple times for multiple filters)

fields

str (optional) Example: NetLiquidation

only return these fields (pass ‘?’ or any invalid fieldname to see available fields) (pass multiple times for multiple fields)

force_refresh

bool (optional) Example: true

refresh account balances to ensure the latest data (default is to query the database, which is refreshed every minute)

Response 200

Headers

Content-Type: text/csv

Body

Broker,Account,Currency,NetLiquidation,LastUpdated
ibkr,DU123456,USD,500000.0,"2017-12-16 14:28:54"

Exchange rates ¶

Get Exchange Rates
GET`/account/rates.{output}{?start_date,end_date,latest,base_currencies,quote_currencies}`

Query exchange rates for the base currency.

The exchange rates in the exchange rate database are sourced from the European Central Bank’s reference rates, which are updated each day at 4 PM CET.

Example URI

GET http://houston/account/rates.csv?start_date=2017-01-01&end_date=2018-01-01&latest=true&base_currencies=USD&quote_currencies=CAD

URI Parameters

output

str (required) Example: csv

output format

Choices: csv json

start_date

str (optional) Example: 2017-01-01

limit to exchange rates on or after this date

end_date

str (optional) Example: 2018-01-01

limit to exchange rates on or before this date

latest

bool (optional) Example: true

return the latest exchange rates

base_currencies

str (optional) Example: USD

limit to these base currencies (pass multiple times for multiple base currencies)

quote_currencies

str (optional) Example: CAD

limit to these quote currencies (pass multiple times for multiple quote currencies)

Response 200

Headers

Content-Type: text/csv

Body

BaseCurrency,QuoteCurrency,Rate,Date
USD,AUD,1.2774,2018-01-09
USD,CAD,1.2425,2018-01-09
USD,CHF,0.98282,2018-01-09

Account Portfolio ¶

Get Account Portfolio
GET`/account/portfolio.{output}{?brokers,accounts,sec_types,exchanges,sids,symbols,include_zero,fields}`

Download current portfolio.

Example URI

GET http://houston/account/portfolio.csv?brokers=ibkr&accounts=U12345&sec_types=STK&exchanges=XNYS&sids=FI12345&symbols=AAPL&include_zero=true&fields=Sid

URI Parameters

output

str (required) Example: csv

output format

Choices: csv json

brokers

str (optional) Example: ibkr

limit to these brokers.

Choices: alpaca ibkr

accounts

str (optional) Example: U12345

limit to these accounts

sec_types

str (optional) Example: STK

limit to these security types

exchanges

str (optional) Example: XNYS

limit to these exchanges

sids

str (optional) Example: FI12345

limit to these sids

symbols

str (optional) Example: AAPL

limit to these symbols

include_zero

bool (optional) Example: true

include zero position rows (default is to exclude them). Only supported for Interactive Brokers.

fields

str (optional) Example: Sid

only return these fields. By default a core set of fields is returned. Pass a list of fields, or ‘*’ to return all fields. Pass ‘?’ or any invalid fieldname to see available fields.

Response 200

Headers

Content-Type: text/csv

quantrocket.blotter

order management and trade ledger service

QuantRocket blotter CLI

usage: quantrocket blotter [-h]
                           {order,cancel,status,positions,close,executions,pnl}
                           ...

subcommands¶

subcommand: Possible choices: order, cancel, status, positions, close, executions, pnl

Sub-commands:¶

order¶

place one or more orders

quantrocket blotter order [-h]
                          [-f INFILE | -p [PARAM:VALUE [PARAM:VALUE ...]]]

Named Arguments¶

-f, --infile: place orders from this CSV or JSON file (specify ‘-‘ to read file from stdin)
-p, --params: order details as multiple key-value pairs (pass as ‘param:value’, for example OrderType:MKT)

Place one or more orders.

Returns a list of order IDs, which can be used to cancel the orders or check their status.

Examples:

Place orders from a CSV file.

quantrocket blotter order -f orders.csv

Place orders from a JSON file.

quantrocket blotter order -f orders.json

Place an order by specifying the order parameters on the command line:

quantrocket blotter order –params Sid:FIBBG123456 Action:BUY Exchange:SMART TotalQuantity:100 OrderType:MKT Tif:Day Account:DU12345 OrderRef:my-strategy

cancel¶

cancel one or more orders by order ID, sid, or order ref

quantrocket blotter cancel [-h] [-d [ORDER_ID [ORDER_ID ...]]]
                           [-i [SID [SID ...]]]
                           [-r [ORDER_REF [ORDER_REF ...]]]
                           [-a [ACCOUNT [ACCOUNT ...]]] [--all]

Named Arguments¶

-d, --order-ids

cancel these order IDs

-i, --sids

cancel orders for these sids

-r, --order-refs

cancel orders for these order refs

-a, --accounts

cancel orders for these accounts

--all

cancel all open orders

Default: False

Cancel one or more orders by order ID, sid, or order ref.

Examples:

Cancel orders by order ID:

quantrocket blotter cancel -d 6002:45 6001:46

Cancel orders by sid:

quantrocket blotter cancel -i FIBBG123456

Cancel orders by order ref:

quantrocket blotter cancel –order-refs my-strategy

Cancel all open orders:

quantrocket blotter cancel –all

status¶

download order statuses

quantrocket blotter status [-h] [-d [ORDER_ID [ORDER_ID ...]]]
                           [-i [SID [SID ...]]]
                           [-r [ORDER_REF [ORDER_REF ...]]]
                           [-a [ACCOUNT [ACCOUNT ...]]] [--open]
                           [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                           [-f [FIELD [FIELD ...]]] [-o OUTFILE] [-j]

filtering options¶

-d, --order-ids

limit to these order IDs

-i, --sids

limit to orders for these sids

-r, --order-refs

limit to orders for these order refs

-a, --accounts

limit to orders for these accounts

--open

limit to open orders

Default: False

-s, --start-date

limit to orders submitted on or after this date

-e, --end-date

limit to orders submitted on or before this date

output options¶

-f, --fields: return these fields in addition to the default fields (pass ‘?’ or any invalid fieldname to see available fields)
-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)

Download order statuses.

Examples:

Download order status by order ID and save to file:

quantrocket blotter status -d 6002:45 6001:46 -o statuses.csv

Download order status for all open orders and display in terminal:

quantrocket blotter status –open | csvlook

Download order status with extra fields and display as YAML:

quantrocket blotter status –open –fields Exchange LmtPrice –json | json2yaml

Download order status of open orders by sid:

quantrocket blotter status -i FIBBG123456 –open

Download order status of open orders by order ref:

quantrocket blotter status –order-refs my-strategy –open

positions¶

query current positions

quantrocket blotter positions [-h] [-i [SID [SID ...]]]
                              [-r [ORDER_REF [ORDER_REF ...]]]
                              [-a [ACCOUNT [ACCOUNT ...]]] [--diff] [--broker]
                              [-o OUTFILE] [-j]

filtering options¶

-i, --sids

limit to these sids

-r, --order-refs

limit to these order refs (not supported with broker view)

-a, --accounts

limit to these accounts

--diff

limit to positions where the blotter quantity and broker quantity disagree (requires –broker)

Default: False

output options¶

--broker: return ‘broker’ view of positions (by account and sid) instead of default ‘blotter’ view (by account, sid, and order ref)
-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)

Query current positions.

There are two ways to view positions: blotter view (default) and broker view.

The default “blotter view” returns positions by account, sid, and order ref. Positions are tracked based on execution records saved to the blotter database.

“Broker view” (using the –broker option) returns positions by account and sid (but not order ref) as reported directly by the broker.

Examples:

Query current positions:

quantrocket blotter positions

Save current positions to CSV file:

quantrocket blotter positions –outfile positions.csv

Query positions for a single order ref:

quantrocket blotter positions –order-refs my-strategy

Query positions using broker view:

quantrocket blotter positions –broker

close¶

generate orders to close positions

quantrocket blotter close [-h] [-i [SID [SID ...]]]
                          [-r [ORDER_REF [ORDER_REF ...]]]
                          [-a [ACCOUNT [ACCOUNT ...]]] [-o OUTFILE]
                          [-p [PARAM:VALUE [PARAM:VALUE ...]]] [-j]

filtering options¶

-i, --sids: limit to these sids
-r, --order-refs: limit to these order refs
-a, --accounts: limit to these accounts

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-p, --params: additional parameters to append to each row in output (pass as ‘param:value’, for example OrderType:MKT)
-j, --json: format output as JSON (default is CSV)

Generate orders to close positions.

Doesn’t actually place any orders but returns an orders file that can be placed separately. Additional order parameters can be appended with the –params option.

Examples:

Generate MKT orders to close positions for a particular strategy:

quantrocket blotter close –order-refs my-strategy –params OrderType:MKT Tif:DAY Exchange:SMART

Generate orders and also place them:

quantrocket blotter close -r my-strategy -p OrderType:MKT Tif:DAY Exchange:SMART | quantrocket blotter order -f -

executions¶

query executions from the executions database

quantrocket blotter executions [-h] [-i [SID [SID ...]]]
                               [-r [ORDER_REF [ORDER_REF ...]]]
                               [-a [ACCOUNT [ACCOUNT ...]]] [-s YYYY-MM-DD]
                               [-e YYYY-MM-DD] [-o OUTFILE]

filtering options¶

-i, --sids: limit to these sids
-r, --order-refs: limit to these order refs
-a, --accounts: limit to these accounts
-s, --start-date: limit to executions on or after this date
-e, --end-date: limit to executions on or before this date

output options¶

-o, --outfile: filename to write the data to (default is stdout)

Query executions from the executions database.

Examples:

Get a CSV of all executions:

quantrocket blotter executions -o executions.csv

pnl¶

query trading performance and return a PDF tearsheet or CSV of results

quantrocket blotter pnl [-h] [-i [SID [SID ...]]]
                        [-r [ORDER_REF [ORDER_REF ...]]]
                        [-a [ACCOUNT [ACCOUNT ...]]] [-s YYYY-MM-DD]
                        [-e YYYY-MM-DD] [-d] [-t TIMEZONE] [--pdf]
                        [-o OUTFILE]

filtering options¶

-i, --sids: limit to these sids
-r, --order-refs: limit to these order refs
-a, --accounts: limit to these accounts
-s, --start-date: limit to pnl on or after this date
-e, --end-date: limit to pnl on or before this date

output options¶

-d, --details

return detailed results for all securities instead of aggregating to account/order ref level (only supported for a single account and order ref at a time)

Default: False

-t, --timezone

return execution times in this timezone (default UTC)

--pdf

return a PDF tear sheet of PNL (default is to return a CSV)

-o, --outfile

filename to write the data to (default is stdout)

Query trading performance and return a PDF tearsheet or CSV of results.

Trading performance is broken down by account and order ref and optionally by sid.

Examples:

Get a Moonchart PDF of all trading performance PNL:

quantrocket blotter pnl -o pnl.pdf –pdf

Get a PDF for a single account and order ref, broken down by sid:

quantrocket blotter pnl –accounts U12345 –order-refs mystrategy1 –details –pdf -o pnl_details.pdf

Get a CSV of performance results for a particular date range:

quantrocket blotter pnl -s 2018-03-01 -e 2018-06-30 -o pnl_2018Q2.csv

quantrocket.blotter.place_orders(orders=None, infilepath_or_buffer=None)¶

Place one or more orders.

Returns a list of order IDs, which can be used to cancel the orders or check their status.

Parameters

orders (list of dict of PARAM:VALUE, optional) – a list of one or more orders, where each order is a dict specifying the order parameters (see examples)
infilepath_or_buffer (str or file-like object, optional) – place orders from this CSV or JSON file (specify ‘-‘ to read file from stdin). Mutually exclusive with orders argument.

Returns

order IDs

Return type

list

Examples

>>> orders = []
>>> order1 = {
        'Sid':'FIBBG123456',
        'Action':'BUY',
        'Exchange':'SMART',
        'TotalQuantity':100,
        'OrderType':'MKT',
        'Tif':'Day',
        'Account':'DU12345',
        'OrderRef':'my-strategy'
    }
>>> orders.append(order1)
>>> order_ids = place_orders(orders)

quantrocket.blotter.cancel_orders(order_ids=None, sids=None, order_refs=None, accounts=None, cancel_all=None)¶

Cancel one or more orders by order ID, sid, or order ref.

Parameters

order_ids (list of str, optional) – cancel these order IDs
sids (list of str, optional) – cancel orders for these sids
order_refs (list of str, optional) – cancel orders for these order refs
accounts (list of str, optional) – cancel orders for these accounts
cancel_all (bool) – cancel all open orders

Returns

status message

Return type

dict

Examples

Cancel orders by order ID:

>>> cancel_orders(order_ids=['6002:45','6002:46'])

Cancel orders by sid:

>>> cancel_orders(sids=["FIBBG123456"])

Cancel orders by order ref:

>>> cancel_orders(order_refs=['my-strategy'])

Cancel all open orders:

>>> cancel_orders(cancel_all=True)

quantrocket.blotter.download_order_statuses(filepath_or_buffer=None, output='csv', order_ids=None, sids=None, order_refs=None, accounts=None, open_orders=None, start_date=None, end_date=None, fields=None)¶

Download order statuses.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json or csv, default is csv)
order_ids (list of str, optional) – limit to these order IDs
sids (list of str, optional) – limit to orders for these sids
order_refs (list of str, optional) – limit to orders for these order refs
accounts (list of str, optional) – limit to orders for these accounts
open_orders (bool) – limit to open orders
start_date (str (YYYY-MM-DD), optional) – limit to orders submitted on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to orders submitted on or before this date
fields (list of str, optional) – return these fields in addition to the default fields (pass ‘?’ or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

Download order status by order ID and load into Pandas:

>>> f = io.StringIO()
>>> download_order_statuses(f, order_ids=['6001:45','6001:46'])
>>> order_statuses = pd.read_csv(f)

Download order status for all open orders and include extra fields in output:

>>> download_order_statuses(open_orders=True, fields=["LmtPrice", "OcaGroup"])

Download order status of open orders by sid:

>>> download_order_statuses(sids=["FIBBG123456"], open_orders=True)

Download order status of open orders by order ref:

>>> download_order_statuses(order_refs=['my-strategy'], open_orders=True)

quantrocket.blotter.download_positions(filepath_or_buffer=None, output='csv', order_refs=None, accounts=None, sids=None, view='blotter', diff=False)¶

Query current positions and write results to file.

To return positions as a Python list, see list_positions.

There are two ways to view positions: blotter view (default) and broker view.

The default “blotter view” returns positions by account, sid, and order ref. Positions are tracked based on execution records saved to the blotter database.

“Broker view” (view=’broker’) returns positions by account and sid (but not order ref) as reported directly by the broker.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json or csv, default is csv)
order_refs (list of str, optional) – limit to these order refs (not supported with broker view)
accounts (list of str, optional) – limit to these accounts
sids (list of str, optional) – limit to these sids
view (str, optional) – whether to return ‘broker’ view of positions (by account and sid) or default ‘blotter’ view (by account, sid, and order ref). Choices are: blotter, broker
diff (bool) – limit to positions where the blotter quantity and broker quantity disagree (requires view=’broker’)

Returns

Return type

None

See also

list_positions(): load positions into Python list

quantrocket.blotter.list_positions(order_refs=None, accounts=None, sids=None, view='blotter', diff=False)¶

Query current positions and return them as a Python list.

There are two ways to view positions: blotter view (default) and broker view.

The default “blotter view” returns positions by account, sid, and order ref. Positions are tracked based on execution records saved to the blotter database.

“Broker view” (view=’broker’) returns positions by account and sid (but not order ref) as reported directly by the broker.

Parameters

order_refs (list of str, optional) – limit to these order refs (not supported with broker view)
accounts (list of str, optional) – limit to these accounts
sids (list of str, optional) – limit to these sids
view (str, optional) – whether to return ‘broker’ view of positions (by account and sid) or default ‘blotter’ view (by account, sid, and order ref). Choices are: blotter, broker
diff (bool) – limit to positions where the blotter quantity and broker quantity disagree (requires view=’broker’)

Returns

Return type

list

Examples

Query current positions and load into Pandas:

>>> positions = list_positions()
>>> if positions:
>>>     positions = pd.DataFrame(positions)

quantrocket.blotter.close_positions(filepath_or_buffer=None, output='csv', order_refs=None, accounts=None, sids=None, params=None)¶

Generate orders to close positions.

Doesn’t actually place any orders but returns an orders file that can be placed separately. Additional order parameters can be appended with the params argument.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json or csv, default is csv)
order_refs (list of str, optional) – limit to these order refs
accounts (list of str, optional) – limit to these accounts
sids (list of str, optional) – limit to these sids
params (dict of PARAM:VALUE, optional) – additional parameters to append to each row in output (pass as {param:value}, for example {“OrderType”:”MKT”})

Returns

Return type

None

Examples

Get orders to close positions, then place the orders:

>>> from quantrocket.blotter import place_orders, close_positions
>>> import io
>>> orders_file = io.StringIO()
>>> close_positions(orders_file, params={"OrderType":"MKT", "Tif":"DAY", "Exchange":"SMART"})
>>> place_orders(infilepath_or_buffer=orders_file)

quantrocket.blotter.download_executions(filepath_or_buffer=None, order_refs=None, accounts=None, sids=None, start_date=None, end_date=None)¶

Query executions from the executions database.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
order_refs (list of str, optional) – limit to these order refs
accounts (list of str, optional) – limit to these accounts
sids (list of str, optional) – limit to these sids
start_date (str (YYYY-MM-DD), optional) – limit to executions on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to executions on or before this date

Returns

Return type

None

quantrocket.blotter.download_pnl(filepath_or_buffer=None, order_refs=None, accounts=None, sids=None, start_date=None, end_date=None, timezone=None, details=False, output='csv')¶

Query trading performance and return a CSV of results or PDF tearsheet.

Trading performance is broken down by account and order ref and optionally by sid.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
order_refs (list of str, optional) – limit to these order refs
accounts (list of str, optional) – limit to these accounts
sids (list of str, optional) – limit to these sids
start_date (str (YYYY-MM-DD), optional) – limit to pnl on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to pnl on or before this date
details (bool) – return detailed results for all securities instead of aggregating to account/order ref level (only supported for a single account and order ref at a time)
timezone (str, optional) – return execution times in this timezone (default UTC)
output (str, required) – the output format (choices are csv or pdf, default is csv)

Returns

Return type

None

quantrocket.blotter.read_pnl_csv(filepath_or_buffer)¶

Load a PNL CSV into a DataFrame.

This is a light wrapper around pd.read_csv that handles setting index columns and casting to proper data types.

Parameters: filepath_or_buffer (string or file-like, required) – path to CSV
Returns: a multi-index (Field, Date[, Time]) DataFrame of backtest results, with sids or strategy codes as columns
Return type: DataFrame

Examples

>>> results = read_pnl_csv("pnl.csv")
>>> returns = results.loc["Return"]

Blotter API

Resource Group ¶

Orders ¶

Place Orders
POST`/blotter/orders`

Place one or more orders from a CSV or JSON file. Returns a list of order IDs, which can be used to cancel the orders or check their status.

Example URI

POST http://houston/blotter/orders

Request

Headers

Content-Type: text/csv

Body

Sid,Account,Action,OrderRef,TotalQuantity,Exchange,OrderType,Tif
FI265598,DU123456,BUY,dma-tech,500,SMART,MKT,DAY
FI3691937,DU123456,BUY,dma-tech,50,SMART,MKT,DAY

Request

Headers

Content-Type: application/json

Body

[
  {
    "Sid": "FI265598",
    "Account": "DU123456",
    "Action": "BUY",
    "OrderRef": "dma-tech",
    "TotalQuantity": 500,
    "Exchange": "SMART",
    "OrderType": "MKT",
    "Tif": "DAY"
  },
  {
    "Sid": "FI3691937",
    "Account": "DU123456",
    "Action": "BUY",
    "OrderRef": "dma-tech",
    "TotalQuantity": 50,
    "Exchange": "SMART",
    "OrderType": "MKT",
    "Tif": "DAY"
  }
]

Response 200

Headers

Content-Type: application/json

Body

[
  "6001:25",
  "6001:26"
]

Get Order Status
GET`/blotter/orders{output}{?order_ids,sids,order_refs,accounts,open_orders,start_date,end_date,fields}`

Download order statuses.

Example URI

GET http://houston/blotter/orders.csv?order_ids=6001:25&sids=FI123456&order_refs=my-strategy&accounts=U12345&open_orders=true&start_date=2018-02-01&end_date=2018-03-01&fields=LmtPrice

URI Parameters

output

str (required) Example: .csv

output format

Choices: .csv .json

order_ids

str (optional) Example: 6001:25

limit to these order IDs (pass multiple times for multiple order IDs)

sids

str (optional) Example: FI123456

limit to orders for these sids (pass multiple times for multiple sids)

order_refs

str (optional) Example: my-strategy

limit to orders for these order refs (pass multiple times for multiple order refs)

accounts

str (optional) Example: U12345

limit to orders for these accounts (pass multiple times for multiple accounts)

open_orders

bool (optional) Example: true

limit to open orders

start_date

str (optional) Example: 2018-02-01

limit to orders submitted on or after this date

end_date

str (optional) Example: 2018-03-01

limit to orders submitted on or before this date

fields

str (optional) Example: LmtPrice

return these fields in addition to the default fields (pass ‘?’ or any invalid fieldname to see available fields) (pass multiple times for multiple fields)

Response 200

Headers

Content-Type: text/csv

Response 200

Headers

Content-Type: application/json

Cancel Orders
DELETE`/blotter/orders{?order_ids,sids,order_refs,accounts,cancel_all}`

Cancel one or more orders by order ID, sid, or order ref.

Example URI

DELETE http://houston/blotter/orders?order_ids=6001:25&sids=FI123456&order_refs=my-strategy&accounts=U12345&cancel_all=true

URI Parameters

order_ids: str (optional) Example: 6001:25
cancel these order IDs (pass multiple times for multiple order IDs)
sids: str (optional) Example: FI123456
cancel orders for these sids (pass multiple times for multiple sids)
order_refs: str (optional) Example: my-strategy
cancel orders for these order refs (pass multiple times for multiple order refs)
accounts: str (optional) Example: U12345
cancel orders for these accounts (pass multiple times for multiple accounts)
cancel_all: bool (optional) Example: true
cancel all open orders

Response 200

Headers

Content-Type: application/json

Body

{
    "order_ids": [
        "6001:25",
    ],
    "status": "the orders will be canceled asynchronously"
}

Positions ¶

Get Positions
GET`/blotter/positions.{output}{?sids,order_refs,accounts,view,diff}`

Query current positions and write results to file.

There are two ways to view positions: blotter view (default) and broker view.

The default “blotter view” returns positions by account, sid, and order ref. Positions are tracked based on execution records saved to the blotter database.

“Broker view” (view=‘broker’) returns positions by account and sid (but not order ref) as reported directly by the broker.

Example URI

GET http://houston/blotter/positions.csv?sids=FI123456&order_refs=my-strategy&accounts=U12345&view=blotter&diff=false

URI Parameters

output

str (required) Example: csv

output format

Choices: csv json

view

str (optional) Example: blotter

whether to return ‘broker’ view of positions (by account and sid) or default ‘blotter’ view (by account, sid, and order ref)

Choices: blotter broker

sids

str (optional) Example: FI123456

limit to these sids (pass multiple times for multiple sids)

order_refs

str (optional) Example: my-strategy

limit to these order refs (not supported with broker view) (pass multiple times for multiple order refs)

accounts

str (optional) Example: U12345

limit to these accounts (pass multiple times for multiple accounts)

diff

bool (optional) Example: false

limit to positions where the blotter quantity and broker quantity disagree (requires broker view)

Response 200

Headers

Content-Type: text/csv

Response 200

Headers

Content-Type: application/json

Close Positions
DELETE`/blotter/positions.{output}{?sids,order_refs,accounts,params}`

Generate orders to close positions. Doesn’t actually place any orders but returns an orders file that can be placed separately. Additional order parameters can be appended with the params argument.

Example URI

DELETE http://houston/blotter/positions.csv?sids=FI123456&order_refs=my-strategy&accounts=U12345&params=OrderType:MKT

URI Parameters

output

str (required) Example: csv

output format

Choices: csv json

sids

str (optional) Example: FI123456

limit to these sids (pass multiple times for multiple sids)

order_refs

str (optional) Example: my-strategy

limit to these order refs (pass multiple times for multiple order refs)

accounts

str (optional) Example: U12345

limit to these accounts (pass multiple times for multiple accounts)

params

str (optional) Example: OrderType:MKT

additional parameters to append to each row in output (pass as ‘param:value’) (pass multiple times for multiple params)

Response 200

Headers

Content-Type: text/csv

Response 200

Headers

Content-Type: application/json

Executions ¶

Get Executions
GET`/blotter/executions.{output}{?sids,order_refs,accounts,start_date,end_date}`

Query executions from the executions database.

Example URI

GET http://houston/blotter/executions.csv?sids=FI123456&order_refs=my-strategy&accounts=U12345&start_date=2018-02-01&end_date=2018-03-01

URI Parameters

output

str (required) Example: csv

output format

Choices: csv

sids

str (optional) Example: FI123456

limit to these sids (pass multiple times for multiple sids)

order_refs

str (optional) Example: my-strategy

limit to these order refs (pass multiple times for multiple order refs)

accounts

str (optional) Example: U12345

limit to these accounts (pass multiple times for multiple accounts)

start_date

str (optional) Example: 2018-02-01

limit to executions on or after this date

end_date

str (optional) Example: 2018-03-01

limit to executions on or before this date

Response 200

Headers

Content-Type: text/csv

PNL ¶

Get PNL
GET`/blotter/pnl.{output}{?sids,order_refs,accounts,start_date,end_date,timezone,details}`

Query trading performance and return a CSV of results or PDF tearsheet. Trading performance is broken down by account and order ref and optionally by sid.

Example URI

GET http://houston/blotter/pnl.csv?sids=FI123456&order_refs=my-strategy&accounts=U12345&start_date=2018-02-01&end_date=2018-03-01&timezone=America/New_York&details=true

URI Parameters

output

str (required) Example: csv

output format

Choices: csv pdf

sids

str (optional) Example: FI123456

limit to these sids (pass multiple times for multiple sids)

order_refs

str (optional) Example: my-strategy

limit to these order refs (pass multiple times for multiple order refs)

accounts

str (optional) Example: U12345

limit to these accounts (pass multiple times for multiple accounts)

start_date

str (optional) Example: 2018-02-01

limit to pnl on or after this date

end_date

str (optional) Example: 2018-03-01

limit to pnl on or before this date

timezone

str (optional) Example: America/New_York

return execution times in this timezone (default UTC)

details

bool (optional) Example: true

return detailed results for all securities instead of aggregating to account/order ref level (only supported for a single account and order ref at a time)

Response 200

Headers

Content-Type: text/csv

Response 200

Headers

Content-Type: application/pdf

quantrocket.codeload

code management service

QuantRocket code management CLI

usage: quantrocket codeload [-h] {clone} ...

subcommands¶

subcommand: Possible choices: clone

Sub-commands:¶

clone¶

clone files from a Git repository

quantrocket codeload clone [-h] [-b BRANCH] [-r | -s] repo

Positional Arguments¶

repo: the name or URL of the repo. Can be the name of a QuantRocket demo repo (e.g. ‘umd’), a GitHub username/repo (e.g. ‘myuser/myrepo’), or the URL of any Git repository

Named Arguments¶

-b, --branch

the branch to clone (default ‘master’)

-r, --replace

if a file already exists locally, replace it with the remote file (mutually exclusive with –skip-existing)

Default: False

-s, --skip-existing

if a file already exists locally, skip it (mutually exclusive with –replace)

Default: False

Clone files from a Git repository.

Only the files are copied, not the Git metadata. Can be run multiple times to clone files from multiple repositories. Won’t overwrite any existing files unless the –replace option is used.

Examples:

Clone QuantRocket’s “umd” demo repository:

quantrocket codeload clone umd

Clone a GitHub repo and skip files that already exist locally:

quantrocket codeload clone myuser/myrepo –skip-existing

Clone a Bitbucket repo:

quantrocket codeload clone https://bitbucket.org/myuser/myrepo.git

Clone a private GitHub repo by including authentication credentials in the URL (also works for Bitbucket):

quantrocket codeload clone https://myuser:mypassword@github.com/myuser/myrepo.git

quantrocket.codeload.clone(repo, branch=None, replace=None, skip_existing=None)¶

Clone files from a Git repository.

Only the files are copied, not the Git metadata. Can be run multiple times to clone files from multiple repositories. Won’t overwrite any existing files unless replace=True.

Parameters

repo (str, required) – the name or URL of the repo. Can be the name of a QuantRocket demo repo (e.g. ‘umd’), a GitHub username/repo (e.g. ‘myuser/myrepo’), or the URL of any Git repository
branch (str, optional) – the branch to clone (default ‘master’)
replace (bool, optional) – if a file already exists locally, replace it with the remote file (mutually exclusive with skip_existing)
skip_existing (bool, optional) – if a file already exists locally, skip it (mutually exclusive with replace)

Returns

status message

Return type

dict

Examples

Clone QuantRocket’s “umd” demo repository:

>>> clone("umd")

Clone a GitHub repo and skip files that already exist locally:

>>> clone("myuser/myrepo", skip_existing=True)

Clone a Bitbucket repo:

>>> clone("https://bitbucket.org/myuser/myrepo.git")

Clone a private GitHub repo by including authentication credentials in the URL (also works for Bitbucket):

>>> clone("https://myuser:mypassword@github.com/myuser/myrepo.git")

Codeload API

Resource Group ¶

Repo ¶

Clone Git Repo
POST`/repo{?repo,branch,replace,skip_existing}`

Clone files from a Git repository.

Only the files are copied, not the Git metadata. Can be run multiple times to clone files from multiple repositories. Won’t overwrite any existing files unless replace=True.

Example URI

POST http://houston/repo?repo=umd&branch=master&replace=true&skip_existing=false

URI Parameters

repo: str (required) Example: umd
the name or URL of the repo. Can be the name of a QuantRocket demo repo (e.g. ‘umd’), a GitHub username/repo (e.g. ‘myuser/myrepo’), or the URL of any Git repository
branch: str (optional) Example: master
the branch to clone (default ‘master’)
replace: bool (optional) Example: true
if a file already exists locally, replace it with the remote file (mutually exclusive with skip_existing)
skip_existing: bool (optional) Example: false
if a file already exists locally, skip it (mutually exclusive with replace)

Response 200

Headers

Content-Type: application/json

quantrocket.countdown

cron scheduler service

QuantRocket cron service CLI

usage: quantrocket countdown [-h] {crontab,timezone} ...

subcommands¶

subcommand: Possible choices: crontab, timezone

Sub-commands:¶

crontab¶

upload a new crontab, or return the current crontab

quantrocket countdown crontab [-h] [-s SERVICE_NAME] [FILENAME]

Positional Arguments¶

FILENAME: the crontab file to upload (if omitted, return the current crontab)

Named Arguments¶

-s, --service: the name of the countdown service (default ‘countdown’)

Upload a new crontab, or return the current crontab.

Examples:

Upload a new crontab to a service called countdown-australia (replaces current crontab):

quantrocket countdown crontab mycron.crontab -s countdown-australia

Show current crontab for a service called countdown-australia:

quantrocket countdown crontab -s countdown-australia

timezone¶

set or show the countdown service timezone

quantrocket countdown timezone [-h] [-s SERVICE_NAME] [TZ]

Positional Arguments¶

TZ: the timezone to set (pass a partial timezone string such as ‘newyork’ or ‘europe’ to see close matches, or pass ‘?’ to see all choices)

Named Arguments¶

-s, --service: the name of the countdown service, (default ‘countdown’)

Set or show the countdown service timezone.

Examples:

Set the timezone of the countdown service to America/New_York:

quantrocket countdown timezone America/New_York

Show the current timezone of the countdown service:

quantrocket countdown timezone

Show the timezone for a service called countdown-australia:

quantrocket countdown timezone -s countdown-australia

quantrocket.countdown.get_crontab(service=None)¶

Return the current crontab.

Parameters: service (str, optional) – the name of the countdown service (default ‘countdown’)
Returns: string representation of crontab
Return type: str

quantrocket.countdown.load_crontab(filename, service=None)¶

Upload a new crontab.

Parameters

filename (str, required) – the crontab file to upload to the countdown service
service (str, optional) – the name of the countdown service (default ‘countdown’)

Returns

status message

Return type

dict

quantrocket.countdown.get_timezone(service=None)¶

Return the service timezone.

Parameters: service (str, optional) – the name of the countdown service (default ‘countdown’)
Returns: dict with key timezone
Return type: dict

quantrocket.countdown.set_timezone(tz, service=None)¶

Set the countdown service timezone.

Parameters

tz (str, required) – the timezone to set (pass a partial timezone string such as ‘newyork’ or ‘europe’ to see close matches, or pass ‘?’ to see all choices)
service (str, optional) – the name of the countdown service (default ‘countdown’)

Returns

status message

Return type

dict

Examples

Set the countdown timezone to America/New_York:

>>> set_timezone("America/New_York")

Countdown API

Resource Group ¶

Crontab ¶

Get Crontab
GET`/{service}/crontab`

Returns the service crontab.

Example URI

GET http://houston/countdown-usa/crontab

URI Parameters

service: str (required) Example: countdown-usa
The name of the countdown-service, e.g. countdown-usa

Response 200

Headers

Content-Type: text/plain

Body

30 9 1-31 1-12 1-5 curl -X POST https://houston/api/endpoint1
30 17 1-31 1-12 1-5 curl -X POST https://houston/api/endpoint2

Load Crontab
PUT`/{service}/crontab`

Uploads a new crontab.

Example URI

PUT http://houston/countdown-usa/crontab

URI Parameters

service: str (required) Example: countdown-usa
The name of the countdown-service, e.g. countdown-usa

Request

Headers

Content-Type: text/plain

Body

30 9 1-31 1-12 1-5 curl -X POST https://houston/api/endpoint1
30 17 1-31 1-12 1-5 curl -X POST https://houston/api/endpoint2
0 12 1-31 1-12 1-7 curl -X POST https://houston/api/endpoint3

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the crontab will be loaded asynchronously"
}

Timezone ¶

Get Timezone
GET`/{service}/timezone`

Returns the service timezone.

Example URI

GET http://houston/countdown-usa/timezone

URI Parameters

service: str (required) Example: countdown-usa
The name of the countdown-service, e.g. countdown-usa

Response 200

Headers

Content-Type: application/json

Body

{
  "timezone": "America/New_York"
}

Set Timezone
PUT`/{service}/timezone{?tz}`

Sets the service timezone.

Example URI

PUT http://houston/countdown-usa/timezone?tz=America/New_York

URI Parameters

service: str (required) Example: countdown-usa
The name of the countdown-service, e.g. countdown-usa
tz: str (required) Example: America/New_York
The timezone to set.

Response 200

Headers

Content-Type: application/json

quantrocket.db

database management service

QuantRocket database service CLI

usage: quantrocket db [-h] {list,s3config,s3push,s3pull,optimize} ...

subcommands¶

subcommand: Possible choices: list, s3config, s3push, s3pull, optimize

Sub-commands:¶

list¶

list databases

quantrocket db list [-h] [-s [SERVICE [SERVICE ...]]]
                    [-c [DATABASE_CODE [DATABASE_CODE ...]]] [-d] [-e]

Named Arguments¶

-s, --services

limit to these services

-c, --codes

limit to these codes

-d, --detail

return database statistics (default is to return a flat list of database names)

Default: False

-e, --expand

expand sharded databases to include individual shards (default is to list sharded databases as a single database)

Default: False

List databases.

Examples:

List all databases:

quantrocket db list

List all history databases and include details such as file size:

quantrocket db list –services history –detail

List details for a sharded history database called usa-stk-15min and list each shard individually:

quantrocket db list –services history –codes usa-stk-15min –detail –expand

s3config¶

set or show Amazon S3 configuration for pushing and pulling databases to and from S3

quantrocket db s3config [-h] [-a ACCESS_KEY_ID] [-s SECRET_ACCESS_KEY]
                        [-b BUCKET]

Named Arguments¶

-a, --access-key-id: AWS access key ID
-s, --secret-access-key: AWS secret access key (if omitted and access-key-id is provided, will be prompted for secret-access-key)
-b, --bucket: the S3 bucket name to push to/pull from

Set or show Amazon S3 configuration for pushing and pulling databases to and from S3.

See http://qrok.it/h/dbs3 to learn more.

Credentials are encrypted at rest and never leave your deployment.

Examples:

Configure S3 (will prompt for secret access key):

quantrocket db s3config –access-key-id XXXXXXXX –bucket my-bucket

Preserve existing credentials but point to a new bucket:

quantrocket db s3config –bucket my-other-bucket

Show current configuration:

quantrocket db s3config

s3push¶

push database(s) to Amazon S3

quantrocket db s3push [-h] [-s [SERVICE [SERVICE ...]]]
                      [-c [DATABASE_CODE [DATABASE_CODE ...]]]

Named Arguments¶

-s, --services: limit to these services
-c, --codes: limit to these codes

Push database(s) to Amazon S3.

See http://qrok.it/h/dbs3 to learn more.

Examples:

Push all databases:

quantrocket db s3push

Push all databases for the history service:

quantrocket db s3push –services history

Push a database called quantrocket.history.nyse.sqlite:

quantrocket db s3push –services history –codes nyse

s3pull¶

pull database(s) from Amazon S3

quantrocket db s3pull [-h] [-s [SERVICE [SERVICE ...]]]
                      [-c [DATABASE_CODE [DATABASE_CODE ...]]] [-f]

Named Arguments¶

-s, --services

limit to these services

-c, --codes

limit to these codes

-f, --force

overwrite existing database if one exists (default is to fail if one exists)

Default: False

Pull database(s) from Amazon S3 to the db service.

See http://qrok.it/h/dbs3 to learn more.

Examples:

Pull a database stored on S3 as quantrocket.history.nyse.sqlite.gz:

quantrocket db s3pull –services history –codes nyse

optimize¶

optimize databases to improve performance

quantrocket db optimize [-h] [-s [SERVICE [SERVICE ...]]]
                        [-c [DATABASE_CODE [DATABASE_CODE ...]]]

Named Arguments¶

-s, --services: limit to these services
-c, --codes: limit to these codes

Optimize databases to improve performance.

This runs the ‘VACUUM’ command, which defragments the database and reclaims disk space.

Examples:

Optimize all blotter databases:

quantrocket db optimize –services blotter

quantrocket.db.list_databases(services=None, codes=None, detail=False, expand=False)¶

List databases.

Parameters

services (str, optional) – limit to these services
codes (list of str, optional) – limit to these codes
detail (bool) – return database statistics (default is to return a flat list of database names)
expand (bool) – expand sharded databases to include individual shards (default is to list sharded databases as a single database)

Returns

dict of lists of databases (one key for PostgreSQL databases and one for SQLite databases)

Return type

dict

Examples

Load database details in a pandas DataFrame:

>>> from quantrocket.db import list_databases
>>> import itertools
>>> databases = list_databases(detail=True)
>>> databases = pd.DataFrame.from_records(itertools.chain(databases["sqlite"], databases["postgres"]))

quantrocket.db.get_s3_config()¶

Return the current S3 configuration, if any.

See http://qrok.it/h/dbs3 to learn more.

Returns: configuration details
Return type: dict

quantrocket.db.set_s3_config(access_key_id=None, secret_access_key=None, bucket=None)¶

Set AWS S3 configuration for pushing and pulling databases to and from S3.

See http://qrok.it/h/dbs3 to learn more.

Credentials are encrypted at rest and never leave your deployment.

Parameters

access_key_id (str, optional) – AWS access key ID
secret_access_key (str, optional) – AWS secret access key (if omitted and access_key_id is provided, will be prompted for secret_access_key)
bucket (str, optional) – the S3 bucket name to push to/pull from

Returns

status message

Return type

dict

quantrocket.db.s3_push_databases(services=None, codes=None)¶

Push database(s) to Amazon S3.

See http://qrok.it/h/dbs3 to learn more.

Parameters

serivces (list of str, optional) – limit to these services
codes (list of str, optional) – limit to these codes

Returns

status message

Return type

json

quantrocket.db.s3_pull_databases(services=None, codes=None, force=False)¶

Pull database(s) from Amazon S3.

See http://qrok.it/h/dbs3 to learn more.

Parameters

serivces (list of str, optional) – limit to these services
codes (list of str, optional) – limit to these codes
force (bool) – overwrite existing database if one exists (default is to fail if one exists)

Returns

status message

Return type

json

quantrocket.db.optimize_databases(services=None, codes=None)¶

Optimize databases to improve performance.

This runs the ‘VACUUM’ command, which defragments the database and reclaims disk space.

Parameters

serivces (list of str, optional) – limit to these service
codes (list of str, optional) – limit to these codes

Returns

status message

Return type

json

DB API

Resource Group ¶

Database List ¶

List Databases
GET`/db/databases{?services,codes,detail,expand}`

List databases.

Example URI

GET http://houston/db/databases?services=history&codes=usa-stk-1min&detail=true&expand=true

URI Parameters

services: str (optional) Example: history
limit to these services (pass multiple times for multiple services)
codes: str (optional) Example: usa-stk-1min
limit to these codes (omit to list all databases for service) (pass multiple times for multiple codes)
detail: bool (optional) Example: true
return database statistics (default is to return a flat list of database names). Currently only supported for SQLite databases.
expand: bool (optional) Example: true
expand sharded databases to include individual shards (default is to list sharded databases as a single database)

Response 200

Headers

Content-Type: application/json

Body

{
    "sqlite": [
        "quantrocket.history.canada.sqlite",
        "quantrocket.history.australia_eod.sqlite",
    ],
    "postgres": []
}

S3 Config ¶

Set S3 configuration
PUT`/s3config{?access_key_id,secret_access_key,bucket}`

Set AWS S3 configuration for pushing and pulling databases to and from S3.

See http://qrok.it/h/dbs3 to learn more.

Credentials are encrypted at rest and never leave your deployment.

Example URI

PUT http://houston/s3config?access_key_id=XXXXXXXXX&secret_access_key=XXXXXXXXX&bucket=mybucket

URI Parameters

access_key_id: str (optional) Example: XXXXXXXXX
AWS access key ID
secret_access_key: str (optional) Example: XXXXXXXXX
AWS secret access key
bucket: str (optional) Example: mybucket
the S3 bucket name to push to/pull from

Response 200

Headers

Content-Type: application/json

Get S3 configuration
GET`/s3config`

Return the current S3 configuration, if any.

Example URI

GET http://houston/s3config

Response 200

Headers

Content-Type: application/json

Body

{
    "AWS_ACCESS_KEY_ID": "XXXXXXXXX",
    "S3_BUCKET": "mybucket",
}

S3 ¶

Pull from S3
GET`/db/s3{?services,codes,force}`

Pull database(s) from Amazon S3.

Example URI

GET http://houston/db/s3?services=history&codes=canada&force=true

URI Parameters

services: str (required) Example: history
limit to these services (pass multiple times for multiple services)
codes: str (optional) Example: canada
limit to these codes (pass multiple times for multiple codes)
force: bool (optional) Example: true
overwrite existing database if one exists (default is to fail if one exists)

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the databases will be pulled from S3 asynchronously"
}

Push to S3
PUT`/db/s3{?services,codes}`

Push database(s) to Amazon S3.

Example URI

PUT http://houston/db/s3?services=history&codes=canada

URI Parameters

services: str (required) Example: history
limit to these services (pass multiple times for multiple services)
codes: str (optional) Example: canada
limit to these codes (pass multiple times for multiple codes)

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the databases will be pushed to S3 asynchronously"
}

Optimizations ¶

Optimize Databases
POST`/db/optimizations{?services,codes}`

Optimize database file(s) to improve performance.

Example URI

POST http://houston/db/optimizations?services=history&codes=canada

URI Parameters

services: str (required) Example: history
limit to these services (pass multiple times for multiple services)
codes: str (optional) Example: canada
limit to these codes (pass multiple times for multiple codes)

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the databases will be optimized asynchronously"
}

quantrocket.flightlog

logging service

QuantRocket logging service CLI

usage: quantrocket flightlog [-h] {stream,get,log,timezone,papertrail} ...

subcommands¶

subcommand: Possible choices: stream, get, log, timezone, papertrail

Sub-commands:¶

stream¶

stream application logs, tail -f style

quantrocket flightlog stream [-h] [-d] [--hist NUM_LINES] [--nocolor]

Named Arguments¶

-d, --detail

show detailed logs from logspout, otherwise show log messages from flightlog only

Default: False

--hist

number of log lines to show right away (ignored if showing detailed logs)

--nocolor

don’t colorize the logs

Default: True

Stream application logs, tail -f style.

Examples:

Stream application logs:

quantrocket flightlog stream

Stream detailed logs:

quantrocket flightlog stream –detail

get¶

download the logfile

quantrocket flightlog get [-h] [-d] [-m PATTERN] OUTFILE

Positional Arguments¶

OUTFILE: filename to write the logfile to

Named Arguments¶

-d, --detail

download detailed logs from logspout, otherwise download log messages from flightlog only

Default: False

-m, --match

filter the logfile to lines containing this string

Download the logfile.

Examples:

Download application logs:

quantrocket flightlog get app.log

Download detailed logs:

quantrocket flightlog get –detail sys.log

Download detailed logs for the history service:

quantrocket flightlog get –detail –match quantrocket_history sys.log

log¶

log a message

quantrocket flightlog log [-h] [-l LEVEL] [-n LOGGER_NAME] [msg]

Positional Arguments¶

msg

the message to be logged

Default: “-“

Named Arguments¶

-l, --level

Possible choices: DEBUG, INFO, WARNING, ERROR, CRITICAL

the log level for the message. Possible choices: (‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’)

Default: “INFO”

-n, --name

the logger name

Default: “quantrocket.cli”

Log a message.

Examples:

Log a message under the name “myapp”:

quantrocket flightlog log “this is a test” –name myapp –level INFO

Log the output from another command:

quantrocket account balance –below-cushion 0.02 | quantrocket flightlog log –name quantrocket.account –level CRITICAL

timezone¶

set or show the flightlog timezone

quantrocket flightlog timezone [-h] [TZ]

Positional Arguments¶

TZ: the timezone to set (pass a partial timezone string such as ‘newyork’ or ‘europe’ to see close matches, or pass ‘?’ to see all choices)

Set or show the flightlog timezone.

Examples:

Set the flightlog timezone to America/New_York:

quantrocket flightlog timezone America/New_York

Show the current flightlog timezone:

quantrocket flightlog timezone

papertrail¶

set or show the Papertrail log configuration

quantrocket flightlog papertrail [-h] [--host HOST] [--port PORT]

Named Arguments¶

--host: the Papertrail host to log to
--port: the Papertrail port to log to

Set or show the Papertrail log configuration.

See http://qrok.it/h/pt to learn more.

Examples:

Set the Papertrail host and port to log to:

quantrocket flightlog papertrail –host logs.papertrailapp.com –port 55555

Show the current papertrail config:

quantrocket flightlog papertrail

quantrocket.flightlog.FlightlogHandler(background=None)¶

Returns a log handler that logs to flightlog.

Parameters: background (bool) – If True, causes logging to happen in a background thread so that logging doesn’t block. Background logging requires Python 3.2 or higher, and defaults to True for supported versions and False otherwise.
Returns
Return type: logging.handlers.QueueHandler or quantrocket.flightlog._ImpatientHttpHandler

Examples

Log a message using the FlightlogHandler:

>>> import logging
>>> from quantrocket.flightlog import FlightlogHandler
>>> logger = logging.getLogger('myapp')
>>> logger.setLevel(logging.DEBUG)
>>> handler = FlightlogHandler()
>>> logger.addHandler(handler)
>>> logger.info('my app just opened a position')

quantrocket.flightlog.stream_logs(detail=False, hist=None, color=True)¶

Stream application logs, tail -f style.

Parameters

detail (bool) – if True, show detailed logs from logspout, otherwise show log messages from flightlog only (default False)
hist (int, optional) – number of log lines to show right away (ignored if showing detailed logs)
color (bool) – colorize the logs

Yields

str – each log line as it arrives

quantrocket.flightlog.download_logfile(outfile, detail=False, match=None)¶

Download the logfile.

Parameters

outfile (str or file-like object, required) – filename or file object to write the logfile to
detail (bool) – if True, show detailed logs from logspout, otherwise show log messages from flightlog only (default False)
match (str, optional) – filter the logfile to lines containing this string

Returns

Return type

None

quantrocket.flightlog.get_timezone()¶

Return the flightlog timezone.

Returns: dict with key timezone
Return type: dict

quantrocket.flightlog.set_timezone(tz)¶

Set the flightlog timezone.

Parameters: tz (str, required) – the timezone to set (pass a partial timezone string such as ‘newyork’ or ‘europe’ to see close matches, or pass ‘?’ to see all choices)
Returns: status message
Return type: dict

Examples

Set the flightlog timezone to America/New_York:

>>> set_timezone("America/New_York")

quantrocket.flightlog.get_papertrail_config()¶

Return the current Papertrail log configuration, if any.

See http://qrok.it/h/pt to learn more.

Returns: config details
Return type: dict

quantrocket.flightlog.set_papertrail_config(host, port)¶

Set the Papertrail log configuration.

See http://qrok.it/h/pt to learn more.

Parameters

host (str, required) – the Papertrail host to log to
port (int, required) – the Papertrail port to log to

Returns

status message

Return type

dict

Examples

Configure flightlog to log to Papertrail:

>>> set_papertrail_config("logs.papertrailapp.com", 55555)

Flightlog API

Resource Group ¶

Logfiles ¶

Download log files
GET`/flightlog/logfile/{logtype}{?match}`

Download the logfile.

Example URI

GET http://houston/flightlog/logfile/app?match=history

URI Parameters

logtype

str (required) Example: app

the type of logfile to download

Choices: app system

match

str (optional) Example: history

filter the logfile to lines containing this string

Response 200

Headers

Content-Type: text/plain

Body

2017-01-18 10:19:31 quantrocket.flightlog: INFO Detected a change in flightlog configs directory, reloading configs...
2017-01-18 10:19:31 quantrocket.flightlog: INFO Successfully loaded config
2017-01-18 14:25:57 quantrocket.master: INFO Requesting contract details for error 200 symbols

Log Stream ¶

Stream logs
GET`/flightlog/stream/logs{?hist,nocolor}`

Stream application logs, tail -f style.

Example URI

GET http://houston/flightlog/stream/logs?hist=5&nocolor=

URI Parameters

hist: int (optional) Example: 5
number of log lines to show right away
nocolor: str (optional)
don’t colorize the logs if nocolor parameter is passed (parameter value doesn’t matter)

Response 200

Headers

Content-Type: text/plain
Transfer-Encoding: chunked

Body

2017-01-18 10:19:31 quantrocket.flightlog: INFO Detected a change in flightlog configs directory, reloading configs...
2017-01-18 10:19:31 quantrocket.flightlog: INFO Successfully loaded config
2017-01-18 14:25:57 quantrocket.master: INFO Requesting contract details for error 200 symbols

Logspout Stream ¶

Stream logspout
GET`/logspout/logs{?colors}`

Stream detailed logs from logspout, tail -f style.

Example URI

GET http://houston/logspout/logs?colors=off

URI Parameters

colors: str (optional) Example: off
don’t colorize the logs if colors=off (colorized by default)

Response 200

Headers

Content-Type: text/plain
Transfer-Encoding: chunked

Body

quantrocket_houston_1|172.21.0.1 - - [18/Jan/2017:10:14:48 +0000] "POST /flightlog/handler HTTP/1.1" 200 5 "-" "-"
2017-01-18 10:19:31 quantrocket.flightlog: INFO Detected a change in flightlog configs directory, reloading configs...
2017-01-18 10:19:31 quantrocket.flightlog: INFO Successfully loaded config
2017-01-18 14:25:57 quantrocket.master: INFO Requesting contract details for error 200 symbols
test_houston_1|2017/01/18 20:59:01 [error] 5#5: *17137 open() "/usr/local/openresty/nginx/html/invalidpath" failed (2: No such file or directory), client: 172.20.0.8, server: localhost, request: "GET /invalidpath HTTP/1.1", host: "houston"

Timezone ¶

Get Timezone
GET`/timezone`

Returns the flightlog timezone.

Example URI

GET http://houston/timezone

Response 200

Headers

Content-Type: application/json

Body

{
  "timezone": "America/New_York"
}

Set Timezone
PUT`/timezone{?tz}`

Sets the timezone.

Example URI

PUT http://houston/timezone?tz=America/New_York

URI Parameters

tz: str (required) Example: America/New_York
The timezone to set.

Response 200

Headers

Content-Type: application/json

Papertrail ¶

Get Papertrail configuration
GET`/papertrail`

Return the current Papertrail log configuration, if any.

Example URI

GET http://houston/papertrail

Response 200

Headers

Content-Type: application/json

Body

{
    "PAPERTRAIL_HOST": "logs.papertrailapp.com",
    "PAPERTRAIL_PORT": 55555,
}

Set Papertrail configuration
PUT`/papertrail{?host,port}`

Set the Papertrail log configuration.

Example URI

PUT http://houston/papertrail?host=logs.papertrailapp.com&port=55555

URI Parameters

host: str (required) Example: logs.papertrailapp.com
the Papertrail host to log to
port: int (required) Example: 55555
the Papertrail port to log to

Response 200

Headers

Content-Type: application/json

quantrocket.fundamental

fundamental data service

QuantRocket fundamental data CLI

usage: quantrocket fundamental [-h]
                               {collect-sharadar-fundamentals,collect-sharadar-insiders,collect-sharadar-institutions,collect-sharadar-sec8,collect-sharadar-sp500,collect-reuters-financials,collect-reuters-estimates,collect-wsh,collect-ibkr-shortshares,collect-ibkr-borrowfees,collect-alpaca-etb,sharadar-fundamentals,sharadar-insiders,sharadar-institutions,sharadar-sec8,sharadar-sp500,reuters-codes,reuters-financials,reuters-estimates,wsh,ibkr-shortshares,ibkr-borrowfees,alpaca-etb}
                               ...

subcommands¶

subcommand: Possible choices: collect-sharadar-fundamentals, collect-sharadar-insiders, collect-sharadar-institutions, collect-sharadar-sec8, collect-sharadar-sp500, collect-reuters-financials, collect-reuters-estimates, collect-wsh, collect-ibkr-shortshares, collect-ibkr-borrowfees, collect-alpaca-etb, sharadar-fundamentals, sharadar-insiders, sharadar-institutions, sharadar-sec8, sharadar-sp500, reuters-codes, reuters-financials, reuters-estimates, wsh, ibkr-shortshares, ibkr-borrowfees, alpaca-etb

Sub-commands:¶

collect-sharadar-fundamentals¶

collect fundamental data from Sharadar and save to database

quantrocket fundamental collect-sharadar-fundamentals [-h] [-c COUNTRY]

Named Arguments¶

-c, --country

Possible choices: US, FREE

country to collect fundamentals for. Possible choices: [‘US’, ‘FREE’]

Default: “US”

Collect fundamental data from Sharadar and save to database.

Examples:

quantrocket fundamental collect-sharadar-fundamentals

collect-sharadar-insiders¶

collect insider holdings data from Sharadar and save to database

quantrocket fundamental collect-sharadar-insiders [-h] [-c COUNTRY]

Named Arguments¶

-c, --country

Possible choices: US, FREE

country to collect insider holdings data for. Possible choices: [‘US’, ‘FREE’]

Default: “US”

Collect insider holdings data from Sharadar and save to database.

Examples:

quantrocket fundamental collect-sharadar-insiders

collect-sharadar-institutions¶

collect institutional investor data from Sharadar and save to database

quantrocket fundamental collect-sharadar-institutions [-h] [-c COUNTRY] [-d]

Named Arguments¶

-c, --country

Possible choices: US, FREE

country to collect institutional investor data for. Possible choices: [‘US’, ‘FREE’]

Default: “US”

-d, --detail

collect detailed investor data (separate record per investor per security per quarter). If omitted, collect data aggregated by security (separate record per security per quarter)

Default: False

Collect institutional investor data from Sharadar and save to database.

Examples:

Collect institutional investor data aggregated by security:

quantrocket fundamental collect-sharadar-institutions

Collect detailed institutional investor data (not aggregated by security):

quantrocket fundamental collect-sharadar-institutions -d

collect-sharadar-sec8¶

collect SEC Form 8-K events from Sharadar and save to database

quantrocket fundamental collect-sharadar-sec8 [-h] [-c COUNTRY]

Named Arguments¶

-c, --country

Possible choices: US, FREE

country to collect events data for. Possible choices: [‘US’, ‘FREE’]

Default: “US”

Collect SEC Form 8-K events from Sharadar and save to database.

Examples:

quantrocket fundamental collect-sharadar-sec8

collect-sharadar-sp500¶

collect historical S&P 500 index constituents from Sharadar and save to database

quantrocket fundamental collect-sharadar-sp500 [-h] [-c COUNTRY]

Named Arguments¶

-c, --country

Possible choices: US, FREE

country to collect S&P 500 constituents data for. Possible choices: [‘US’, ‘FREE’]

Default: “US”

Collect historical S&P 500 index constituents from Sharadar and save to database.

Examples:

quantrocket fundamental collect-sharadar-sp500

collect-reuters-financials¶

collect Reuters financial statements from Interactive Brokers and save to database

quantrocket fundamental collect-reuters-financials [-h]
                                                   [-u [UNIVERSE [UNIVERSE ...]]]
                                                   [-i [SID [SID ...]]] [-f]

Named Arguments¶

-u, --universes

limit to these universes (must provide universes, sids, or both)

-i, --sids

limit to these sids (must provide universes, sids, or both)

-f, --force

collect financials for all securities even if they were collected recently (default is to skip securities that were updated in the last 12 hours)

Default: False

Collect Reuters financial statements from Interactive Brokers and save to database.

This data provides cash flow, balance sheet, and income metrics.

Examples:

Collect Reuters financial statements for a universe of Japanese banks:

quantrocket fundamental collect-reuters-financials –universes ‘japan-bank’

Collect Reuters financial statements for a particular security:

quantrocket fundamental collect-reuters-financials –sids FIBBG123456

collect-reuters-estimates¶

collect Reuters estimates and actuals from Interactive Brokers and save to database

quantrocket fundamental collect-reuters-estimates [-h]
                                                  [-u [UNIVERSE [UNIVERSE ...]]]
                                                  [-i [SID [SID ...]]] [-f]

Named Arguments¶

-u, --universes

limit to these universes (must provide universes, sids, or both)

-i, --sids

limit to these sids (must provide universes, sids, or both)

-f, --force

collect estimates for all securities even if they were collected recently (default is to skip securities that were updated in the last 12 hours)

Default: False

Collect Reuters estimates and actuals from Interactive Brokers and save to database.

This data provides analyst estimates and actuals for a variety of indicators.

Examples:

Collect Reuters estimates and actuals for a universe of Japanese banks:

quantrocket fundamental collect-reuters-estimates –universes ‘japan-bank’

Collect Reuters estimates and actuals for a particular security:

quantrocket fundamental collect-reuters-estimates –sids FIBBG123456

collect-wsh¶

collect Wall Street Horizon upcoming earnings announcement dates from Interactive Brokers and save to database

quantrocket fundamental collect-wsh [-h] [-u [UNIVERSE [UNIVERSE ...]]]
                                    [-i [SID [SID ...]]] [-f]

Named Arguments¶

-u, --universes

limit to these universes (must provide universes, sids, or both)

-i, --sids

limit to these sids (must provide universes, sids, or both)

-f, --force

collect earnings dates for all securities even if they were collected recently (default is to skip securities that were updated in the last 12 hours)

Default: False

Collect Wall Street Horizon upcoming earnings announcement dates from Interactive Brokers and save to database.

Examples:

Collect upcoming earnings dates for a universe of US stocks:

quantrocket fundamental collect-wsh –universes ‘usa-stk’

Collect upcoming earnings dates for a particular security:

quantrocket fundamental collect-wsh –sids FIBBG123456

collect-ibkr-shortshares¶

collect Interactive Brokers shortable shares data and save to database

quantrocket fundamental collect-ibkr-shortshares [-h]
                                                 [-c [COUNTRY [COUNTRY ...]]]

Named Arguments¶

-c, --countries: limit to these countries (pass ‘?’ or any invalid country to see available countries)

Collect Interactive Brokers shortable shares data and save to database.

Data is organized by country and updated every 15 minutes. Historical data is available from April 15, 2018.

Examples:

Collect shortable shares data for US stocks:

quantrocket fundamental collect-ibkr-shortshares –countries usa

Collect shortable shares data for all stocks:

quantrocket fundamental collect-ibkr-shortshares

collect-ibkr-borrowfees¶

collect Interactive Brokers borrow fees data and save to database

quantrocket fundamental collect-ibkr-borrowfees [-h]
                                                [-c [COUNTRY [COUNTRY ...]]]

Named Arguments¶

-c, --countries: limit to these countries (pass ‘?’ or any invalid country to see available countries)

Collect Interactive Brokers borrow fees data and save to database.

Data is organized by country and updated every 15 minutes. Historical data is available from April 15, 2018.

Examples:

Collect borrow fees for US stocks:

quantrocket fundamental collect-ibkr-borrowfees –countries usa

Collect borrow fees for all stocks:

quantrocket fundamental collect-ibkr-borrowfees

collect-alpaca-etb¶

collect Alpaca easy-to-borrow data and save to database

quantrocket fundamental collect-alpaca-etb [-h]

Collect Alpaca easy-to-borrow data and save to database.

Data is updated daily. Historical data is available from March 2019.

Examples:

Collect easy-to-borrow data:

quantrocket fundamental collect-alpaca-etb

sharadar-fundamentals¶

query Sharadar Fundamentals from the local database and download to file

quantrocket fundamental sharadar-fundamentals [-h] [-s YYYY-MM-DD]
                                              [-e YYYY-MM-DD]
                                              [-u [UNIVERSE [UNIVERSE ...]]]
                                              [-i [SID [SID ...]]]
                                              [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                                              [--exclude-sids [SID [SID ...]]]
                                              [-m [{ARQ,ARY,ART,MRQ,MRY,MRT} [{ARQ,ARY,ART,MRQ,MRY,MRT} ...]]]
                                              [-o OUTFILE] [-j]
                                              [-f [FIELD [FIELD ...]]]

filtering options¶

-s, --start-date

limit to fundamentals on or after this fiscal period end date

-e, --end-date

limit to fundamentals on or before this fiscal period end date

-u, --universes

limit to these universes

-i, --sids

limit to these sids

--exclude-universes

exclude these universes

--exclude-sids

exclude these sids

-m, --dimensions

Possible choices: ARQ, ARY, ART, MRQ, MRY, MRT

limit to these dimensions. Possible choices: [‘ARQ’, ‘ARY’, ‘ART’, ‘MRQ’, ‘MRY’, ‘MRT’]. AR=As Reported, MR=Most Recent Reported, Q=Quarterly, Y=Annual, T=Trailing Twelve Month.

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)
-f, --fields: only return these fields (pass ‘?’ or any invalid fieldname to see available fields))

Query Sharadar Fundamentals from the local database and download to file.

Examples:

Query as-reported trailing twelve month (ART) fundamentals for all indicators for a particular sid:

quantrocket fundamental sharadar-fundamentals -i FIBBG12345 –dimensions ART -o aapl_fundamentals.csv

Query as-reported quarterly (ARQ) fundamentals for select indicators for a universe:

quantrocket fundamental sharadar-fundamentals -u usa-stk –dimensions ARQ -f REVENUE EPS -o sharadar_fundamentals.csv

sharadar-insiders¶

query Sharadar insider holdings data from the local database and download to file

quantrocket fundamental sharadar-insiders [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                                          [-u [UNIVERSE [UNIVERSE ...]]]
                                          [-i [SID [SID ...]]]
                                          [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                                          [--exclude-sids [SID [SID ...]]]
                                          [-o OUTFILE] [-j]
                                          [-f [FIELD [FIELD ...]]]

filtering options¶

-s, --start-date: limit to data on or after this filing date
-e, --end-date: limit to data on or before this filing date
-u, --universes: limit to these universes
-i, --sids: limit to these sids
--exclude-universes: exclude these universes
--exclude-sids: exclude these sids

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)
-f, --fields: only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Query Sharadar insider holdings data from the local database and download to file.

Examples:

Query insider holdings data for a particular sid:

quantrocket fundamental sharadar-insiders -i FIBBG000B9XRY4 -o aapl_insiders.csv

sharadar-institutions¶

query Sharadar institutional investor data from the local database and download to file

quantrocket fundamental sharadar-institutions [-h] [-s YYYY-MM-DD]
                                              [-e YYYY-MM-DD]
                                              [-u [UNIVERSE [UNIVERSE ...]]]
                                              [-i [SID [SID ...]]]
                                              [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                                              [--exclude-sids [SID [SID ...]]]
                                              [-o OUTFILE] [-j]
                                              [-f [FIELD [FIELD ...]]] [-d]

filtering options¶

-s, --start-date: limit to data on or after this quarter end date
-e, --end-date: limit to data on or before this quarter end date
-u, --universes: limit to these universes
-i, --sids: limit to these sids
--exclude-universes: exclude these universes
--exclude-sids: exclude these sids

output options¶

-o, --outfile

filename to write the data to (default is stdout)

-j, --json

format output as JSON (default is CSV)

-f, --fields

only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

-d, --detail

query detailed investor data (separate record per investor per security per quarter). If omitted, query data aggregated by security (separate record per security per quarter)

Default: False

Query Sharadar institutional investor data from the local database and download to file.

Examples:

Query institutional investor data aggregated by security:

quantrocket fundamental sharadar-institutions -u usa-stk -s 2019-01-01 -o institutions.csv

sharadar-sec8¶

query Sharadar SEC Form 8-K events data from the local database and download to file

quantrocket fundamental sharadar-sec8 [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                                      [-u [UNIVERSE [UNIVERSE ...]]]
                                      [-i [SID [SID ...]]]
                                      [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                                      [--exclude-sids [SID [SID ...]]]
                                      [-c [INT [INT ...]]] [-o OUTFILE] [-j]
                                      [-f [FIELD [FIELD ...]]]

filtering options¶

-s, --start-date: limit to data on or after this filing date
-e, --end-date: limit to data on or before this filing date
-u, --universes: limit to these universes
-i, --sids: limit to these sids
--exclude-universes: exclude these universes
--exclude-sids: exclude these sids
-c, --event-codes: limit to these event codes

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)
-f, --fields: only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Query Sharadar SEC Form 8-K events data from the local database and download to file.

Examples:

Query event code 13 (Bankruptcy) for a universe of securities:

quantrocket fundamental sharadar-sec8 -u usa-stk –event-codes 13 -o bankruptcies.csv

sharadar-sp500¶

query Sharadar S&P 500 index changes (additions and removals) from the local database and download to file

quantrocket fundamental sharadar-sp500 [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                                       [-u [UNIVERSE [UNIVERSE ...]]]
                                       [-i [SID [SID ...]]]
                                       [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                                       [--exclude-sids [SID [SID ...]]]
                                       [-o OUTFILE] [-j]
                                       [-f [FIELD [FIELD ...]]]

filtering options¶

-s, --start-date: limit to index changes on or after this date
-e, --end-date: limit to index changes on or before this date
-u, --universes: limit to these universes
-i, --sids: limit to these sids
--exclude-universes: exclude these universes
--exclude-sids: exclude these sids

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)
-f, --fields: only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Query Sharadar S&P 500 index changes (additions and removals) from the local database and download to file.

Examples:

Query S&P 500 index changes since 2010:

quantrocket fundamental sharadar-sp500 -s 2010-01-01 -o sp500_changes.csv

reuters-codes¶

list available Chart of Account (COA) codes from the Reuters financials database and/or indicator codes from the Reuters estimates/actuals database

quantrocket fundamental reuters-codes [-h] [-c [CODE [CODE ...]]]
                                      [-r [REPORT_TYPE [REPORT_TYPE ...]]]
                                      [-s [STATEMENT_TYPE [STATEMENT_TYPE ...]]]

Named Arguments¶

-c, --codes

limit to these Chart of Account (COA) or indicator codes

-r, --report-types

Possible choices: financials, estimates

limit to these report types. Possible choices: [‘financials’, ‘estimates’]

-s, --statement-types

Possible choices: INC, BAL, CAS

limit to these statement types. Only applies to financials, not estimates. Possible choices: [‘INC’, ‘BAL’, ‘CAS’]

List available Chart of Account (COA) codes from the Reuters financials database and/or indicator codes from the Reuters estimates/actuals database

Note: you must collect Reuters financials into the database before you can list COA codes.

Examples:

List all codes:

quantrocket fundamental reuters-codes

List COA codes for balance sheets only:

quantrocket fundamental reuters-codes –report-types financials –statement-types BAL

List the description of a specific COA code:

quantrocket fundamental reuters-codes –codes TIAT

reuters-financials¶

query financial statements from the Reuters financials database and download to file

quantrocket fundamental reuters-financials [-h] [-s YYYY-MM-DD]
                                           [-e YYYY-MM-DD]
                                           [-u [UNIVERSE [UNIVERSE ...]]]
                                           [-i [SID [SID ...]]]
                                           [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                                           [--exclude-sids [SID [SID ...]]]
                                           [-q] [-r] [-o OUTFILE] [-j]
                                           [-f [FIELD [FIELD ...]]]
                                           CODE [CODE ...]

Positional Arguments¶

CODE: the Chart of Account (COA) code(s) to query

filtering options¶

-s, --start-date

limit to statements on or after this fiscal period end date

-e, --end-date

limit to statements on or before this fiscal period end date

-u, --universes

limit to these universes

-i, --sids

limit to these sids

--exclude-universes

exclude these universes

--exclude-sids

exclude these sids

-q, --interim

return interim reports (default is to return annual reports, which provide deeper history)

Default: False

-r, --exclude-restatements

exclude restatements (default is to include them)

Default: False

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)
-f, --fields: only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Query financial statements from the Reuters financials database and download to file.

You can query one or more COA codes. Run quantrocket fundamental reuters-codes to see available codes.

Annual or interim reports are available. Annual is the default and provides deeper history.

Examples:

Query total revenue (COA code RTLR) for a universe of Australian stocks:

quantrocket fundamental reuters-financials RTLR -u asx-stk -s 2014-01-01 -e 2017-01-01 -o rtlr.csv

Query net income (COA code NINC) from interim reports for two securities (identified by sid) and exclude restatements:

quantrocket fundamental reuters-financials NINC -i FIBBG123456 FIBBG234567 –interim –exclude-restatements -o ninc.csv

Query common and preferred shares outstanding (COA codes QTCO and QTPO) and return a minimal set of fields (several required fields will always be returned)

quantrocket fundamental reuters-financials QTCO QTPO -u nyse-stk –fields Amount -o nyse_float.csv

reuters-estimates¶

query estimates and actuals from the Reuters estimates database and download to file

quantrocket fundamental reuters-estimates [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                                          [-u [UNIVERSE [UNIVERSE ...]]]
                                          [-i [SID [SID ...]]]
                                          [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                                          [--exclude-sids [SID [SID ...]]]
                                          [-t [PERIOD_TYPE [PERIOD_TYPE ...]]]
                                          [-o OUTFILE] [-j]
                                          [-f [FIELD [FIELD ...]]]
                                          CODE [CODE ...]

Positional Arguments¶

CODE: the indicator code(s) to query

filtering options¶

-s, --start-date

limit to estimates and actuals on or after this fiscal period end date

-e, --end-date

limit to estimates and actuals on or before this fiscal period end date

-u, --universes

limit to these universes

-i, --sids

limit to these sids

--exclude-universes

exclude these universes

--exclude-sids

exclude these sids

-t, --period-types

Possible choices: A, Q, S

limit to these fiscal period types. Possible choices: [‘A’, ‘Q’, ‘S’], where A=Annual, Q=Quarterly, S=Semi-Annual

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)
-f, --fields: only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Query estimates and actuals from the Reuters estimates database and download to file.

You can query one or more indicator codes. Run quantrocket fundamental reuters-codes to see available codes.

Examples:

Query EPS estimates and actuals for a universe of Australian stocks:

quantrocket fundamental reuters-estimates EPS -u asx-stk -s 2014-01-01 -e 2017-01-01 -o eps_estimates.csv

wsh¶

query earnings announcement dates from the Wall Street Horizon announcements database and download to file

quantrocket fundamental wsh [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                            [-u [UNIVERSE [UNIVERSE ...]]]
                            [-i [SID [SID ...]]]
                            [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                            [--exclude-sids [SID [SID ...]]]
                            [-t [STATUS [STATUS ...]]] [-o OUTFILE] [-j]
                            [-f [FIELD [FIELD ...]]]

filtering options¶

-s, --start-date

limit to announcements on or after this date

-e, --end-date

limit to announcements on or before this date

-u, --universes

limit to these universes

-i, --sids

limit to these sids

--exclude-universes

exclude these universes

--exclude-sids

exclude these sids

-t, --statuses

Possible choices: Confirmed, Unconfirmed

limit to these confirmation statuses. Possible choices: [‘Confirmed’, ‘Unconfirmed’]

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)
-f, --fields: only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Query earnings announcement dates from the Wall Street Horizon announcements database and download to file.

Examples:

Query earnings dates for a universe of US stocks:

quantrocket fundamental wsh -u usa-stk -s 2019-01-01 -e 2019-04-01 -o announcements.csv

ibkr-shortshares¶

query Interactive Brokers shortable shares from the local database and download to file

quantrocket fundamental ibkr-shortshares [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                                         [-u [UNIVERSE [UNIVERSE ...]]]
                                         [-i [SID [SID ...]]]
                                         [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                                         [--exclude-sids [SID [SID ...]]]
                                         [-o OUTFILE] [-j]

filtering options¶

-s, --start-date: limit to data on or after this date
-e, --end-date: limit to data on or before this date
-u, --universes: limit to these universes
-i, --sids: limit to these sids
--exclude-universes: exclude these universes
--exclude-sids: exclude these sids

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)

Query Interactive Brokers shortable shares from the local database and download to file.

Data timestamps are UTC.

Examples:

Query shortable shares for a universe of Australian stocks:

quantrocket fundamental ibkr-shortshares -u asx-stk -o asx_shortables.csv

ibkr-borrowfees¶

query Interactive Brokers borrow fees from the local database and download to file

quantrocket fundamental ibkr-borrowfees [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                                        [-u [UNIVERSE [UNIVERSE ...]]]
                                        [-i [SID [SID ...]]]
                                        [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                                        [--exclude-sids [SID [SID ...]]]
                                        [-o OUTFILE] [-j]

filtering options¶

-s, --start-date: limit to data on or after this date
-e, --end-date: limit to data on or before this date
-u, --universes: limit to these universes
-i, --sids: limit to these sids
--exclude-universes: exclude these universes
--exclude-sids: exclude these sids

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)

Query Interactive Brokers borrow fees from the local database and download to file.

Data timestamps are UTC.

Examples:

Query borrow fees for a universe of Australian stocks:

quantrocket fundamental ibkr-borrowfees -u asx-stk -o asx_borrow_fees.csv

alpaca-etb¶

query Alpaca easy-to-borrow data from the local database and download to file

quantrocket fundamental alpaca-etb [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                                   [-u [UNIVERSE [UNIVERSE ...]]]
                                   [-i [SID [SID ...]]]
                                   [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                                   [--exclude-sids [SID [SID ...]]]
                                   [-o OUTFILE] [-j]

filtering options¶

-s, --start-date: limit to data on or after this date
-e, --end-date: limit to data on or before this date
-u, --universes: limit to these universes
-i, --sids: limit to these sids
--exclude-universes: exclude these universes
--exclude-sids: exclude these sids

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)

Query Alpaca easy-to-borrow data from the local database and download to file.

Examples:

Query easy-to-borrow data for a universe of US stocks:

quantrocket fundamental alpaca-etb -u usa-stk -o usa_etb.csv

quantrocket.fundamental.collect_alpaca_etb()¶

Collect Alpaca easy-to-borrow data and save to database.

Data is updated daily. Historical data is available from March 2019.

Returns: status message
Return type: dict

quantrocket.fundamental.download_alpaca_etb(filepath_or_buffer=None, output='csv', start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None)¶

Query Alpaca easy-to-borrow data from the local database and download to file.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json, csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to data on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to data on or before this date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids

Returns

Return type

None

Examples

Query easy-to-borrow data for a universe of US stocks.

>>> f = io.StringIO()
>>> download_alpaca_etb("usa_etb.csv", universes=["usa-stk"])
>>> etb = pd.read_csv("usa_etb.csv", parse_dates=["Date"])

quantrocket.fundamental.get_alpaca_etb_reindexed_like(reindex_like)¶

Return a DataFrame of Alpaca easy-to-borrow status, reindexed to match the index (dates) and columns (sids) of reindex_like.

Parameters: reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
Returns: a Boolean DataFrame indicating easy-to-borrow status, shaped like the input DataFrame
Return type: DataFrame

Examples

Get easy-to-borrow status for a DataFrame of stocks:

>>> closes = prices.loc["Close"]
>>> are_etb = get_alpaca_etb_reindexed_like(closes)

quantrocket.fundamental.collect_ibkr_shortable_shares(countries=None)¶

Collect Interactive Brokers shortable shares data and save to database.

Data is organized by country and updated every 15 minutes. Historical data is available from April 2018.

Parameters: countries (list of str, optional) – limit to these countries (pass ‘?’ or any invalid country to see available countries)
Returns: status message
Return type: dict

quantrocket.fundamental.collect_ibkr_borrow_fees(countries=None)¶

Collect Interactive Brokers borrow fees data and save to database.

Data is organized by country and updated every 15 minutes. Historical data is available from April 2018.

Parameters: countries (list of str, optional) – limit to these countries (pass ‘?’ or any invalid country to see available countries)
Returns: status message
Return type: dict

quantrocket.fundamental.download_ibkr_shortable_shares(filepath_or_buffer=None, output='csv', start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None)¶

Query Interactive Brokers shortable shares from the local database and download to file.

Data timestamps are UTC.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json, csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to data on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to data on or before this date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids

Returns

Return type

None

Examples

Query shortable shares for a universe of Australian stocks.

>>> f = io.StringIO()
>>> download_ibkr_shortable_shares("asx_shortables.csv", universes=["asx-stk"])
>>> shortables = pd.read_csv("asx_shortables.csv", parse_dates=["Date"])

quantrocket.fundamental.download_ibkr_borrow_fees(filepath_or_buffer=None, output='csv', start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None)¶

Query Interactive Brokers borrow fees from the local database and download to file.

Data timestamps are UTC.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json, csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to data on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to data on or before this date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids

Returns

Return type

None

Examples

Query borrow fees for a universe of Australian stocks.

>>> f = io.StringIO()
>>> download_ibkr_borrow_fees("asx_borrow_fees.csv", universes=["asx-stk"])
>>> borrow_fees = pd.read_csv("asx_borrow_fees.csv", parse_dates=["Date"])

quantrocket.fundamental.get_ibkr_shortable_shares_reindexed_like(reindex_like, time=None)¶

Return a DataFrame of Interactive Brokers shortable shares, reindexed to match the index (dates) and columns (sids) of reindex_like.

Parameters

reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
time (str (HH:MM:SS[ TZ]), optional) – return shortable shares as of this time of day. If omitted, shortable shares will be returned as of the times of day in reindex_like’s DatetimeIndex. (Note that for a DatetimeIndex containing dates only, the time is 00:00:00, meaning shortable shares will be returned as of midnight at the start of the day.) A time and timezone can be passed as a space-separated string (e.g. “09:30:00 America/New_York”). If timezone is omitted, the timezone of reindex_like’s DatetimeIndex will be used; if reindex_like’s timezone is not set, the timezone will be inferred from the component securities, if all securities share the same timezone.

Returns

a DataFrame of shortable shares, shaped like the input DataFrame

Return type

DataFrame

Examples

Get shortable shares as of midnight for a DataFrame of US stocks:

>>> closes = prices.loc["Close"]
>>> shortables = get_ibkr_shortable_shares_reindexed_like(closes)

Get shortable shares as of 9:20 AM for a DataFrame of US stocks (timezone inferred from component stocks):

>>> closes = prices.loc["Close"]
>>> shortables = get_ibkr_shortable_shares_reindexed_like(closes, time="09:20:00")

Get shortable shares as of 9:20 AM New York time for a multi-timezone DataFrame of stocks:

>>> closes = prices.loc["Close"]
>>> shortables = get_ibkr_shortable_shares_reindexed_like(closes, time="09:20:00 America/New_York")

quantrocket.fundamental.get_ibkr_borrow_fees_reindexed_like(reindex_like, time=None)¶

Return a DataFrame of Interactive Brokers borrow fees, reindexed to match the index (dates) and columns (sids) of reindex_like.

Parameters

reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
time (str (HH:MM:SS[ TZ]), optional) – return borrow fees as of this time of day. If omitted, borrow fees will be returned as of the times of day in reindex_like’s DatetimeIndex. (Note that for a DatetimeIndex containing dates only, the time is 00:00:00, meaning borrow fees will be returned as of midnight at the start of the day.) A time and timezone can be passed as a space-separated string (e.g. “09:30:00 America/New_York”). If timezone is omitted, the timezone of reindex_like’s DatetimeIndex will be used; if reindex_like’s timezone is not set, the timezone will be inferred from the component securities, if all securities share the same timezone.

Returns

a DataFrame of borrow fees, shaped like the input DataFrame

Return type

DataFrame

Examples

Get borrow fees as of midnight for a DataFrame of US stocks:

>>> closes = prices.loc["Close"]
>>> borrow_fees = get_ibkr_borrow_fees_reindexed_like(closes)

Get borrow fees as of 4:30 PM for a DataFrame of US stocks (timezone inferred from component stocks):

>>> closes = prices.loc["Close"]
>>> borrow_fees = get_ibkr_borrow_fees_reindexed_like(closes, time="16:30:00")

Get borrow fees as of 4:30 PM New York time for a multi-timezone DataFrame of stocks:

>>> closes = prices.loc["Close"]
>>> borrow_fees = get_ibkr_borrow_fees_reindexed_like(closes, time="16:30:00 America/New_York")

quantrocket.fundamental.collect_reuters_financials(universes=None, sids=None, force=True)¶

Collect Reuters financial statements from Interactive Brokers and save to database.

This data provides cash flow, balance sheet, and income metrics.

Parameters

universes (list of str, optional) – limit to these universes (must provide universes, sids, or both)
sids (list of str, optional) – limit to these sids (must provide universes, sids, or both)
force (bool) – collect financials for all securities even if they were collected recently (default is to skip securities that were updated in the last 12 hours)

Returns

status message

Return type

dict

quantrocket.fundamental.collect_reuters_estimates(universes=None, sids=None, force=False)¶

Collect Reuters estimates and actuals from Interactive Brokers and save to database.

This data provides analyst estimates and actuals for a variety of indicators.

Parameters

universes (list of str, optional) – limit to these universes (must provide universes, sids, or both)
sids (list of str, optional) – limit to these sids (must provide universes, sids, or both)
force (bool) – collect estimates for all securities even if they were collected recently (default is to skip securities that were updated in the last 12 hours)

Returns

status message

Return type

dict

quantrocket.fundamental.list_reuters_codes(codes=None, report_types=None, statement_types=None)¶

List available Chart of Account (COA) codes from the Reuters financials database and/or indicator codes from the Reuters estimates/actuals database

Note: you must collect Reuters financials into the database before you can list COA codes.

Parameters

codes (list of str, optional) – limit to these Chart of Account (COA) or indicator codes
report_types (list of str, optional) – limit to these report types. Possible choices: financials, estimates
statement_types (list of str, optional) – limit to these statement types. Only applies to financials, not estimates. Possible choices: INC, BAL, CAS

Returns

codes and descriptions

Return type

dict

quantrocket.fundamental.download_reuters_financials(codes, filepath_or_buffer=None, output='csv', start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, interim=False, exclude_restatements=False, fields=None)¶

Query financial statements from the Reuters financials database and download to file.

You can query one or more COA codes. Use the list_reuters_codes function to see available codes.

Annual or interim reports are available. Annual is the default and provides deeper history.

Parameters

codes (list of str, required) – the Chart of Account (COA) code(s) to query
filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json or csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to statements on or after this fiscal period end date
end_date (str (YYYY-MM-DD), optional) – limit to statements on or before this fiscal period end date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
interim (bool, optional) – return interim reports (default is to return annual reports, which provide deeper history)
exclude_restatements (bool, optional) – exclude restatements (default is to include them)
fields (list of str, optional) – only return these fields (pass [‘?’] or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

Query total revenue (COA code RTLR) for a universe of Australian stocks. You can use StringIO to load the CSV into pandas.

>>> f = io.StringIO()
>>> download_reuters_financials(["RTLR"], f, universes=["asx-stk"],
                                start_date="2014-01-01"
                                end_date="2017-01-01")
>>> financials = pd.read_csv(f, parse_dates=["StatementDate", "SourceDate", "FiscalPeriodEndDate"])

Query net income (COA code NINC) from interim reports for two securities (identified by sid) and exclude restatements:

>>> download_reuters_financials(["NINC"], f, sids=["FIBBG123456", "FIBBG234567"],
                                interim=True, exclude_restatements=True)

Query common and preferred shares outstanding (COA codes QTCO and QTPO) and return a minimal set of fields (several required fields will always be returned):

>>> download_reuters_financials(["QTCO", "QTPO"], f, universes=["nyse-stk"],
                                fields=["Amount"])

quantrocket.fundamental.get_reuters_financials_reindexed_like(reindex_like, coa_codes, fields=['Amount'], interim=False, exclude_restatements=False, max_lag=None)¶

Return a multiindex (CoaCode, Field, Date) DataFrame of point-in-time Reuters financial statements for one or more Chart of Account (COA) codes, reindexed to match the index (dates) and columns (sids) of reindex_like. Financial values are forward-filled in order to provide the latest reading at any given date. Financials are indexed to the SourceDate field, i.e. the date on which the financial statement was released. SourceDate is shifted forward 1 day to avoid lookahead bias.

Parameters

reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
coa_codes (list of str, required) – the Chart of Account (COA) code(s) to query. Use the list_reuters_codes function to see available codes.
fields (list of str) – a list of fields to include in the resulting DataFrame. Defaults to simply including the Amount field.
interim (bool) – query interim/quarterly reports (default is to query annual reports, which provide deeper history)
exclude_restatements (bool, optional) – exclude restatements (default is to include them)
max_lag (str, optional) – maximum amount of time a data point can be used after the associated fiscal period has ended. Setting a limit can prevent using data that is reported long after the fiscal period ended, or can limit how far data is forward filled in the absence of subsequent data. Specify as a Pandas offset alias, e.g. ‘500D’. By default, no maximum limit is applied.

Returns

a multiindex (CoaCode, Field, Date) DataFrame of financials, shaped like the input DataFrame

Return type

DataFrame

Examples

Let’s calculate book value per share, defined as:

(Total Assets - Total Liabilities) / Number of shares outstanding

The COA codes for these metrics are ‘ATOT’ (Total Assets), ‘LTLL’ (Total Liabilities), and ‘QTCO’ (Total Common Shares Outstanding).

>>> closes = prices.loc["Close"]
>>> financials = get_reuters_financials_reindexed_like(closes, coa_codes=["ATOT", "LTLL", "QTCO"])
>>> tot_assets = financials.loc["ATOT"].loc["Amount"]
>>> tot_liabilities = financials.loc["LTLL"].loc["Amount"]
>>> shares_out = financials.loc["QTCO"].loc["Amount"]
>>> book_values_per_share = (tot_assets - tot_liabilities)/shares_out

quantrocket.fundamental.download_reuters_estimates(codes, filepath_or_buffer=None, output='csv', start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, period_types=None, fields=None)¶

Query estimates and actuals from the Reuters estimates database and download to file.

You can query one or more indicator codes. Use the list_reuters_codes function to see available codes.

Parameters

codes (list of str, required) – the indicator code(s) to query
filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json or csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to estimates and actuals on or after this fiscal period end date
end_date (str (YYYY-MM-DD), optional) – limit to estimates and actuals on or before this fiscal period end date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
period_types (list of str, optional) – limit to these fiscal period types. Possible choices: A, Q, S, where A=Annual, Q=Quarterly, S=Semi-Annual
fields (list of str, optional) – only return these fields (pass [‘?’] or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

Query EPS estimates and actuals for a universe of Australian stocks. You can use StringIO to load the CSV into pandas.

>>> f = io.StringIO()
>>> download_reuters_estimates(["EPS"], f, universes=["asx-stk"],
                                start_date="2014-01-01"
                                end_date="2017-01-01")
>>> estimates = pd.read_csv(f, parse_dates=["FiscalPeriodEndDate", "UpdatedDate"])

quantrocket.fundamental.get_reuters_estimates_reindexed_like(reindex_like, codes, fields=['Actual'], period_types=['Q'], ffill=True, shift=True, max_lag=None)¶

Return a multiindex (Indicator, Field, Date) DataFrame of point-in-time Reuters estimates and actuals for one or more indicator codes, reindexed to match the index (dates) and columns (sids) of reindex_like. Estimates and actuals are forward-filled in order to provide the latest reading at any given date, indexed to the UpdatedDate field (which usually corresponds to the announcement date). By default UpdatedDate is shifted forward 1 day to avoid lookahead bias.

Parameters

reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
codes (list of str, required) – the indicator code(s) to query. Use the list_reuters_codes function to see available codes.
fields (list of str) – a list of fields to include in the resulting DataFrame. Defaults to simply including the Actual field.
period_types (list of str, optional) – limit to these fiscal period types. Possible choices: A, Q, S, where A=Annual, Q=Quarterly, S=Semi-Annual. Default is Q/Quarterly.
ffill (bool) – forward-fill values in the resulting DataFrame so that each date reflects the latest available value as of that date. If False, values appear only on the first date they were available, followed by NaNs. Default True.
shift (bool) – shift values forward one day from the UpdatedDate to avoid lookahead bias. Shifting forward one day may be overly cautious as announcements may occur early in the day, for example before the market open, and thus may be actionable the same day. Set ‘shift=False’ to index values to the UpdatedDate rather than the day after, in which case you may also want to query UpdatedDate (timestamped in UTC) and use it to selectively shift estimates and actuals yourself. Default True.
max_lag (str, optional) – maximum amount of time a data point can be used after the associated fiscal period has ended. Setting a limit can prevent using data that is reported long after the fiscal period ended, or can limit how far data is forward filled in the absence of subsequent data. Specify as a Pandas offset alias, e.g. ‘500D’. By default, no maximum limit is applied.

Returns

a multiindex (Indicator, Field, Date) DataFrame of estimates and actuals, shaped like the input DataFrame

Return type

DataFrame

Examples

Query book value per share (code BVPS):

>>> closes = prices.loc["Close"]
>>> estimates = get_reuters_estimates_reindexed_like(closes, codes=["BVPS"])
>>> book_values_per_share = estimates.loc["BVPS"].loc["Actual"]

Query the UpdatedDate field without shifting or forward-filling, convert UTC to New York time, and determine whether the earnings were announced before 9 AM or after 4 PM:

>>> estimates = get_reuters_estimates_reindexed_like(
                    closes, codes="EPS", fields="UpdatedDate", ffill=False, shift=False)
>>> announce_dates = estimates.loc["EPS"].loc["UpdatedDate"]
>>> announce_hours = announce_dates.stack(dropna=False).dt.tz_localize("UTC").dt.tz_convert("America/New_York").dt.hour.unstack()
>>> announced_before_market_opens = announce_hours < 9
>>> announced_after_market_closes = announce_hours >= 16

quantrocket.fundamental.collect_sharadar_fundamentals(country='US')¶

Collect fundamental data from Sharadar and save to database.

Parameters: country (str, required) – country to collect fundamentals for. Possible choices: US, FREE
Returns: status message
Return type: dict

quantrocket.fundamental.collect_sharadar_insiders(country='US')¶

Collect insider holdings data from Sharadar and save to database.

Parameters: country (str, required) – country to collect insider holdings data for. Possible choices: US, FREE
Returns: status message
Return type: dict

quantrocket.fundamental.collect_sharadar_institutions(country='US', detail=False)¶

Collect institutional investor data from Sharadar and save to database.

Parameters

country (str, required) – country to collect institutional investor data for. Possible choices: US, FREE
detail (bool) – if true, collect detailed investor data (separate record per investor per security per quarter). If false (the default), collect data aggregated by security (separate record per security per quarter).

Returns

status message

Return type

dict

quantrocket.fundamental.collect_sharadar_sec8(country='US')¶

Collect SEC Form 8-K events from Sharadar and save to database.

Parameters: country (str, required) – country to collect events data for. Possible choices: US, FREE
Returns: status message
Return type: dict

quantrocket.fundamental.collect_sharadar_sp500(country='US')¶

Collect historical S&P 500 index constituents from Sharadar and save to database.

Parameters: country (str, required) – country to collect S&P 500 constituents data for. Possible choices: US, FREE
Returns: status message
Return type: dict

quantrocket.fundamental.download_sharadar_fundamentals(filepath_or_buffer=None, start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, dimensions=None, fields=None, output=None)¶

Query Sharadar fundamentals from the local database and download to file.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json, csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to fundamentals on or after this fiscal period end date
end_date (str (YYYY-MM-DD), optional) – limit to fundamentals on or before this fiscal period end date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
dimensions (list of str, optional) – limit to these dimensions. Possible choices: ARQ, ARY, ART, MRQ, MRY, MRT. AR=As Reported, MR=Most Recent Reported, Q=Quarterly, Y=Annual, T=Trailing Twelve Month.
fields (list of str, optional) – only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

Query as-reported trailing twelve month (ART) fundamentals for all indicators for a particular sid, then load the CSV into Pandas:

>>> download_sharadar_fundamentals(filepath_or_buffer="aapl_fundamentals.csv",
                                   sids="FIBBG265598", dimensions="ART")
>>> fundamentals = pd.read_csv("aapl_fundamentals.csv", parse_dates=["REPORTPERIOD", "DATEKEY", "CALENDARDATE"])

Query as-reported quarterly (ARQ) fundamentals for select indicators for a universe:

>>> download_sharadar_fundamentals(filepath_or_buffer="sharadar_fundamentals.csv",
                                   universes="usa-stk",
                                   dimensions="ARQ", fields=["REVENUE", "EPS"])

quantrocket.fundamental.download_sharadar_insiders(filepath_or_buffer=None, start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, fields=None, output=None)¶

Query Sharadar insider holdings data from the local database and download to file.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json, csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to data on or after this filing date
end_date (str (YYYY-MM-DD), optional) – limit to data on or before this filing date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
fields (list of str, optional) – only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

Query insider holdings data for a particular sid, then load the CSV into Pandas:

>>> download_sharadar_insiders(filepath_or_buffer="aapl_insiders.csv",
                                sids="FIBBG000B9XRY4")
>>> insiders = pd.read_csv("aapl_insiders.csv", parse_dates=["FILINGDATE", "TRANSACTIONDATE"])

quantrocket.fundamental.download_sharadar_institutions(filepath_or_buffer=None, start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, detail=False, fields=None, output=None)¶

Query Sharadar institutional investor data from the local database and download to file.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json, csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to data on or after this quarter end date
end_date (str (YYYY-MM-DD), optional) – limit to data on or before this quarter end date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
detail (bool) – if true, query detailed investor data (separate record per investor per security per quarter). If false (the default), query data aggregated by security (separate record per security per quarter).
fields (list of str, optional) – only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

Query institutional investor data aggregated by security and load the CSV into Pandas:

>>> download_sharadar_institutions(filepath_or_buffer="institutions.csv",
                                    universes="usa-stk", start_date="2019-01-01")
>>> institutions = pd.read_csv("institutions.csv", parse_dates=["CALENDARDATE"])

quantrocket.fundamental.download_sharadar_sec8(filepath_or_buffer=None, start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, event_codes=None, fields=None, output=None)¶

Query Sharadar SEC Form 8-K events data from the local database and download to file.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json, csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to data on or after this filing date
end_date (str (YYYY-MM-DD), optional) – limit to data on or before this filing date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
event_codes (list of int, optional) – limit to these event codes
fields (list of str, optional) – only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

Query event code 13 (Bankruptcy) for a universe of securities and load into Pandas:

>>> download_sharadar_sec8(filepath_or_buffer="bankruptcies.csv",
                            universes="usa-stk", event_codes=13)
>>> bankruptcies = pd.read_csv("bankruptcies.csv", parse_dates=["DATE"])

quantrocket.fundamental.download_sharadar_sp500(filepath_or_buffer=None, start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, fields=None, output=None)¶

Query Sharadar S&P 500 index changes (additions and removals) from the local database and download to file.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json, csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to index changes on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to index changes on or before this date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
fields (list of str, optional) – only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

Query S&P 500 index changes since 2010 and load into Pandas:

>>> download_sharadar_sp500(filepath_or_buffer="sp500_changes.csv", start_date="2010-01-01")
>>> sp500_changes = pd.read_csv("sp500_changes.csv", parse_dates=["DATE"])

Get the current members of the S&P 500:

>>> download_sharadar_sp500(filepath_or_buffer="sp500_changes.csv")
>>> sp500_changes = pd.read_csv("sp500_changes.csv", parse_dates=["DATE"])
>>> latest_changes = sp500_changes.drop_duplicates(subset="Sid", keep="last")
>>> current_members = latest_changes[latest_changes.ACTION == "added"]

quantrocket.fundamental.get_sharadar_fundamentals_reindexed_like(reindex_like, fields=None, dimension='ART')¶

Return a multiindex (Field, Date) DataFrame of point-in-time Sharadar fundamentals, reindexed to match the index (dates) and columns (sids) of reindex_like. Financial indicators are forward-filled in order to provide the latest reading at any given date. Indicators are indexed to the Sharadar DATEKEY field, i.e. the filing date. DATEKEY is shifted forward 1 day to avoid lookahead bias.

Parameters

reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
fields (list of str) – a list of fields to include in the resulting DataFrame. Defaults to including all fields. For faster performance, limiting fields to those needed is highly recommended, especially for large universes.
dimension (bool) – the dimension of the data. Defaults to As Reported Trailing Twelve Month (ART). Possible choices: ARQ, ARY, ART, MRQ, MRY, MRT. AR=As Reported, MR=Most Recent Reported, Q=Quarterly, Y=Annual, T=Trailing Twelve Month.

Returns

a multiindex (Field, Date) DataFrame of fundamentals, shaped like the input DataFrame

Return type

DataFrame

Examples

Query several trailing twelve month indicators using a DataFrame of historical prices:

>>> closes = prices.loc["Close"]
>>> fundamentals = get_sharadar_fundamentals_reindexed_like(closes, fields=["EPS", "REVENUE"])
>>> eps = fundamentals.loc["EPS"]
>>> revenue = fundamentals.loc["REVENUE"]

Query quarterly book value per share using a DataFrame of historical prices:

>>> closes = prices.loc["Close"]
>>> fundamentals = get_sharadar_fundamentals_reindexed_like(closes, fields=["BVPS"],
                                                             dimension="ARQ")
>>> bvps = fundamentals.loc["BVPS"]

Query outstanding shares using a DataFrame of historical prices:

>>> closes = prices.loc["Close"]
>>> fundamentals = get_sharadar_fundamentals_reindexed_like(closes,
                                                            fields=["SHARESWA"])
>>> shares_out = fundamentals.loc["SHARESWA"]

quantrocket.fundamental.get_sharadar_institutions_reindexed_like(reindex_like, fields=None, shift=45)¶

Return a multiindex (Field, Date) DataFrame of Sharadar institutional investor data, reindexed to match the index (dates) and columns (sids) of reindex_like. Values are forward-filled in order to provide the latest reading at any given date. Data are indexed to the quarter end date. Because the reporting deadline is 45 days after the end of the quarter the values are shifted forward 45 calendar days by default (see the shift parameter to control this).

Parameters

reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
fields (list of str) – a list of fields to include in the resulting DataFrame. Defaults to including all fields. For faster performance, limiting fields to those needed is highly recommended, especially for large universes.
shift (int, optional) – shift the data forward this many period to account for the 45-day lag between the quarter end date and the reporting deadline. Defaults to 45.

Returns

a multiindex (Field, Date) DataFrame of institutional investor data, shaped like the input DataFrame

Return type

DataFrame

Examples

Calculate institutional ownership as a percentage of total market cap:

>>> closes = prices.loc["Close"]
>>> insti = get_sharadar_institutions_reindexed_like(closes, fields="SHRVALUE")
>>> insti_share_values = insti.loc["SHRVALUE"]
>>> fundamentals = get_sharadar_fundamentals_reindexed_like(closes, dimension="ARQ", fields="MARKETCAP")
>>> market_caps = fundamentals.loc["MARKETCAP"]
>>> insti_pct = insti_share_values/market_caps

quantrocket.fundamental.get_sharadar_sec8_reindexed_like(reindex_like, event_codes=None)¶

Return a Boolean DataFrame indicating whether securities filed SEC Form 8-K for specified event codes on given dates. The resulting DataFrame will be reindexed to match the index (dates) and columns (sids) of reindex_like.

Parameters

reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
event_codes (list of int, optional) – limit to these event codes

Returns

a Boolean DataFrame shaped like the input DataFrame

Return type

DataFrame

Examples

Query bankruptcies (event code 13) and use it to mask a prices DataFrame:

>>> closes = prices.loc["Close"]
>>> filed_for_bankruptcy = get_sharadar_sec8_reindexed_like(closes, event_codes=13)
>>> closes.where(filed_for_bankruptcy)

quantrocket.fundamental.get_sharadar_sp500_reindexed_like(reindex_like)¶

Return a Boolean DataFrame indicating whether securities were in the S&P 500 on the given dates. The resulting DataFrame will be reindexed to match the index (dates) and columns (sids) of reindex_like.

Parameters: reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
Returns: a Boolean DataFrame shaped like the input DataFrame
Return type: DataFrame

Examples

Query S&P 500 membership and use it to mask a prices DataFrame:

>>> closes = prices.loc["Close"]
>>> are_in_sp500 = get_sharadar_sp500_reindexed_like(closes)
>>> closes.where(are_in_sp500)

quantrocket.fundamental.collect_wsh_earnings_dates(universes=None, sids=None, force=False)¶

Collect Wall Street Horizon upcoming earnings announcement dates from Interactive Brokers and save to database.

Parameters

universes (list of str, optional) – limit to these universes (must provide universes, sids, or both)
sids (list of str, optional) – limit to these sids (must provide universes, sids, or both)
force (bool) – collect earnings dates for all securities even if they were collected recently (default is to skip securities that were updated in the last 12 hours)

Returns

status message

Return type

dict

quantrocket.fundamental.download_wsh_earnings_dates(filepath_or_buffer=None, output='csv', start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, statuses=None, fields=None)¶

Query earnings announcement dates from the Wall Street Horizon announcements database and download to file.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json or csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to announcements on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to announcements on or before this date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
statuses (list of str, optional) – limit to these confirmation statuses. Possible choices: Confirmed, Unconfirmed
fields (list of str, optional) – only return these fields (pass [‘?’] or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

Query earnings dates for a universe of US stocks:

>>> download_wsh_earnings_dates("announcements.csv", universes=["usa-stk"],
                                start_date="2019-01-01"
                                end_date="2019-04-01")
>>> announcements = pd.read_csv("announcements.csv", parse_dates=["Date"])

quantrocket.fundamental.get_wsh_earnings_dates_reindexed_like(reindex_like, fields=['Time'], statuses=['Confirmed'])¶

Return a multiindex (Field, Date) DataFrame of earnings announcement dates, reindexed to match the index (dates) and columns (sids) of reindex_like.

Parameters

reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
fields (list of str) – a list of fields to include in the resulting DataFrame. Defaults to including the Time field.
statuses (list of str, optional) – limit to these confirmation statuses. By default only confirmed announcements are returned. Possible choices: Confirmed, Unconfirmed.

Returns

a multiindex (Field, Date) DataFrame of earnings dates, shaped like the input DataFrame

Return type

DataFrame

Examples

Get a boolean DataFrame indicating announcements that occurred since the prior close:

>>> closes = prices.loc["Close"]
>>> announcements = get_wsh_earnings_dates_reindexed_like(closes)
>>> announce_times = announcements.loc["Time"]
>>> announced_since_prior_close = (announce_times == "Before Market") | (announce_times.shift() == "After Market")

For live trading, to get a boolean DataFrame indicating announcements that will occur before the next session’s open, first extend the index of the input DataFrame to include the next session:

>>> from ib_trading_calendars import get_calendar
>>> nyse_cal = get_calendar("NYSE")
>>> latest_session = closes.index.max()
>>> # wind latest session to end of day and use calendar to get next session
>>> next_session = nyse_cal.next_open(latest_session.replace(hour=23, minute=59)).date()
>>> closes = closes.reindex(closes.index.union([next_session]))
>>> closes.index.name = "Date" # reindex loses name attribute

Then get the announcements, shifting pre-market announcements backward:

>>> announcements = get_wsh_earnings_dates_reindexed_like(closes)
>>> announce_times = announcements.loc["Time"]
>>> announces_before_next_open = (announce_times == "After Market") | (announce_times.shift(-1) == "Before Market")

Finally, if needed, restore the DataFrame indexes to their original shape:

>>> closes = closes.drop(next_session)
>>> announces_before_next_open = announces_before_next_open.drop(next_session)

Fundamental Data API

Resource Group ¶

Sharadar Fundamentals ¶

Collect Sharadar Fundamentals
POST`/fundamental/sharadar/fundamentals{?country}`

Collect fundamental data from Sharadar and save to database.

Example URI

POST http://houston/fundamental/sharadar/fundamentals?country=US

URI Parameters

country

str (required) Example: US

country to collect fundamentals for

Choices: US FREE

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the fundamental data will be collected asynchronously"
}

Download Sharadar Fundamentals
GET`/fundamental/sharadar/fundamentals{filetype}{?start_date,end_date,universes,sids,exclude_universes,exclude_sids,dimensions,fields}`

Query Sharadar fundamentals from the local database and download to file.

Example URI

GET http://houston/fundamental/sharadar/fundamentals.csv?start_date=2014-01-01&end_date=2018-01-01&universes=nyse-stk&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456&dimensions=ARQ&fields=EPS

URI Parameters

filetype

str (required) Example: .csv

output format

Choices: .csv .json

start_date

str (optional) Example: 2014-01-01

limit to fundamentals on or after this fiscal period end date

end_date

str (optional) Example: 2018-01-01

limit to fundamentals on or before this fiscal period end date

universes

str (optional) Example: nyse-stk

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

dimensions

str (optional) Example: ARQ

limit to these dimensions

Choices: ARQ ARY ART MRQ MRY MRT

fields

str (optional) Example: EPS

only return these fields (pass multiple times for multiple fields)

Response 200

Headers

Content-Type: text/csv

Sharadar Insiders ¶

Collect Sharadar Insiders
POST`/fundamental/sharadar/insiders{?country}`

Collect insider holdings data from Sharadar and save to database.

Example URI

POST http://houston/fundamental/sharadar/insiders?country=US

URI Parameters

country

str (required) Example: US

country to collect insider holdings data for

Choices: US FREE

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the insiders data will be collected asynchronously"
}

Download Sharadar Insiders
GET`/fundamental/sharadar/insiders{filetype}{?start_date,end_date,universes,sids,exclude_universes,exclude_sids,fields}`

Query Sharadar insider holdings data from the local database and download to file.

Example URI

GET http://houston/fundamental/sharadar/insiders.csv?start_date=2014-01-01&end_date=2018-01-01&universes=nyse-stk&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456&fields=OWNERNAME

URI Parameters

filetype

str (required) Example: .csv

output format

Choices: .csv .json

start_date

str (optional) Example: 2014-01-01

limit to data on or after this filing date

end_date

str (optional) Example: 2018-01-01

limit to data on or before this filing date

universes

str (optional) Example: nyse-stk

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

fields

str (optional) Example: OWNERNAME

only return these fields (pass multiple times for multiple fields)

Response 200

Headers

Content-Type: text/csv

Sharadar Institutions ¶

Collect Sharadar Institutions
POST`/fundamental/sharadar/institutions{?country,detail}`

Collect institutional investor data from Sharadar and save to database.

Example URI

POST http://houston/fundamental/sharadar/institutions?country=US&detail=true

URI Parameters

country

str (required) Example: US

country to collect institutional investor data for

Choices: US FREE

detail

bool (optional) Example: true

if true, collect detailed investor data (separate record per investor per security per quarter). If false (the default), collect data aggregated by security (separate record per security per quarter).

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the institutional investor data will be collected asynchronously"
}

Download Sharadar Institutions
GET`/fundamental/sharadar/institutions{filetype}{?detail,start_date,end_date,universes,sids,exclude_universes,exclude_sids,fields}`

Query Sharadar institutional investor data from the local database and download to file.

Example URI

GET http://houston/fundamental/sharadar/institutions.csv?detail=true&start_date=2014-01-01&end_date=2018-01-01&universes=nyse-stk&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456&fields=INVESTORNAME

URI Parameters

filetype

str (required) Example: .csv

output format

Choices: .csv .json

start_date

str (optional) Example: 2014-01-01

limit to data on or after this quarter end date

end_date

str (optional) Example: 2018-01-01

limit to data on or before this quarter end date

universes

str (optional) Example: nyse-stk

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

fields

str (optional) Example: INVESTORNAME

only return these fields (pass multiple times for multiple fields)

detail

bool (optional) Example: true

if true, query detailed investor data (separate record per investor per security per quarter). If false (the default), query data aggregated by security (separate record per security per quarter).

Response 200

Headers

Content-Type: text/csv

Sharadar SEC Form 8-K ¶

Collect Sharadar SEC 8-K
POST`/fundamental/sharadar/sec8{?country}`

Collect SEC Form 8-K events from Sharadar and save to database.

Example URI

POST http://houston/fundamental/sharadar/sec8?country=US

URI Parameters

country

str (required) Example: US

country to collect events data for

Choices: US FREE

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the sec8 data will be collected asynchronously"
}

Download Sharadar SEC 8-K
GET`/fundamental/sharadar/sec8{filetype}{?start_date,end_date,event_codes,universes,sids,exclude_universes,exclude_sids,fields}`

Query Sharadar SEC Form 8-K events data from the local database and download to file.

Example URI

GET http://houston/fundamental/sharadar/sec8.csv?start_date=2014-01-01&end_date=2018-01-01&event_codes=11&universes=nyse-stk&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456&fields=EVENTCODE

URI Parameters

filetype

str (required) Example: .csv

output format

Choices: .csv .json

start_date

str (optional) Example: 2014-01-01

limit to data on or after this filing date

end_date

str (optional) Example: 2018-01-01

limit to data on or before this filing date

universes

str (optional) Example: nyse-stk

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

event_codes

int (optional) Example: 11

limit to these event codes (pass multiple times for multiple event codes)

fields

str (optional) Example: EVENTCODE

only return these fields (pass multiple times for multiple fields)

Response 200

Headers

Content-Type: text/csv

Sharadar S&P 500 ¶

Collect Sharadar S&P 500
POST`/fundamental/sharadar/sp500{?country}`

Collect historical S&P 500 index constituents from Sharadar and save to database.

Example URI

POST http://houston/fundamental/sharadar/sp500?country=US

URI Parameters

country

str (required) Example: US

country to collect S&P 500 constituents data for

Choices: US FREE

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the sp500 data will be collected asynchronously"
}

Download Sharadar S&P 500
GET`/fundamental/sharadar/sp500{filetype}{?start_date,end_date,universes,sids,exclude_universes,exclude_sids,fields}`

Query Sharadar S&P 500 index changes (additions and removals) from the local database and download to file.

Example URI

GET http://houston/fundamental/sharadar/sp500.csv?start_date=2014-01-01&end_date=2018-01-01&universes=nyse-stk&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456&fields=EVENTCODE

URI Parameters

filetype

str (required) Example: .csv

output format

Choices: .csv .json

start_date

str (optional) Example: 2014-01-01

limit to data on or after this date

end_date

str (optional) Example: 2018-01-01

limit to data on or before this date

universes

str (optional) Example: nyse-stk

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

fields

str (optional) Example: EVENTCODE

only return these fields (pass multiple times for multiple fields)

Response 200

Headers

Content-Type: text/csv

Alpaca Easy-to-Borrow ¶

Collect ETB
POST`/fundamental/alpaca/stockloan/etb`

Collect Alpaca easy-to-borrow data and save to database.

Data is updated daily. Historical data is available from March 2019.

Example URI

POST http://houston/fundamental/alpaca/stockloan/etb

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the etb data will be collected asynchronously"
}

Download ETB
GET`/fundamental/alpaca/stockloan/etb{filetype}{?start_date,end_date,universes,sids,exclude_universes,exclude_sids}`

Query Alpaca easy-to-borrow data from the local database and download to file.

Example URI

GET http://houston/fundamental/alpaca/stockloan/etb.csv?start_date=2018-04-16&end_date=2019-01-01&universes=japan-banks&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456

URI Parameters

filetype

str (required) Example: .csv

output format

Choices: .csv .json

start_date

str (optional) Example: 2018-04-16

limit to data on or after this date

end_date

str (optional) Example: 2019-01-01

limit to data on or before this date

universes

str (optional) Example: japan-banks

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

Response 200

Headers

Content-Type: text/csv

IBKR Shortable Shares ¶

Collect Shortable Shares
POST`/fundamental/ibkr/stockloan/shares{?countries}`

Collect Interactive Brokers shortable shares data and save to database.

Data is organized by country and updated every 15 minutes. Historical data is available from April 2018.

Example URI

POST http://houston/fundamental/ibkr/stockloan/shares?countries=usa

URI Parameters

countries: str (optional) Example: usa
limit to these countries (pass ‘?’ or any invalid country to see available countries) (pass multiple times for multiple countries)

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the shortable shares will be collected asynchronously"
}

Download IBKR Shortable Shares
GET`/fundamental/ibkr/stockloan/shares{filetype}{?start_date,end_date,universes,sids,exclude_universes,exclude_sids}`

Query Interactive Brokers shortable shares from the stockloan database and download to file.

Data timestamps are UTC.

Example URI

GET http://houston/fundamental/ibkr/stockloan/shares.csv?start_date=2018-04-16&end_date=2019-01-01&universes=japan-banks&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456

URI Parameters

filetype

str (required) Example: .csv

output format

Choices: .csv .json

start_date

str (optional) Example: 2018-04-16

limit to data on or after this date

end_date

str (optional) Example: 2019-01-01

limit to data on or before this date

universes

str (optional) Example: japan-banks

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

Response 200

Headers

Content-Type: text/csv

IBKR Borrow Fees ¶

Collect IBKR Borrow Fees
POST`/fundamental/ibkr/stockloan/fees{?countries}`

Collect Interactive Brokers borrow fees data and save to database.

Data is organized by country and updated every 15 minutes. Historical data is available from April 2018.

Example URI

POST http://houston/fundamental/ibkr/stockloan/fees?countries=usa

URI Parameters

countries: str (optional) Example: usa
limit to these countries (pass ‘?’ or any invalid country to see available countries) (pass multiple times for multiple countries)

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the borrow fees will be collected asynchronously"
}

Download IBKR Borrow Fees
GET`/fundamental/ibkr/stockloan/fees{filetype}{?start_date,end_date,universes,sids,exclude_universes,exclude_sids}`

Query Interactive Brokers borrow fees from the stockloan database and download to file.

Data timestamps are UTC.

Example URI

GET http://houston/fundamental/ibkr/stockloan/fees.csv?start_date=2018-04-16&end_date=2019-01-01&universes=japan-banks&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456

URI Parameters

filetype

str (required) Example: .csv

output format

Choices: .csv .json

start_date

str (optional) Example: 2018-04-16

limit to data on or after this date

end_date

str (optional) Example: 2019-01-01

limit to data on or before this date

universes

str (optional) Example: japan-banks

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

Response 200

Headers

Content-Type: text/csv

Wall Street Horizon earnings announcement dates ¶

Collect Earnings Dates
POST`/fundamental/wsh/calendar{?universes,sids,force}`

Collect Wall Street Horizon upcoming earnings announcement dates from Interactive Brokers and save to database.

Example URI

POST http://houston/fundamental/wsh/calendar?universes=usa-stk&sids=FI12345&force=false

URI Parameters

universes: str (optional) Example: usa-stk
limit to these universes (must provide universes, sids, or both) (pass multiple times for multiple universes)
sids: str (optional) Example: FI12345
limit to these sids (must provide universes, sids, or both) (pass multiple times for multiple sids)
force: boolean (optional) Example: false
collect earnings dates for all securities even if they were collected recently (default is to skip securities that were updated in the last 12 hours)

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the fundamental data will be collected asynchronously"
}

Download Earnings Dates
GET`/fundamental/wsh/calendar{filetype}{?start_date,end_date,universes,sids,exclude_universes,exclude_sids,statuses,fields}`

Query earnings announcement dates from the Wall Street Horizon announcements database and download to file.

Example URI

GET http://houston/fundamental/wsh/calendar.csv?start_date=2014-01-01&end_date=2018-01-01&universes=usa-stk&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456&statuses=Confirmed&fields=Time

URI Parameters

filetype

str (required) Example: .csv

output format

Choices: .csv .json

start_date

str (optional) Example: 2014-01-01

limit to announcements on or after this date

end_date

str (optional) Example: 2018-01-01

limit to announcements on or before this date

universes

str (optional) Example: usa-stk

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

statuses

str (optional) Example: Confirmed

limit to these confirmation statuses

Choices: Confirmed Unconfirmed

fields

str (optional) Example: Time

only return these fields (pass multiple times for multiple fields)

Response 200

Headers

Content-Type: text/csv

Body

Sid,Date,Time,Status,Period,LastUpdated
FI4027,2019-05-21,"Before Market",Unconfirmed,2019-1,2019-04-04T02:17:27
FI4050,2019-06-05,"After Market",Unconfirmed,2019-2,2019-04-04T02:17:27

Reuters Financials ¶

Collect Reuters Financials
POST`/fundamental/reuters/financials{?universes,sids,force}`

Collect Reuters financial statements from Interactive Brokers and save to database.

This data provides cash flow, balance sheet, and income metrics.

Example URI

POST http://houston/fundamental/reuters/financials?universes=japan-banks&sids=FI12345&force=false

URI Parameters

universes: str (optional) Example: japan-banks
limit to these universes (must provide universes, sids, or both) (pass multiple times for multiple universes)
sids: str (optional) Example: FI12345
limit to these sids (must provide universes, sids, or both) (pass multiple times for multiple sids)
force: boolean (optional) Example: false
collect financials for all securities even if they were collected recently (default is to skip securities that were updated in the last 12 hours)

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the fundamental data will be collected asynchronously"
}

Download Reuters Financials
GET`/fundamental/reuters/financials{filetype}{?codes,start_date,end_date,universes,sids,exclude_universes,exclude_sids,interim,exclude_restatements,fields}`

Query financial statements from the Reuters financials database and download to file.

You can query one or more COA codes.

Annual or interim/quarterly reports are available. Annual is the default and provides deeper history.

Example URI

GET http://houston/fundamental/reuters/financials.csv?codes=QTCO&start_date=2014-01-01&end_date=2018-01-01&universes=japan-banks&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456&interim=true&exclude_restatements=false&fields=Amount

URI Parameters

codes

str (required) Example: QTCO

the Chart of Account (COA) code(s) to query (pass multiple times for multiple codes)

filetype

str (required) Example: .csv

output format

Choices: .csv .json

start_date

str (optional) Example: 2014-01-01

limit to statements on or after this fiscal period end date

end_date

str (optional) Example: 2018-01-01

limit to statements on or before this fiscal period end date

universes

str (optional) Example: japan-banks

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

interim

bool (optional) Example: true

return interim/quarterly reports (default is to return annual reports, which provide deeper history)

exclude_restatements

bool (optional) Example: false

exclude restatements (default is to include them)

fields

str (optional) Example: Amount

only return these fields (pass multiple times for multiple fields)

Response 200

Headers

Content-Type: text/csv

Body

CoaCode,Sid,Amount,FiscalYear,FiscalPeriodEndDate,FiscalPeriodType,FiscalPeriodNumber,StatementType,StatementPeriodLength,StatementPeriodUnit,UpdateTypeCode,UpdateTypeDescription,StatementDate,AuditorNameCode,AuditorName,AuditorOpinionCode,AuditorOpinion,Source,SourceDate
EIBT,FI9029,13.53,2014,2014-12-31,Annual,,INC,12,M,UPD,"Updated Normal",2014-12-31,EY,"Ernst & Young LLP",UNQ,Unqualified,10-K,2015-03-13
EIBT,FI9029,28.117,2015,2015-12-31,Annual,,INC,12,M,UPD,"Updated Normal",2015-12-31,EY,"Ernst & Young LLP",UNQ,Unqualified,10-K,2016-02-29

Reuters Estimates ¶

Collect Reuters Estimates
POST`/fundamental/reuters/estimates{?universes,sids,force}`

Collect Reuters estimates and actuals from Interactive Brokers and save to database.

This data provides analyst estimates and actuals for a variety of indicators.

Example URI

POST http://houston/fundamental/reuters/estimates?universes=japan-banks&sids=FI12345&force=false

URI Parameters

universes: str (optional) Example: japan-banks
limit to these universes (must provide universes, sids, or both) (pass multiple times for multiple universes)
sids: str (optional) Example: FI12345
limit to these sids (must provide universes, sids, or both) (pass multiple times for multiple sids)
force: boolean (optional) Example: false
collect estimates for all securities even if they were collected recently (default is to skip securities that were updated in the last 12 hours)

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the fundamental data will be collected asynchronously"
}

Download Reuters Estimates
GET`/fundamental/reuters/estimates{filetype}{?codes,start_date,end_date,universes,sids,exclude_universes,exclude_sids,period_types,fields}`

Query estimates and actuals from the Reuters estimates database and download to file.

You can query one or more indicator codes.

Example URI

GET http://houston/fundamental/reuters/estimates.csv?codes=EPS&start_date=2014-01-01&end_date=2018-01-01&universes=japan-banks&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456&period_types=A&fields=Actual

URI Parameters

codes

str (required) Example: EPS

the indicator code(s) to query (pass multiple times for multiple codes)

filetype

str (required) Example: .csv

output format

Choices: .csv .json

start_date

str (optional) Example: 2014-01-01

limit to estimates and actuals on or after this fiscal period end date

end_date

str (optional) Example: 2018-01-01

limit to estimates and actuals on or before this fiscal period end date

universes

str (optional) Example: japan-banks

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

period_types

str (optional) Example: A

limit to these fiscal period types (A=Annual, Q=Quarterly, S=Semi-Annual)

Choices: A Q S

fields

str (optional) Example: Actual

only return these fields (pass multiple times for multiple fields)

Response 200

Headers

Content-Type: text/csv

Body

Sid,Indicator,Unit,FiscalYear,FiscalPeriodEndDate,FiscalPeriodType,FiscalPeriodNumber,High,Low,Mean,Median,StdDev,NumOfEst,AnnounceDate,UpdatedDate,Actual
FI9029,EPS,U,2014,2014-03-31,Q,1,0.31,0.2,0.255,0.255,0.055,2,2014-05-01T11:45:00,2014-05-01T12:06:31,0.12
FI9029,EPS,U,2014,2014-06-30,Q,2,0.77,0.73,0.7467,0.74,0.017,3,2014-07-31T11:45:00,2014-07-31T13:47:24,1.02

Reuters Codes ¶

List Reuters Codes
GET`/fundamental/reuters/codes{?codes,report_types,statement_types}`

List available Chart of Account (COA) codes from the Reuters financials database and/or indicator codes from the Reuters estimates/actuals database

Note: you must collect Reuters financials into the database before you can list COA codes.

Example URI

GET http://houston/fundamental/reuters/codes?codes=ATOT&report_types=financials&statement_types=INC

URI Parameters

codes

str (optional) Example: ATOT

limit to these Chart of Account (COA) or indicator codes (pass multiple times for multiple codes)

report_types

str (optional) Example: financials

limit to these report types (pass multiple times for multiple report types)

Choices: financials estimates

statement_types

str (optional) Example: INC

limit to these statement types. Only applies to financials, not estimates (pass multiple times for multiple statement types)

Choices: INC BAL CAS

Response 200

Headers

Content-Type: application/json

Body

{
  "financials": {
    "FCDP": "Total Cash Dividends Paid",
    "FPRD": "Issuance (Retirement) of Debt, Net",
    "FPSS": "Issuance (Retirement) of Stock, Net",
    "FTLF": "Cash from Financing Activities",
    "ITLI": "Cash from Investing Activities",
    "OBDT": "Deferred Taxes",
    "OCPD": "Cash Payments",
    "OCRC": "Cash Receipts"
  }
}

quantrocket.history

historical market data service

QuantRocket historical market data CLI

usage: quantrocket history [-h]
                           {create-edi-db,create-ibkr-db,create-sharadar-db,create-usstock-db,list,config,drop-db,collect,queue,cancel,wait,get}
                           ...

subcommands¶

subcommand: Possible choices: create-edi-db, create-ibkr-db, create-sharadar-db, create-usstock-db, list, config, drop-db, collect, queue, cancel, wait, get

Sub-commands:¶

create-edi-db¶

create a new database for collecting historical data from EDI

quantrocket history create-edi-db [-h] [-e [MIC [MIC ...]]] CODE

Positional Arguments¶

CODE: the code to assign to the database (lowercase alphanumerics and hyphens only)

Named Arguments¶

-e, --exchanges: one or more exchange codes (MICs) which should be collected

Create a new database for collecting historical data from EDI.

Examples:

Create a database for end-of-day China stock prices from EDI:

quantrocket history create-edi-db china-1d -e XSHG XSHE

create-ibkr-db¶

create a new database for collecting historical data from Interactive Brokers

quantrocket history create-ibkr-db [-h] [-u [UNIVERSE [UNIVERSE ...]]]
                                   [-i [SID [SID ...]]] [-s YYYY-MM-DD]
                                   [-e YYYY-MM-DD] [-z BAR_SIZE] [-t BAR_TYPE]
                                   [-o] [-p]
                                   [--times [HH:MM:SS [HH:MM:SS ...]] |
                                   --between-times HH:MM:SS HH:MM:SS]
                                   [--shard HOW]
                                   CODE

Positional Arguments¶

CODE: the code to assign to the database (lowercase alphanumerics and hyphens only)

Named Arguments¶

-u, --universes

include these universes

-i, --sids

include these sids

-s, --start-date

collect history back to this start date (default is to collect as far back as data is available)

-e, --end-date

collect history up to this end date (default is to collect up to the present)

-z, --bar-size

Possible choices: 1 secs, 5 secs, 10 secs, 15 secs, 30 secs, 1 min, 2 mins, 3 mins, 5 mins, 10 mins, 15 mins, 20 mins, 30 mins, 1 hour, 2 hours, 3 hours, 4 hours, 8 hours, 1 day, 1 week, 1 month

the bar size to collect. Possible choices: [‘1 secs’, ‘5 secs’, ‘10 secs’, ‘15 secs’, ‘30 secs’, ‘1 min’, ‘2 mins’, ‘3 mins’, ‘5 mins’, ‘10 mins’, ‘15 mins’, ‘20 mins’, ‘30 mins’, ‘1 hour’, ‘2 hours’, ‘3 hours’, ‘4 hours’, ‘8 hours’, ‘1 day’, ‘1 week’, ‘1 month’]

-t, --bar-type

Possible choices: TRADES, ADJUSTED_LAST, MIDPOINT, BID, ASK, BID_ASK, HISTORICAL_VOLATILITY, OPTION_IMPLIED_VOLATILITY

the bar type to collect (if not specified, defaults to MIDPOINT for FX and TRADES for everything else). Possible choices: [‘TRADES’, ‘ADJUSTED_LAST’, ‘MIDPOINT’, ‘BID’, ‘ASK’, ‘BID_ASK’, ‘HISTORICAL_VOLATILITY’, ‘OPTION_IMPLIED_VOLATILITY’]

-o, --outside-rth

include data from outside regular trading hours (default is to limit to regular trading hours)

Default: False

-p, --primary-exchange

limit to data from the primary exchange

Default: False

--times

limit to these times (refers to the bar’s start time; mutually exclusive with –between-times)

--between-times

limit to times between these two times (refers to the bar’s start time; mutually exclusive with –times)

--shard

Possible choices: year, month, day, time, sid, sid,time, off

whether and how to shard the database, i.e. break it into smaller pieces. Required for intraday databases. Possible choices are year (separate database for each year), month (separate database for each year+month), day (separate database for each day), time (separate database for each bar time), sid (separate database for each security), sid,time (duplicate copies of database, one sharded by sid and the other by time),or off (no sharding). See http://qrok.it/h/shard for more help.

Create a new database for collecting historical data from Interactive Brokers.

The historical data requirements you specify when you create a new database (bar size, universes, etc.) are applied each time you collect data for that database.

Examples:

Create an end-of-day database called “arca-etf-eod” for a universe called “arca-etf”:

quantrocket history create-ibkr-db ‘arca-etf-eod’ –universes ‘arca-etf’ –bar-size ‘1 day’

Create a similar end-of-day database, but collect primary exchange prices instead of consolidated prices, adjust prices for dividends (=ADJUSTED_LAST), and use an explicit start date:

quantrocket history create-ibkr-db ‘arca-etf-eod’ -u ‘arca-etf’ -z ‘1 day’ –primary-exchange –bar-type ‘ADJUSTED_LAST’ -s 2010-01-01

Create a database of 1-minute bars showing the midpoint for a universe of FX pairs:

quantrocket history create-ibkr-db ‘fx-1m’ -u ‘fx’ -z ‘1 min’ –bar-type MIDPOINT

Create a database of 1-second bars just before the open for a universe of Canadian energy stocks in 2016:

quantrocket history create-ibkr-db ‘tse-enr-929’ -u ‘tse-enr’ -z ‘1 secs’ –outside-rth –times 09:29:55 09:29:56 09:29:57 09:29:58 09:29:59 -s 2016-01-01 -e 2016-12-31

create-sharadar-db¶

create a new database for collecting historical data from Sharadar

quantrocket history create-sharadar-db [-h] [-t SEC_TYPE] [-c COUNTRY] CODE

Positional Arguments¶

CODE: the code to assign to the database (lowercase alphanumerics and hyphens only)

Named Arguments¶

-t, --sec-type

Possible choices: STK, ETF

the security type to collect. Possible choices: [‘STK’, ‘ETF’]

-c, --country

Possible choices: US, FREE

country to collect data for. Possible choices: [‘US’, ‘FREE’]

Default: “US”

Create a new database for collecting historical data from Sharadar.

Examples:

Create a database for Sharadar US stocks and call it “sharadar-us-stk-1d”:

quantrocket history create-sharadar-db sharadar-us-stk-1d –sec-type STK –country US

create-usstock-db¶

create a new database for collecting historical US stock data from QuantRocket

quantrocket history create-usstock-db [-h] [-z BAR_SIZE] [-u {US,FREE}] CODE

Positional Arguments¶

CODE: the code to assign to the database (lowercase alphanumerics and hyphens only)

Named Arguments¶

-z, --bar-size

Possible choices: 1 day

the bar size to collect. Possible choices: [‘1 day’]

-u, --universe

Possible choices: US, FREE

the universe to collect. Possible choices: [‘US’, ‘FREE’]

Create a new database for collecting historical US stock data from QuantRocket.

Examples:

Create a database for end-of-day US stock prices:

quantrocket history create-usstock-db us-stk-1d –bar-size ‘1 day’

list¶

list history databases

quantrocket history list [-h]

List history databases.

Examples:

quantrocket history list

config¶

return the configuration for a history database

quantrocket history config [-h] code

Positional Arguments¶

code: the database code

Return the configuration for a history database.

Examples:

Return the configuration for a database called “jpn-lrg-15m”:

quantrocket history config jpn-lrg-15m

drop-db¶

delete a history database

quantrocket history drop-db [-h] --confirm-by-typing-db-code-again CODE code

Positional Arguments¶

code: the database code

Named Arguments¶

--confirm-by-typing-db-code-again: enter the db code again to confirm you want to drop the database, its config, and all its data

Delete a history database.

Deleting a history database deletes its configuration and data and is irreversible.

Examples:

Delete a database called “jpn-lrg-15m”:

quantrocket history drop-db jpn-lrg-15m –confirm-by-typing-db-code-again jpn-lrg-15m

collect¶

collect historical market data from a vendor and save it to a history database

quantrocket history collect [-h] [-i [SID [SID ...]]]
                            [-u [UNIVERSE [UNIVERSE ...]]] [-s YYYY-MM-DD]
                            [-e YYYY-MM-DD] [-p]
                            CODE [CODE ...]

Positional Arguments¶

CODE: the database code(s) to collect data for

Named Arguments¶

-i, --sids

collect history for these sids, overriding config (typically used to collect a subset of securities). Only supported for IBKR databases.

-u, --universes

collect history for these universes, overriding config (typically used to collect a subset of securities). Only supported for IBKR databases.

-s, --start-date

collect history back to this start date, overriding config

-e, --end-date

collect history up to this end date, overriding config. Only supported for IBKR databases.

-p, --priority

use the priority queue (default is to use the standard queue). Only applicable to IBKR databases.

Default: False

Collect historical market data from a vendor and save it to a history database.

The vendor and collection parameters are determined by the stored database configuration as defined at the time the database was created. For certain vendors, collection parameters can be overridden at the time of data collection.

Examples:

Collect historical data for a database of Chinese stock prices:

quantrocket history collect china-1d

Collect historical data for an IBKR database of US futures, using the priority queue to jump in front of other queued IBKR collections:

quantrocket history collect globex-10m –priority

queue¶

get the current queue of historical data collections

quantrocket history queue [-h]

Get the current queue of historical data collections.

Examples:

quantrocket history queue

cancel¶

cancel running or pending historical data collections

quantrocket history cancel [-h] CODE [CODE ...]

Positional Arguments¶

CODE: the database code(s) to cancel collections for

Cancel running or pending historical data collections.

Examples:

Cancel collections for a database called japan-1d:

quantrocket history cancel japan-1d

wait¶

wait for historical data collection to finish

quantrocket history wait [-h] [-t TIMEDELTA] CODE [CODE ...]

Positional Arguments¶

CODE: the database code(s) to wait for

Named Arguments¶

-t, --timeout: time out if data collection hasn’t finished after this much time (use Pandas timedelta string, e.g. 30sec or 5min or 2h)

Wait for historical data collection to finish.

Examples:

Wait at most 10 minutes for data collection to finish for a database called ‘fx-1h’:

quantrocket history wait ‘fx-1h’ -t 10min

get¶

query historical market data from a history database and download to file

quantrocket history get [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                        [-u [UNIVERSE [UNIVERSE ...]]] [-i [SID [SID ...]]]
                        [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                        [--exclude-sids [SID [SID ...]]]
                        [-t [HH:MM:SS [HH:MM:SS ...]]] [-o OUTFILE] [-j]
                        [-f [FIELD [FIELD ...]]] [-c HOW]
                        CODE

Positional Arguments¶

CODE: the code of the database to query

filtering options¶

-s, --start-date: limit to history on or after this date
-e, --end-date: limit to history on or before this date
-u, --universes: limit to these universes
-i, --sids: limit to these sids
--exclude-universes: exclude these universes
--exclude-sids: exclude these sids
-t, --times: limit to these times

output options¶

-o, --outfile

filename to write the data to (default is stdout)

-j, --json

format output as JSON (default is CSV)

-f, --fields

only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

-c, --cont-fut

Possible choices: concat

stitch futures into continuous contracts using this method (default is not to stitch together). Possible choices: [‘concat’]

Query historical market data from a history database and download to file.

Examples:

Download a CSV of all historical market data since 2015 from a database called “arca-eod” to a file called arca.csv:

quantrocket history get arca-eod –start-date 2015-01-01 -o arca.csv

quantrocket.history.create_edi_db(code, exchanges)¶

Create a new database for collecting historical data from EDI.

Parameters

code (str, required) – the code to assign to the database (lowercase alphanumerics and hyphens only)
exchanges (list of str, required) – one or more exchange codes (MICs) which should be collected

Returns

status message

Return type

dict

quantrocket.history.create_ibkr_db(code, universes=None, sids=None, start_date=None, end_date=None, bar_size=None, bar_type=None, outside_rth=False, primary_exchange=False, times=None, between_times=None, shard=None)¶

Create a new database for collecting historical data from Interactive Brokers.

The historical data requirements you specify when you create a new database (bar size, universes, etc.) are applied each time you collect data for that database.

Parameters

code (str, required) – the code to assign to the database (lowercase alphanumerics and hyphens only)
universes (list of str) – include these universes
sids (list of str) – include these sids
start_date (str (YYYY-MM-DD), optional) – collect history back to this start date (default is to collect as far back as data is available)
end_date (str (YYYY-MM-DD), optional) – collect history up to this end date (default is to collect up to the present)
bar_size (str, required) – the bar size to collect. Possible choices: “1 secs”, “5 secs”, “10 secs”, “15 secs”, “30 secs”, “1 min”, “2 mins”, “3 mins”, “5 mins”, “10 mins”, “15 mins”, “20 mins”, “30 mins”, “1 hour”, “2 hours”, “3 hours”, “4 hours”, “8 hours”, “1 day”, “1 week”, “1 month”
bar_type (str, optional) – the bar type to collect (if not specified, defaults to MIDPOINT for FX and TRADES for everything else). Possible choices: “TRADES”, “ADJUSTED_LAST”, “MIDPOINT”, “BID”, “ASK”, “BID_ASK”, “HISTORICAL_VOLATILITY”, “OPTION_IMPLIED_VOLATILITY”
outside_rth (bool) – include data from outside regular trading hours (default is to limit to regular trading hours)
primary_exchange (bool) – limit to data from the primary exchange (default False)
times (list of str (HH:MM:SS), optional) – limit to these times (refers to the bar’s start time; mutually exclusive with between_times)
between_times (list of str (HH:MM:SS), optional) – limit to times between these two times (refers to the bar’s start time; mutually exclusive with times)
shard (str, optional) – whether and how to shard the database, i.e. break it into smaller pieces. Required for intraday databases. Possible choices are year (separate database for each year), month (separate database for each year+month), day (separate database for each day), time (separate database for each bar time), sid (separate database for each security), sid,time (duplicate copies of database, one sharded by sid and the other by time), or off (no sharding). See http://qrok.it/h/shard for more help.

Returns

status message

Return type

dict

quantrocket.history.create_sharadar_db(code, sec_type, country='US')¶

Create a new database for collecting historical data from Sharadar.

Parameters

code (str, required) – the code to assign to the database (lowercase alphanumerics and hyphens only)
sec_type (str, required) – the security type to collect. Possible choices: STK, ETF
country (str, required) – country to collect data for. Possible choices: US, FREE

Returns

status message

Return type

dict

quantrocket.history.create_usstock_db(code, bar_size=None, universe=None)¶

Create a new database for collecting historical US stock data from QuantRocket.

Parameters

code (str, required) – the code to assign to the database (lowercase alphanumerics and hyphens only)
bar_size (str, optional) – the bar size to collect. Possible choices: 1 day
universe (str, optional) – the universe to collect. Possible choices: US, FREE

Returns

status message

Return type

dict

Examples

Create a database for end-of-day US stock prices:

create_usstock_db(‘us-stk-1d’, bar_size=’1 day’)

quantrocket.history.get_db_config(code)¶

Return the configuration for a history database.

Parameters: code (str, required) – the database code
Returns: config
Return type: dict

quantrocket.history.drop_db(code, confirm_by_typing_db_code_again=None)¶

Delete a history database.

Deleting a history database deletes its configuration and data and is irreversible.

Parameters

code (str, required) – the database code
confirm_by_typing_db_code_again (str, required) – enter the db code again to confirm you want to drop the database, its config, and all its data

Returns

status message

Return type

dict

quantrocket.history.list_databases()¶

List history databases.

Returns: list of database codes
Return type: list

quantrocket.history.collect_history(codes, sids=None, universes=None, start_date=None, end_date=None, priority=False)¶

Collect historical market data from a vendor and save it to a history database.

Parameters

codes (list of str, required) – the database code(s) to collect data for
sids (list of str, optional) – collect history for these sids, overriding config (typically used to collect a subset of securities). Only supported for IBKR databases.
universes (list of str, optional) – collect history for these universes, overriding config (typically used to collect a subset of securities). Only supported for IBKR databases.
start_date (str (YYYY-MM-DD), optional) – collect history back to this start date, overriding config. Only supported for IBKR databases.
end_date (str (YYYY-MM-DD), optional) – collect history up to this end date, overriding config. Only supported for IBKR databases.
priority (bool) – use the priority queue (default is to use the standard queue). Only applicable to IBKR databases.

Returns

status message

Return type

dict

quantrocket.history.get_history_queue()¶

Get the current queue of historical data collections.

Returns: queue by vendor
Return type: dict

quantrocket.history.cancel_collections(codes)¶

Cancel running or pending historical data collections.

Parameters: codes (list of str, required) – the database code(s) to cancel collections for
Returns: queue by vendor
Return type: dict

quantrocket.history.wait_for_collections(codes, timeout=None)¶

Wait for historical data collection to finish.

Parameters

codes (list of str, required) – the database code(s) to wait for
timeout (str, optional) – time out if data collection hasn’t finished after this much time (use Pandas timedelta string, e.g. 30sec or 5min or 2h)

Returns

status message

Return type

dict

quantrocket.history.download_history_file(code, filepath_or_buffer=None, output='csv', start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, times=None, cont_fut=None, fields=None)¶

Query historical market data from a history database and download to file.

Parameters

code (str, required) – the code of the database to query
filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json, csv, default is csv)
start_date (str (YYYY-MM-DD), optional) – limit to history on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to history on or before this date
universes (list of str, optional) – limit to these universes (default is to return all securities in database)
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
times (list of str (HH:MM:SS), optional) – limit to these times
cont_fut (str) – stitch futures into continuous contracts using this method (default is not to stitch together). Possible choices: concat
fields (list of str, optional) – only return these fields (pass [‘?’] or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

You can use StringIO to load the CSV into pandas.

>>> f = io.StringIO()
>>> download_history_file("my-db", f)
>>> history = pd.read_csv(f, parse_dates=["Date"])

See also

quantrocket.get_prices(): load prices into a DataFrame

Historical Data API

Resource Group ¶

Database ¶

Create History Database
PUT`/history/databases/{code}{?universes,exchanges,sec_type,country,universe,start_date,end_date,vendor,bar_size,bar_type,outside_rth,primary_exchange,times,between_times,shard}`

Create a new history database.

Not all parameters are applicable to all vendors. Please see the Python API reference to determine which parameters are applicable to which vendors.

Example URI

PUT http://houston/history/databases/japan-bank-eod?universes=japan-bank&exchanges=XNYS&sec_type=STK&country=US&universe=US&start_date=2010-06-01&end_date=2019-06-30&vendor=usstock&bar_size=1 day&bar_type=TRADES&outside_rth=false&primary_exchange=true&times=09:29:50&between_times=09:30:00&shard=off

URI Parameters

code

str (required) Example: japan-bank-eod

the code to assign to the database (lowercase alphanumerics and hyphens only)

universes

str (optional) Example: japan-bank

include these universes (pass multiple times for multiple universes)

exchanges

str (optional) Example: XNYS

exchange code (MICs) which should be collected (pass multiple times for multiple exchanges)

country

str (optional) Example: US

country to collect data for

Choices: US FREE

sec_type

str (optional) Example: STK

the security type to collect

Choices: STK ETF

universe

str (optional) Example: US

the universe to collect

Choices: US FREE

start_date

str (optional) Example: 2010-06-01

collect history back to this start date (default is to collect as far back as data is available)

end_date

str (optional) Example: 2019-06-30

collect history up to this end date (default is to collect up to the present)

vendor

str (required) Example: usstock

the vendor to collect data from

Choices: edi ibkr sharadar usstock

bar_size

str (optional) Example: 1 day

the bar size to collect

Choices: 1 secs 5 secs 10 secs 15 secs 30 secs 1 min 2 mins 3 mins 5 mins 10 mins 15 mins 20 mins 30 mins 1 hour 2 hours 3 hours 4 hours 8 hours 1 day 1 week 1 month

bar_type

str (optional) Example: TRADES

the bar type to collect

Choices: TRADES ADJUSTED_LAST MIDPOINT BID ASK BID_ASK HISTORICAL_VOLATILITY OPTION_IMPLIED_VOLATILITY

outside_rth

bool (required) Example: false

include data from outside regular trading hours (default is to limit to regular trading hours)

primary_exchange

bool (required) Example: true

limit to data from the primary exchange (default False)

times

str (optional) Example: 09:29:50

limit to these times (pass multiple times for multiple times)

between_times

str (optional) Example: 09:30:00

limit to times between these two times (refers to the bar’s start time; mutually exclusive with times; should be passed exactly twice, once for start time and once for end time)

shard

str (optional) Example: off

whether and how to shard the database, i.e. break it into smaller pieces. Required for intraday databases. Possible choices are year (separate database for each year), month (separate database for each year+month), day (separate database for each day), time (separate database for each bar time), sid (separate database for each security), sid,time (duplicate copies of database, one sharded by sid and the other by time), or off (no sharding). See http://qrok.it/h/shard for more help.

Choices: year month day sid time off

Response 200

Headers

Content-Type: application/json

Body

{
  "status": "successfully created quantrocket.v2.history.japan-bank-eod.sqlite"
}

Get History Database Config
GET`/history/databases/{code}`

Return the configuration for a history database.

Example URI

GET http://houston/history/databases/japan-bank-eod

URI Parameters

code: str (required) Example: japan-bank-eod
the database code

Response 200

Headers

Content-Type: application/json

Body

{
  "universes": [
    "japan-bank"
  ],
  "start_date": "2010-06-01",
  "vendor": "ibkr",
  "bar_size": "1 day",
  "bar_type": "TRADES",
  "primary_exchange": true,
  "times": [
    "09:29:50"
  ]
}

Delete History Database
DELETE`/history/databases/{code}{?confirm_by_typing_db_code_again}`

Delete a history database.

Example URI

DELETE http://houston/history/databases/japan-bank-eod?confirm_by_typing_db_code_again=japan-bank-eod

URI Parameters

code: str (required) Example: japan-bank-eod
the database code
confirm_by_typing_db_code_again: str (required) Example: japan-bank-eod
enter the db code again to confirm you want to drop the database, its config, and all its data

Response 200

Headers

Content-Type: application/json

Body

{
  "status": "deleted quantrocket.v2.history.japan-bank-eod.sqlite"
}

Databases ¶

List History Databases
GET`/history/databases`

List history databases.

Example URI

GET http://houston/history/databases

Response 200

Headers

Content-Type: application/json

Body

[
  "demo-stk-1d",
  "usa-stk-15min"
]

Historical Data Queue ¶

Collect Historical Data
POST`/history/queue{?codes,priority,sids,universes,start_date,end_date}`

Collect historical market data from a vendor and save it to a history database.

Example URI

POST http://houston/history/queue?codes=japan-bank-eod&priority=false&sids=FI12345&universes=japan-bank&start_date=2016-06-01&end_date=2019-06-30

URI Parameters

codes: str (required) Example: japan-bank-eod
the database code(s) to collect data for (pass multiple times for multiple codes)
sids: str (optional) Example: FI12345
collect history for these sids, overriding config (typically used to collect a subset of securities) (pass multiple times for multiple sids)
universes: str (optional) Example: japan-bank
collect history for these universes, overriding config (typically used to collect a subset of securities) (pass multiple times for multiple universes)
start_date: str (optional) Example: 2016-06-01
collect history back to this start date, overriding config
end_date: str (optional) Example: 2019-06-30
collect history up to this end date, overriding config
priority: bool (optional) Example: false
use the priority queue (default is to use the standard queue). Only applicable to IBKR databases.

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the historical data will be collected asynchronously"
}

Get History Data Queue
GET`/history/queue`

Get the current queue of historical data collections.

Example URI

GET http://houston/history/queue

Response 200

Headers

Content-Type: application/json

Cancel Historical Data Collection
DELETE`/history/queue{?codes}`

Cancel running or pending historical data collections.

Example URI

DELETE http://houston/history/queue?codes=japan-bank-eod

URI Parameters

codes: str (required) Example: japan-bank-eod
the database code(s) to cancel collections for (pass multiple times for multiple codes)

Response 200

Headers

Content-Type: application/json

Wait for Historical Data Collection
PUT`/history/queue{?codes,timeout}`

Wait for historical data collection to finish.

Example URI

PUT http://houston/history/queue?codes=japan-bank-eod&timeout=30sec

URI Parameters

codes: str (required) Example: japan-bank-eod
the database code(s) to wait for (pass multiple times for multiple codes)
timeout: str (optional) Example: 30sec
time out if data collection hasn’t finished after this much time (use Pandas timedelta string, e.g. 30sec or 5min or 2h)

Response 200

Headers

Content-Type: application/json

Historical Market Data ¶

Query Historical Data
GET`/history/{code}.{filetype}{?start_date,end_date,universes,sids,exclude_universes,exclude_sids,times,cont_fut,fields}`

Query historical market data from a history database and download to file.

Example URI

GET http://houston/history/japan-bank-eod.csv?start_date=2016-06-01&end_date=2017-06-01&universes=japan-bank&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456&times=09:29:50&cont_fut=concat&fields=Close

URI Parameters

code

str (required) Example: japan-bank-eod

the code of the database to query

filetype

str (required) Example: csv

output format

Choices: csv json

start_date

str (optional) Example: 2016-06-01

limit to history on or after this date

end_date

str (optional) Example: 2017-06-01

limit to history on or before this date

universes

str (optional) Example: japan-bank

limit to these universes (default is to return all securities in database) (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

times

str (optional) Example: 09:29:50

limit to these times (pass multiple times for multiple times)

cont_fut

str (optional) Example: concat

stitch futures into continuous contracts using this method (default is not to stitch together)

Choices: concat

fields

str (optional) Example: Close

only return these fields

Response 200

Headers

Content-Type: text/csv

Body

Sid,Date,Close
FI1715006,2017-01-27,48.65
FI1715006,2017-01-30,47.67
FI1715006,2017-01-31,48.97
FI1715006,2017-02-01,49.26

quantrocket.houston

Houston API gateway

QuantRocket Houston API Gateway CLI

usage: quantrocket houston [-h] {ping} ...

subcommands¶

subcommand: Possible choices: ping

Sub-commands:¶

ping¶

ping houston

quantrocket houston ping [-h]

Ping houston.

Examples:

quantrocket houston ping

class quantrocket.houston.Houston¶

Subclass of requests.Session that provides an interface to the houston API gateway. Reads HOUSTON_URL (and Basic Auth credentials if applicable) from environment variables and applies them to each request. Simply provide the path, starting with /, for example:

>>> response = houston.get("/countdown/crontab")

Since each instance of Houston is a session, you can improve performance by using a single session for all requests. The module provides an instance of Houston, named houston.

Use the same session as other requests:

>>> from quantrocket.houston import houston

Use a new session:

>>> from quantrocket.houston import Houston
>>> houston = Houston()

quantrocket.houston.ping()¶

Pings houston.

Returns: reply from houston
Return type: json

Houston API

Only the ping endpoint and generic proxy endpoints are documented below. For service-specific endpoints, see the respective service documentation.

Resource Group ¶

Ping ¶

Ping
GET`/ping`

Ping houston to test connectivity.

Example URI

GET http://houston/ping

Response 200

Headers

Content-Type: application/json

Body

{
  "msg": "hello from houston"
}

HTTP Proxy ¶

HTTP Proxy
GET`/proxy/http/{service_name}/{port}/{path}`

Use houston as a reverse proxy to a destination service speaking HTTP. Only GET is shown but the same signature applies for any HTTP method.

Example URI

GET http://houston/proxy/http/myservice/80/my/endpoint

URI Parameters

service_name: str (required) Example: myservice
the destination service name/host name
port: int (required) Example: 80
the destination port
path: str (required) Example: my/endpoint
the request path on the destination host

uWSGI Proxy ¶

uWSGI Proxy
GET`/proxy/uwsgi/{service_name}/{port}/{path}`

Use houston as a reverse proxy to a destination service speaking the uWSGI protocol. Only GET is shown but the same signature applies for any HTTP method.

Example URI

GET http://houston/proxy/uwsgi/myservice/80/my/endpoint

URI Parameters

service_name: str (required) Example: myservice
the destination service name/host name
port: int (required) Example: 80
the destination port
path: str (required) Example: my/endpoint
the request path on the destination host

quantrocket.ibg

IB Gateway service

QuantRocket IB Gateway service CLI

usage: quantrocket ibg [-h] {credentials,status,start,stop,config} ...

subcommands¶

subcommand: Possible choices: credentials, status, start, stop, config

Sub-commands:¶

credentials¶

set username/password and trading mode (paper/live) for IB Gateway

quantrocket ibg credentials [-h] [-u USERNAME] [-p PASSWORD]
                            [--paper | --live]
                            SERVICE_NAME

Positional Arguments¶

SERVICE_NAME: name of IB Gateway service to set credentials for (for example, ‘ibg1’)

Named Arguments¶

-u, --username: IBKR username (optional if only modifying trading mode)
-p, --password: IBKR password (if omitted and user is provided, will be prompted for password)
--paper: set trading mode to paper trading
--live: set trading mode to live trading

Set username/password and trading mode (paper/live) for IB Gateway, or view current username and trading mode.

Can be used to set new credentials or switch between paper and live trading (must have previously entered live credentials). Setting new credentials will restart IB Gateway and takes a moment to complete.

Credentials are encrypted at rest and never leave your deployment.

Examples:

View current credentials for IB Gateway service named ibg1 (shows username and trading mode only):

quantrocket ibg credentials ibg1

Set credentials for ibg1 (will prompt for password):

quantrocket ibg credentials ibg1 -u myuser –paper

Leave credentials as-is but switch to live trading (must have previously entered live credentials):

quantrocket ibg credentials ibg1 –live

status¶

query statuses of IB Gateways

quantrocket ibg status [-h] [-s {running,stopped,error}]
                       [-g [SERVICE_NAME [SERVICE_NAME ...]]]

Named Arguments¶

-s, --status

Possible choices: running, stopped, error

limit to IB Gateways in this status. Possible choices: [‘running’, ‘stopped’, ‘error’]

-g, --gateways

limit to these IB Gateways

Query statuses of IB Gateways.

Examples:

List the status of all gateways:

quantrocket ibg status

Get a list of gateways that are running:

quantrocket ibg status –status running

start¶

start one or more IB Gateways

quantrocket ibg start [-h] [-g [SERVICE_NAME [SERVICE_NAME ...]]] [-w]

Named Arguments¶

-g, --gateways

limit to these IB Gateways

-w, --wait

wait for the IB Gateway to start before returning (default is to start the gateways asynchronously)

Default: False

Start one or more IB Gateways.

Examples:

Asynchronously start all gateways (that aren’t already running):

quantrocket ibg start

Start specific gateways and wait for them to come up:

quantrocket ibg start –gateways ibg1 ibg3 –wait

Restart all gateways:

quantrocket ibg stop –wait && quantrocket ibg start

stop¶

stop one or more IB Gateways

quantrocket ibg stop [-h] [-g [SERVICE_NAME [SERVICE_NAME ...]]] [-w]

Named Arguments¶

-g, --gateways

limit to these IB Gateways

-w, --wait

wait for the IB Gateway to stop before returning (default is to stop the gateways asynchronously)

Default: False

Stop one or more IB Gateways.

Examples:

Stop all gateways (that aren’t already stopped):

quantrocket ibg stop

Stop specific gateways and wait for them to stop:

quantrocket ibg stop –gateways ibg1 ibg3 –wait

config¶

upload a new config, or return the current configuration

quantrocket ibg config [-h] [FILENAME]

Positional Arguments¶

FILENAME: the config file to upload (if omitted, return the current config)

Upload a new IB Gateway permissions config, or return the current configuration.

Permission configs are only necessary when running multiple IB Gateways with differing market data permissions.

Examples:

Upload a new config (replaces current config):

quantrocket ibg config myconfig.yml

Show current config:

quantrocket ibg config

quantrocket.ibg.get_credentials(gateway)¶

Returns username and trading mode (paper/live) for IB Gateway.

Parameters: gateway (str, required) – name of IB Gateway service to get credentials for (for example, ‘ibg1’)
Returns: credentials
Return type: dict

quantrocket.ibg.set_credentials(gateway, username=None, password=None, trading_mode=None)¶

Set username/password and trading mode (paper/live) for IB Gateway.

Credentials are encrypted at rest and never leave your deployment.

Parameters

gateway (str, required) – name of IB Gateway service to set credentials for (for example, ‘ibg1’)
username (str, optional) – IBKR username (optional if only modifying trading environment)
password (str, optional) – IBKR password (if omitted and username is provided, will be prompted for password)
trading_mode (str, optional) – the trading mode to use (‘paper’ or ‘live’)

Returns

status message

Return type

dict

quantrocket.ibg.list_gateway_statuses(status=None, gateways=None)¶

Query statuses of IB Gateways.

Parameters

status (str, optional) – limit to IB Gateways in this status. Possible choices: running, stopped, error
gateways (list of str, optional) – limit to these IB Gateways

Returns

dict of gateway

Return type

status (if status arg not provided), or list of gateways (if status arg provided)

quantrocket.ibg.start_gateways(gateways=None, wait=False)¶

Start one or more IB Gateways.

Parameters

gateways (list of str, optional) – limit to these IB Gateways
wait (bool) – wait for the IB Gateway to start before returning (default is to start the gateways asynchronously)

Returns

status message

Return type

dict

quantrocket.ibg.stop_gateways(gateways=None, wait=False)¶

Stop one or more IB Gateways.

Parameters

gateways (list of str, optional) – limit to these IB Gateways
wait (bool) – wait for the IB Gateway to stop before returning (default is to stop the gateways asynchronously)

Returns

status message

Return type

dict

quantrocket.ibg.load_ibg_config(filename)¶

Upload a new IB Gateway permissions config.

Permission configs are only necessary when running multiple IB Gateways with differing market data permissions.

Parameters: filename (str, required) – the config file to upload
Returns: status message
Return type: dict

quantrocket.ibg.get_ibg_config()¶

Returns the current IB Gateway permissions config.

Returns: the config as a dict
Return type: dict

IB Gateway API

Resource Group ¶

IB Gateway Credentials ¶

Set IB Credentials
PUT`/{gateway}/credentials{?username,password,trading_mode}`

Set IB username/password and trading mode (paper/live) for IB Gateway.

Credentials are encrypted at rest and never leave your deployment.

Example URI

PUT http://houston/ibg1/credentials?username=XXXXXXXXX&password=XXXXXXXXX&trading_mode=paper

URI Parameters

gateway

str (required) Example: ibg1

name of IB Gateway service to set credentials for

username

str (optional) Example: XXXXXXXXX

IB username (optional if only modifying trading environment)

password

str (optional) Example: XXXXXXXXX

IB password (optional if only modifying trading environment)

trading_mode

str (optional) Example: paper

the trading mode to use

Choices: paper live

Response 200

Headers

Content-Type: application/json

Get IB Gateway Credentials
GET`/{gateway}/credentials`

Returns IB username and trading mode (paper/live) for IB Gateway.

Example URI

GET http://houston/ibg1/credentials

URI Parameters

gateway: str (required) Example: ibg1
name of IB Gateway service to get credentials for

Response 200

Headers

Content-Type: application/json

Body

{
    "TWSUSERID": "XXXXXXXXX",
    "TRADING_MODE": "paper",
}

IB Gateway ¶

List Gateways
GET`/ibgrouter/gateways{?statuses,gateways}`

Query statuses of IB Gateways.

Example URI

GET http://houston/ibgrouter/gateways?statuses=running&gateways=ibg1

URI Parameters

statuses

str (optional) Example: running

limit to IB Gateway services in this status (pass multiple times for multiple statuses)

Choices: running stopped error

gateways

str (optional) Example: ibg1

limit to these IB Gateway services (pass multiple times for multiple gateways)

Response 200

Headers

Content-Type: application/json

Body

{
  "ibg1": "running",
  "ibg2": "stopped"
}

Start Gateways
POST`/ibgrouter/gateways{?gateways,wait}`

Start IB Gateway services

Example URI

POST http://houston/ibgrouter/gateways?gateways=ibg1&wait=true

URI Parameters

gateways: str (optional) Example: ibg1
limit to these IB Gateway services (pass multiple times for multiple gateways)
wait: bool (required) Example: true
wait for the IB Gateway services to start before returning (default is to start the gateways asynchronously)

Response 200

Headers

Content-Type: application/json

Body

{
  "ibg1": {
    "status": "running"
  },
  "ibg2": {
    "status": "running"
  }
}

Stop Gateways
DELETE`/ibgrouter/gateways{?gateways,wait}`

Stop IB Gateway services

Example URI

DELETE http://houston/ibgrouter/gateways?gateways=ibg1&wait=true

URI Parameters

gateways: str (optional) Example: ibg1
limit to these IB Gateway services (pass multiple times for multiple gateways)
wait: bool (required) Example: true
wait for the IB Gateway services to stop before returning (default is to stop the gateways asynchronously)

Response 200

Headers

Content-Type: application/json

Body

{
  "ibg1": {
    "status": "stopped"
  },
  "ibg2": {
    "status": "stopped"
  }
}

IB Gateway Config ¶

Get Config
GET`/ibgrouter/config`

Returns the current IB Gateway permissions config.

Example URI

GET http://houston/ibgrouter/config

Response 200

Headers

Content-Type: application/json

Body

{
  "ibg1": {
    "marketdata": {
      "STK": [
        "ASX",
        "ISLAND",
        "NYSE",
        "TSE"
      ]
    },
    "research": [
      "wsh"
    ]
  },
  "ibg2": {
    "marketdata": {
      "STK": [
        "ISLAND",
        "NYSE"
      ],
      "FUT": [
        "GLOBEX"
      ]
    }
  }
}

Load Config
PUT`/ibgrouter/config`

Upload a new IB Gateway permissions config.

Permission configs are only necessary when running multiple IB Gateways with differing market data permissions.

Example URI

PUT http://houston/ibgrouter/config

Request

Headers

Content-Type: application/x-yaml

Body

ibg1:
marketdata:
    STK:
    - ASX
    - ISLAND
    - NYSE
    - TSE
ibg2:
marketdata:
    STK:
    - ISLAND
    - TSEJ

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the config will be loaded asynchronously"
}

quantrocket.license

license service

QuantRocket license service CLI

usage: quantrocket license [-h]
                           {get,set,alpaca-key,polygon-key,quandl-key} ...

subcommands¶

subcommand: Possible choices: get, set, alpaca-key, polygon-key, quandl-key

Sub-commands:¶

get¶

return the current license profile

quantrocket license get [-h] [--force-refresh]

Named Arguments¶

--force-refresh

refresh the license profile before returning it (default is to return the cached profile, which is refreshed every few minutes)

Default: False

Return the current license profile.

Examples:

View the current license profile:

quantrocket license get

set¶

set QuantRocket license key

quantrocket license set [-h] LICENSEKEY

Positional Arguments¶

LICENSEKEY: the license key for your account

Set QuantRocket license key.

Examples:

quantrocket license set XXXXXXXXXX

alpaca-key¶

set Alpaca API key, or view the current API key

quantrocket license alpaca-key [-h] [-a API_KEY] [-s SECRET_KEY]
                               [--paper | --live]

Named Arguments¶

-a, --api-key: Alpaca API key ID
-s, --secret-key: Alpaca secret key (if omitted, will be prompted for secret key)
--paper: set trading mode to paper trading
--live: set trading mode to live trading

Set Alpaca API key, or view the current API key.

Your credentials are encrypted at rest and never leave your deployment.

Examples:

View current live and paper API keys:

quantrocket license alpaca-key

Set Alpaca live API key (will prompt for secret key):

quantrocket license alpaca-key –api-key AK123 –live

Set Alpaca paper API key (will prompt for secret key):

quantrocket license alpaca-key –api-key PK123 –paper

polygon-key¶

set Polygon API key, or view the current API key

quantrocket license polygon-key [-h] [API_KEY]

Positional Arguments¶

API_KEY: Polygon API key

Set Polygon API key, or view the current API key.

Your credentials are encrypted at rest and never leave your deployment.

Examples:

View current API key:

quantrocket license polygon-key

Set Polygon API key:

quantrocket license polygon-key K123

quandl-key¶

set Quandl API key, or view the current API key

quantrocket license quandl-key [-h] [API_KEY]

Positional Arguments¶

API_KEY: Quandl API key

Set Quandl API key, or view the current API key.

Your credentials are encrypted at rest and never leave your deployment.

Examples:

View current API key:

quantrocket license quandl-key

Set Polygon API key:

quantrocket license quandl-key K123

quantrocket.license.get_license_profile(force_refresh=False)¶

Return the current license profile.

Parameters: force_refresh (bool) – refresh the license profile before returning it (default is to return the cached profile, which is refreshed every few minutes)
Returns: license profile
Return type: dict

quantrocket.license.set_license(key)¶

Set QuantRocket license key.

Parameters: key (str, required) – the license key for your account
Returns: license profile
Return type: dict

quantrocket.license.get_alpaca_key()¶

Returns the current API key(s) for Alpaca.

Returns: credentials
Return type: dict

quantrocket.license.set_alpaca_key(api_key, trading_mode, secret_key=None)¶

Set Alpaca API key.

Your credentials are encrypted at rest and never leave your deployment.

Parameters

api_key (str, required) – Alpaca API key ID
trading_mode (str, required) – the trading mode of this API key (‘paper’ or ‘live’)
secret_key (str, optional) – Alpaca secret key (if omitted, will be prompted for secret key)

Returns

status message

Return type

dict

quantrocket.license.get_polygon_key()¶

Returns the current API key for Polygon.

Returns: credentials
Return type: dict

quantrocket.license.set_polygon_key(api_key)¶

Set Polygon API key.

Your credentials are encrypted at rest and never leave your deployment.

Parameters: api_key (str, required) – Polygon API key
Returns: status message
Return type: dict

quantrocket.license.get_quandl_key()¶

Returns the current API key for Quandl.

Returns: credentials
Return type: dict

quantrocket.license.set_quandl_key(api_key)¶

Set Quandl API key.

Your credentials are encrypted at rest and never leave your deployment.

Parameters: api_key (str, required) – Quandl API key
Returns: status message
Return type: dict

License API

Resource Group ¶

License Profile ¶

Get License Profile
GET`/license-service/license/{?force_refresh}`

Return the current license profile.

Example URI

GET http://houston/license-service/license/?force_refresh=false

URI Parameters

force_refresh: bool (optional) Example: false
refresh the license profile before returning it (default is to return the cached profile, which is refreshed every few minutes)

Response 200

Headers

Content-Type: application/json

Body

{
  "licensekey": "XXXXXXXXXX",
  "software_license": {
    "use_case": "Individual Non-Professional",
    "user_limit": 1,
    "concurrent_install_limit": 2,
    "account": {
      "account_limit": "1000000 USD"
    }
  }
}

Set License Profile
PUT`/license-service/license/{key}`

Set QuantRocket license key.

Example URI

PUT http://houston/license-service/license/XXXXXXXX

URI Parameters

key: str (required) Example: XXXXXXXX
the license key for your account

Response 200

Headers

Content-Type: application/json

Body

{
  "licensekey": "XXXXXXXXXX",
  "software_license": {
    "use_case": "Individual Non-Professional",
    "user_limit": 1,
    "concurrent_install_limit": 2,
    "account": {
      "account_limit": "1000000 USD"
    }
  }
}

Third-Party API Key ¶

Get API Key
GET`/license-service/credentials/{vendor}`

Returns the current API key for a third-party provider.

Example URI

GET http://houston/license-service/credentials/alpaca

URI Parameters

vendor

str (required) Example: alpaca

the vendor to return credentials for

Choices: alpaca polygon quandl

Response 200

Headers

Content-Type: application/json

Set API Key
PUT`/license-service/credentials/{vendor}{?api_key,secret_key,trading_mode}`

Set API key for a third-party provider.

Your credentials are encrypted at rest and never leave your deployment.

Example URI

PUT http://houston/license-service/credentials/alpaca?api_key=XXXXXXXX&secret_key=ZZZZZZZZZZ&trading_mode=paper

URI Parameters

vendor

str (required) Example: alpaca

the vendor to set credentials for

Choices: alpaca polygon quandl

api_key

str (required) Example: XXXXXXXX

the third-party API key

secret_key

str (optional) Example: ZZZZZZZZZZ

the third-party secret key, if applicable

trading_mode

str (optional) Example: paper

the trading mode, if applicable

Response 200

Headers

Content-Type: application/json

quantrocket.master

securities master service

QuantRocket securities master CLI

usage: quantrocket master [-h]
                          {collect-alpaca,collect-edi,collect-figi,collect-ibkr,collect-sharadar,collect-usstock,collect-ibkr-options,get,list-ibkr-exchanges,diff-ibkr,delist-ibkr,list-universes,universe,delete-universe,create-ibkr-combo,rollrules,collect-ibkr-calendar,calendar,isopen,isclosed,ticksize}
                          ...

subcommands¶

subcommand: Possible choices: collect-alpaca, collect-edi, collect-figi, collect-ibkr, collect-sharadar, collect-usstock, collect-ibkr-options, get, list-ibkr-exchanges, diff-ibkr, delist-ibkr, list-universes, universe, delete-universe, create-ibkr-combo, rollrules, collect-ibkr-calendar, calendar, isopen, isclosed, ticksize

Sub-commands:¶

collect-alpaca¶

collect securities listings from Alpaca and store in securities master database

quantrocket master collect-alpaca [-h]

Collect securities listings from Alpaca and store in securities master database.

Examples:

quantrocket master collect-alpaca

collect-edi¶

collect securities listings from EDI and store in securities master database

quantrocket master collect-edi [-h] [-e [MIC [MIC ...]]]

Named Arguments¶

-e, --exchanges: collect listings for these exchanges (identified by MICs)

Collect securities listings from EDI and store in securities master database.

Examples:

Collect sample listings:

quantrocket master collect-edi –exchanges FREE

Collect listings for all permitted exchanges

quantrocket master collect-edi

Collect all Chinese stock listings:

quantrocket master collect-edi -e XSHG XSHE

collect-figi¶

collect securities listings from Bloomberg OpenFIGI and store in securities master database

quantrocket master collect-figi [-h]

Collect securities listings from Bloomberg OpenFIGI and store in securities master database.

OpenFIGI provides several useful security attributes including market sector, a detailed security type, and share class-level FIGI identifier.

The collected data fields show up in the master file under the prefix “figi_*”.

This command does not directly query the OpenFIGI API but rather downloads a dump of all FIGIs which QuantRocket has previously mapped to securities from other vendors.

Examples:

quantrocket master collect-figi

collect-ibkr¶

collect securities listings from Interactive Brokers and store in securities master database

quantrocket master collect-ibkr [-h] [-e [EXCHANGE [EXCHANGE ...]]]
                                [-t [SEC_TYPE [SEC_TYPE ...]]]
                                [-c [CURRENCY [CURRENCY ...]]]
                                [-s [SYMBOL [SYMBOL ...]]]
                                [-u [UNIVERSE [UNIVERSE ...]]]
                                [-i [SID [SID ...]]]

Named Arguments¶

-e, --exchanges

one or more exchange codes to collect listings for (required unless providing universes or sids). For sample data use exchange code ‘FREE’

-t, --sec-types

Possible choices: STK, ETF, FUT, CASH, IND

limit to these security types. Possible choices: [‘STK’, ‘ETF’, ‘FUT’, ‘CASH’, ‘IND’]

-c, --currencies

limit to these currencies

-s, --symbols

limit to these symbols

-u, --universes

limit to these universes

-i, --sids

limit to these sids

Collect securities listings from Interactive Brokers and store in securities master database.

Specify an exchange (optionally filtering by security type, currency, and/or symbol) to collect listings from the IBKR website and collect associated contract details from the IBKR API. Or, specify universes or sids to collect details from the IBKR API, bypassing the website.

Examples:

Collect free sample listings:

quantrocket master collect-ibkr –exchanges FREE

Collect all Toronto Stock Exchange stock listings:

quantrocket master collect-ibkr –exchanges TSE –sec-types STK

Collect all NYSE ARCA ETF listings:

quantrocket master collect-ibkr -e ARCA –sec-types ETF

Collect specific symbols from Nasdaq:

quantrocket master collect-ibkr -e NASDAQ –symbols AAPL GOOG NFLX

Re-collect contract details for an existing universe called “japan-fin”:

quantrocket master collect-ibkr –universes japan-fin

collect-sharadar¶

collect securities listings from Sharadar and store in securities master database

quantrocket master collect-sharadar [-h] [-c [COUNTRY [COUNTRY ...]]]

Named Arguments¶

-c, --countries

Possible choices: US, FREE

collect listings for these countries. Possible choices: [‘US’, ‘FREE’]

Default: [‘US’]

Collect securities listings from Sharadar and store in securities master database.

Examples:

Collect sample listings:

quantrocket master collect-sharadar –countries FREE

Collect all US listings:

quantrocket master collect-sharadar –countries US

collect-usstock¶

collect US stock listings from QuantRocket and store in securities master database

quantrocket master collect-usstock [-h]

Collect US stock listings from QuantRocket and store in securities master database.

Examples:

quantrocket master collect-usstock

collect-ibkr-options¶

collect IBKR option chains for underlying securities

quantrocket master collect-ibkr-options [-h] [-u [UNIVERSE [UNIVERSE ...]]]
                                        [-i [SID [SID ...]]] [-f INFILE]

Named Arguments¶

-u, --universes: collect options for these universes of underlying securities
-i, --sids: collect options for these underlying sids
-f, --infile: collect options for the sids in this file (specify ‘-‘ to read file from stdin)

Collect IBKR option chains for underlying securities.

Note: option chains often consist of hundreds, sometimes thousands of options per underlying security. Be aware that requesting option chains for large universes of underlying securities, such as all stocks on the NYSE, can take numerous hours to complete.

Examples:

Collect option chains for several underlying securities:

quantrocket master collect-ibkr-options –sids FIBBG000LV0836 FIBBG000B9XRY4

Collect option chains for NQ futures:

quantrocket master get -e GLOBEX -s NQ -t FUT | quantrocket master collect-ibkr-options -f -

Collect option chains for a large universe of stocks called “nyse-stk” (see note above):

quantrocket master collect-ibkr-options -u “nyse-stk”

get¶

query security details from the securities master database and download to file

quantrocket master get [-h] [-e [EXCHANGE [EXCHANGE ...]]]
                       [-t [SEC_TYPE [SEC_TYPE ...]]]
                       [-c [CURRENCY [CURRENCY ...]]]
                       [-u [UNIVERSE [UNIVERSE ...]]]
                       [-s [SYMBOL [SYMBOL ...]]] [-i [SID [SID ...]]]
                       [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                       [--exclude-sids [SID [SID ...]]] [--exclude-delisted]
                       [--exclude-expired] [-m] [-v [VENDOR [VENDOR ...]]]
                       [-o OUTFILE] [-j] [-f [FIELD [FIELD ...]]]

filtering options¶

-e, --exchanges

limit to these exchanges. You can specify exchanges using the MIC or the vendor’s exchange code.

-t, --sec-types

Possible choices: STK, ETF, FUT, CASH, IND, OPT, FOP, BAG

limit to these security types. Possible choices: [‘STK’, ‘ETF’, ‘FUT’, ‘CASH’, ‘IND’, ‘OPT’, ‘FOP’, ‘BAG’]

-c, --currencies

limit to these currencies

-u, --universes

limit to these universes

-s, --symbols

limit to these symbols

-i, --sids

limit to these sids

--exclude-universes

exclude these universes

--exclude-sids

exclude these sids

--exclude-delisted

exclude delisted securities (default is to include them)

Default: False

--exclude-expired

exclude expired contracts (default is to include them)

Default: False

-m, --frontmonth

exclude backmonth and expired futures contracts

Default: False

-v, --vendors

Possible choices: alpaca, edi, ibkr, sharadar, usstock

limit to these vendors. Possible choices: [‘alpaca’, ‘edi’, ‘ibkr’, ‘sharadar’, ‘usstock’]

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)
-f, --fields: return specific fields. By default a core set of fields is returned, but additional vendor-specific fields are also available. To return non-core fields, you can reference them by name, or pass “*” to return all available fields. To return all fields for a specific vendor, pass the vendor prefix followed by “*”, for example “edi*” for all EDI fields. Pass “?*” (or any invalid vendor prefix plus “*”) to see available vendor prefixes. Pass “?” or any invalid fieldname to see all available fields.

Query security details from the securities master database and download to file.

Examples:

Download NYSE and NASDAQ securities to file, using MICs to specify the exchanges:

quantrocket master get –exchanges XNYS XNAS -o securities.csv

Download NYSE and NASDAQ securities to file, using IBKR exchange codes to specify the exchanges, and include all IBKR fields:

quantrocket master get –exchanges NYSE NASDAQ -f ‘ibkr*’ -o securities.csv

Download a CSV of all ARCA ETFs and use it to create a universe called “arca-etf”:

quantrocket master get –exchanges ARCA –sec-types ETF | quantrocket master universe “arca-etf” –infile -

Query the exchange and currency for all listings of AAPL and format for terminal display:

quantrocket master get –symbols AAPL –fields Exchange Currency | csvlook -I

list-ibkr-exchanges¶

list exchanges by security type and country as found on the IBKR website

quantrocket master list-ibkr-exchanges [-h] [-r [REGION [REGION ...]]]
                                       [-t [SEC_TYPE [SEC_TYPE ...]]]

Named Arguments¶

-r, --regions

Possible choices: north_america, europe, asia, global

limit to these regions. Possible choices: [‘north_america’, ‘europe’, ‘asia’, ‘global’]

-t, --sec-types

Possible choices: STK, ETF, FUT, CASH, IND

limit to these security types. Possible choices: [‘STK’, ‘ETF’, ‘FUT’, ‘CASH’, ‘IND’]

List exchanges by security type and country as found on the IBKR website.

Examples:

List all exchanges:

quantrocket master list-ibkr-exchanges

List stock exchanges in North America:

quantrocket master list-ibkr-exchanges –regions north_america –sec-types STK

diff-ibkr¶

flag security details that have changed in IBKR’s system since the time they were last collected into the securities master database

quantrocket master diff-ibkr [-h] [-u [UNIVERSE [UNIVERSE ...]]]
                             [-i [SID [SID ...]]] [-n INFILE]
                             [-f [FIELD [FIELD ...]]] [--delist-missing]
                             [--delist-exchanges [EXCHANGE [EXCHANGE ...]]]
                             [-w]

Named Arguments¶

-u, --universes

limit to these universes

-i, --sids

limit to these sids

-n, --infile

limit to the sids in this file (specify ‘-‘ to read file from stdin)

-f, --fields

only diff these fields (field name should start with ‘ibkr’)

--delist-missing

auto-delist securities that are no longer available from IBKR

Default: False

--delist-exchanges

auto-delist securities that are associated with these exchanges

-w, --wait

run the diff synchronously and return the diff (otherwise run asynchronously and log the results, if any, to flightlog

Default: False

Flag security details that have changed in IBKR’s system since the time they were last collected into the securities master database.

Diff can be run synchronously or asynchronously (asynchronous is the default and is recommended if diffing more than a handful of securities).

Examples:

Asynchronously generate a diff for all securities in a universe called “italy-stk” and log the results, if any, to flightlog:

quantrocket master diff-ibkr -u “italy-stk”

Asynchronously generate a diff for all securities in a universe called “italy-stk”, looking only for sector or industry changes:

quantrocket master diff-ibkr -u “italy-stk” –fields ibkr_Sector ibkr_Industry

Synchronously get a diff for specific securities by sid:

quantrocket master diff-ibkr –sids FIBBG000LV0836 FIBBG000B9XRY4 –wait

Synchronously get a diff for specific securities without knowing their sids:

quantrocket master get -e NASDAQ -t STK -s AAPL FB GOOG | quantrocket master diff-ibkr –wait –infile -

Asynchronously generate a diff for all securities in a universe called “nasdaq-sml” and auto-delist any symbols that are no longer available from IBKR or that are now associated with the PINK exchange:

quantrocket master diff-ibkr -u “nasdaq-sml” –delist-missing –delist-exchanges PINK

delist-ibkr¶

mark an IBKR security as delisted

quantrocket master delist-ibkr [-h] [-i SID] [-s SYMBOL] [-e EXCHANGE]
                               [-c CURRENCY] [-t SEC_TYPE]

Named Arguments¶

-i, --sid

the sid of the security to be delisted

-s, --symbol

the symbol to be delisted (if sid not provided)

-e, --exchange

the exchange of the security to be delisted (if needed to disambiguate)

-c, --currency

the currency of the security to be delisted (if needed to disambiguate)

-t, --sec-type

Possible choices: STK, ETF, FUT, CASH, IND

the security type of the security to be delisted (if needed to disambiguate). Possible choices: [‘STK’, ‘ETF’, ‘FUT’, ‘CASH’, ‘IND’]

Mark an IBKR security as delisted.

This does not remove any data but simply marks the security as delisted so that data services won’t attempt to collect data for the security and so that the security can be optionally excluded from query results.

The security can be specified by sid or a combination of other parameters (for example, symbol + exchange). As a precaution, the request will fail if the parameters match more than one security.

Examples:

Delist a security by sid:

quantrocket master delist-ibkr -i FIBBG1234567890

Delist a security by symbol + exchange:

quantrocket master delist-ibkr -s ABC -e NYSE

list-universes¶

list universes and their size

quantrocket master list-universes [-h]

List universes and their size.

Examples:

quantrocket master list-universes

universe¶

create a universe of securities

quantrocket master universe [-h] [-f INFILE]
                            [--from-universes [UNIVERSE [UNIVERSE ...]]]
                            [--exclude-delisted] [-a | -r]
                            CODE

Positional Arguments¶

CODE: the code to assign to the universe (lowercase alphanumerics and hyphens only)

Named Arguments¶

-f, --infile

create the universe from the sids in this file (specify ‘-‘ to read file from stdin)

--from-universes

create the universe from these existing universes

--exclude-delisted

exclude delisted securities and expired contracts that would otherwise be included (default is to include them)

Default: False

-a, --append

append to universe if universe already exists

Default: False

-r, --replace

replace universe if universe already exists

Default: False

Create a universe of securities.

Examples:

Download a CSV of Italian stocks then upload it to create a universe called “italy-stk”:

quantrocket master get –exchanges BVME –sec-types STK -f italy.csv quantrocket master universe “italy-stk” -f italy.csv

In one line, download a CSV of all ARCA ETFs and append to a universe called “arca-etf”:

quantrocket master get –exchanges ARCA –sec-types ETF | quantrocket master universe “arca-etf” –append –infile -

Create a universe consisting of several existing universes:

quantrocket master universe “asx” –from-universes “asx-sml” “asx-mid” “asx-lrg”

Copy a universe but exclude delisted securities:

quantrocket master universe “hong-kong-active” –from-universes “hong-kong” –exclude-delisted

delete-universe¶

delete a universe

quantrocket master delete-universe [-h] code

Positional Arguments¶

code: the universe code

Delete a universe.

The listings details of the member securities won’t be deleted, only their grouping as a universe.

Examples:

Delete the universe called “italy-stk”:

quantrocket master delete-universe ‘italy-stk’

create-ibkr-combo¶

Create an IBKR combo (aka spread)

quantrocket master create-ibkr-combo [-h] PATH

Positional Arguments¶

PATH: a JSON file containing an array of the combo legs, where each leg is an array specifying action, ratio, and sid

Create an IBKR combo (aka spread), which is a composite instrument consisting of two or more individual instruments (legs) that are traded as a single instrument.

Each user-defined combo is stored in the securities master database with a SecType of “BAG”. The combo legs are stored in the ComboLegs field as a JSON array. QuantRocket assigns a sid for the combo consisting of a prefix ‘IC’ followed by an autoincrementing digit, for example: IC1, IC2, IC3, …

If the combo already exists, its sid will be returned instead of creating a duplicate record.

Examples:

Create a spread from a JSON file:

cat spread.json [[“BUY”, 1, QF12345],

[“SELL”, 1, QF23456]]

quantrocket master create-ibkr-combo spread.json

rollrules¶

upload a new rollover rules config, or return the current rollover rules

quantrocket master rollrules [-h] [FILENAME]

Positional Arguments¶

FILENAME: the rollover rules YAML config file to upload (if omitted, return the current config)

Upload a new rollover rules config, or return the current rollover rules.

Examples:

Upload a new rollover config (replaces current config):

quantrocket master rollrules myrolloverrules.yml

Show current rollover config:

quantrocket master rollrules

collect-ibkr-calendar¶

collect upcoming trading hours from IBKR for exchanges and save to securities master database

quantrocket master collect-ibkr-calendar [-h] [-e [EXCHANGE [EXCHANGE ...]]]

Named Arguments¶

-e, --exchanges: limit to these exchanges

Collect upcoming trading hours from IBKR for exchanges and save to securities master database.

Examples:

Collect trading hours for ARCA:

quantrocket master collect-ibkr-calendar -e ARCA

calendar¶

check whether exchanges are open or closed

quantrocket master calendar [-h] [-t SEC_TYPE] [-i TIMEDELTA | -a TIMEDELTA]
                            [-o]
                            EXCHANGE [EXCHANGE ...]

Positional Arguments¶

EXCHANGE: the exchange(s) to check

Named Arguments¶

-t, --sec-type

Possible choices: STK, FUT, CASH, OPT

the security type, if needed to disambiguate for exchanges that trade multiple security types. Possible choices: [‘STK’, ‘FUT’, ‘CASH’, ‘OPT’]

-i, --in

check whether exchanges will be open or closed at this point in the future (use Pandas timedelta string, e.g. 2h or 30min or 1d)

-a, --ago

check whether exchanges were open or closed this long ago (use Pandas timedelta string, e.g. 2h or 30min or 1d)

-o, --outside-rth

check extended hours calendar (default is to check regular trading hours calendar)

Default: False

Check whether exchanges are open or closed.

Examples:

Check whether NYSE is open or closed now:

quantrocket master calendar NYSE

Check whether the Tokyo Stock Exchange was open or closed 5 hours ago:

quantrocket master calendar TSEJ –ago 5h

Check whether GLOBEX will be open or closed in 30 minutes:

quantrocket master calendar GLOBEX –in 30min

isopen¶

assert that one or more exchanges are open and exit non-zero if closed

quantrocket master isopen [-h] [-t SEC_TYPE] [-i TIMEDELTA | -a TIMEDELTA]
                          [-s FREQ | -u FREQ] [-o]
                          EXCHANGE [EXCHANGE ...]

Positional Arguments¶

EXCHANGE: the exchange(s) to check

Named Arguments¶

-t, --sec-type

Possible choices: STK, FUT, CASH, OPT

the security type, if needed to disambiguate for exchanges that trade multiple security types. Possible choices: [‘STK’, ‘FUT’, ‘CASH’, ‘OPT’]

-i, --in

assert that exchanges will be open at this point in the future (use Pandas timedelta string, e.g. 2h or 30min or 1d)

-a, --ago

assert that exchanges were open this long ago (use Pandas timedelta string, e.g. 2h or 30min or 1d)

-s, --since

assert that exchanges have been opened (as of –in or –ago if applicable) since at least this time (use Pandas frequency string, e.g. ‘W’ (week end), ‘M’ (month end), ‘Q’ (quarter end), ‘A’ (year end))

-u, --until

assert that exchanges will be opened (as of –in or –ago if applicable) until at least this time (use Pandas frequency string, e.g. ‘W’ (week end), ‘M’ (month end), ‘Q’ (quarter end), ‘A’ (year end))

-o, --outside-rth

check extended hours calendar (default is to check regular trading hours calendar)

Default: False

Assert that one or more exchanges are open and exit non-zero if closed.

Intended to be used as a conditional for running other commands.

Examples:

Place Moonshot orders if NYSE is open now:

quantrocket master isopen NYSE && quantrocket moonshot orders my-strategy | quantrocket blotter order -f -

Collect historical data for Australian stocks if the exchange was open 4 hours ago:

quantrocket master isopen ASX –ago 4h && quantrocket history collect asx-stk-1d

Log a message if the London Stock Exchange will be open in 30 minutes:

quantrocket master isopen LSE –in 30min && quantrocket flightlog log ‘the market opens soon!’

isclosed¶

assert that one or more exchanges are closed and exit non-zero if open

quantrocket master isclosed [-h] [-t SEC_TYPE] [-i TIMEDELTA | -a TIMEDELTA]
                            [-s FREQ | -u FREQ] [-o]
                            EXCHANGE [EXCHANGE ...]

Positional Arguments¶

EXCHANGE: the exchange(s) to check

Named Arguments¶

-t, --sec-type

Possible choices: STK, FUT, CASH, OPT

the security type, if needed to disambiguate for exchanges that trade multiple security types. Possible choices: [‘STK’, ‘FUT’, ‘CASH’, ‘OPT’]

-i, --in

assert that exchanges will be closed at this point in the future (use Pandas timedelta string, e.g. 2h or 30min or 1d)

-a, --ago

assert that exchanges were closed this long ago (use Pandas timedelta string, e.g. 2h or 30min or 1d)

-s, --since

assert that exchanges have been closed (as of –in or –ago if applicable) since at least this time (use Pandas frequency string, e.g. ‘W’ (week end), ‘M’ (month end), ‘Q’ (quarter end), ‘A’ (year end))

-u, --until

assert that exchanges will be closed (as of –in or –ago if applicable) until at least this time (use Pandas frequency string, e.g. ‘W’ (week end), ‘M’ (month end), ‘Q’ (quarter end), ‘A’ (year end))

-o, --outside-rth

check extended hours calendar (default is to check regular trading hours calendar)

Default: False

Assert that one or more exchanges are closed and exit non-zero if open.

Intended to be used as a conditional for running other commands.

For –since/–until options, pass a Pandas frequency string, i.e. any string that is a valid freq argument to pd.date_range. See: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#anchored-offsets

Examples:

Place Moonshot orders if the NYSE will be closed NYSE in 1 hour:

quantrocket master isclosed NYSE –in 1h && quantrocket moonshot orders my-strategy | quantrocket blotter order -f -

Collect historical data for Australian stocks if the exchange is closed now but was open 4 hours ago:

quantrocket master isclosed ASX && quantrocket master isopen ASX –ago 4h && quantrocket history collect asx-stk-1d

Place Moonshot orders if the NYSE has been closed since month end:

quantrocket master isclosed NYSE –since M && quantrocket moonshot orders monthly-rebalancing-strategy | quantrocket blotter order -f -

Place Moonshot orders if the NYSE will be closed in 1 hour and remain closed through quarter end:

quantrocket master isclosed NYSE –in 1H –until Q && quantrocket moonshot orders end-of-quarter-strategy | quantrocket blotter order -f -

ticksize¶

round prices in a CSV to valid tick sizes

quantrocket master ticksize [-h] -f INFILE -r FIELD [FIELD ...] [-d DIRECTION]
                            [-a] [-o OUTFILE]

Named Arguments¶

-f, --infile

CSV file with prices to be rounded (specify ‘-‘ to read file from stdin)

-r, --round

columns to be rounded

-d, --how

Possible choices: up, down, nearest

which direction to round to. Possible choices: up, down, nearest (default is ‘nearest’)

-a, --append-ticksize

append a column of tick sizes for each field to be rounded

Default: False

-o, --outfile

filename to write the data to (default is stdout)

Round prices in a CSV file to valid tick sizes.

CSV should contain columns Sid, Exchange, and the columns to be rounded (e.g. LmtPrice). Additional columns will be ignored and returned unchanged.

Examples:

Round the LmtPrice column in a CSV of orders and return a new CSV:

quantrocket master ticksize -f orders.csv –round LmtPrice -o rounded_orders.csv

Round the StopPrice column in a CSV of orders and append the tick size as a new column (called StopPriceTickSize):

quantrocket master ticksize -f orders.csv -r StopPrice –append-ticksize -o rounded_orders.csv

Round the LmtPrice column in a CSV of Moonshot orders then place the orders:

quantrocket moonshot orders umd-japan | quantrocket master ticksize -f - -r LmtPrice | quantrocket blotter order -f -

quantrocket.master.list_ibkr_exchanges(regions=None, sec_types=None)¶

List exchanges by security type and country as found on the IBKR website.

Parameters

regions (list of str, optional) – limit to these regions. Possible choices: north_america, europe, asia, global
sec_types (list of str, optional) – limit to these securitiy types. Possible choices: STK, ETF, FUT, CASH, IND

Returns

Return type

dict

quantrocket.master.collect_alpaca_listings()¶

Collect securities listings from Alpaca and store in securities master database.

Returns: status message
Return type: dict

quantrocket.master.collect_edi_listings(exchanges=None)¶

Collect securities listings from EDI and store in securities master database.

Parameters: exchanges (list or str, required) – collect listings for these exchanges (identified by MICs)
Returns: status message
Return type: dict

Examples

Collect sample listings:

>>> collect_edi_listings(exchanges="FREE")

Collect listings for all permitted exchanges:

>>> collect_edi_listings()

Collect all Chinese stock listings:

>>> collect_edi_listings(exchanges=["XSHG", "XSHE"])

quantrocket.master.collect_figi_listings()¶

Collect securities listings from Bloomberg OpenFIGI and store in securities master database.

OpenFIGI provides several useful security attributes including market sector, a detailed security type, and share class-level FIGI identifier.

The collected data fields show up in the master file with the prefix “figi_*”.

This function does not directly query the OpenFIGI API but rather downloads a dump of all FIGIs which QuantRocket has previously mapped to securities from other vendors.

Returns: status message
Return type: dict

Examples

Collect all available FIGI listings:

>>> collect_figi_listings()

quantrocket.master.collect_ibkr_listings(exchanges=None, sec_types=None, currencies=None, symbols=None, universes=None, sids=None)¶

Collect securities listings from Interactive Brokers and store in securities master database.

Parameters

exchanges (list or str) – one or more IBKR exchange codes to collect listings for (required unless providing universes or sids). For sample data use exchange code ‘FREE’
sec_types (list of str, optional) – limit to these security types. Possible choices: STK, ETF, FUT, CASH, IND
currencies (list of str, optional) – limit to these currencies
symbols (list of str, optional) – limit to these symbols
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids

Returns

status message

Return type

dict

Examples

Collect free sample listings:

>>> collect_ibkr_listings(exchanges="FREE")

Collect all Toronto Stock Exchange stock listings:

>>> collect_ibkr_listings(exchanges="TSE", sec_types="STK")

Collect all NYSE ARCA ETF listings:

>>> collect_ibkr_listings(exchanges="ARCA", sec_types="ETF")

Collect specific symbols from Nasdaq:

>>> collect_ibkr_listings(exchanges="NASDAQ", symbols=["AAPL", "GOOG", "NFLX"])

Re-collect contract details for an existing universe called “japan-fin”:

>>> collect_ibkr_listings(universes="japan-fin")

quantrocket.master.collect_sharadar_listings(countries='US')¶

Collect securities listings from Sharadar and store in securities master database.

Parameters: countries (list of str, required) – countries to collect listings for. Possible choices: US, FREE
Returns: status message
Return type: dict

quantrocket.master.collect_usstock_listings()¶

Collect US stock listings from QuantRocket and store in securities master database.

Returns: status message
Return type: dict

quantrocket.master.collect_ibkr_option_chains(universes=None, sids=None, infilepath_or_buffer=None)¶

Collect IBKR option chains for underlying securities.

Parameters

universes (list of str, optional) – collect options for these universes of underlying securities
sids (list of str, optional) – collect options for these underlying sids
infilepath_or_buffer (str or file-like object, optional) – collect options for the sids in this file (specify ‘-‘ to read file from stdin)

Returns

status message

Return type

dict

quantrocket.master.diff_ibkr_securities(universes=None, sids=None, infilepath_or_buffer=None, fields=None, delist_missing=False, delist_exchanges=None, wait=False)¶

Flag security details that have changed in IBKR’s system since the time they were last collected into the securities master database.

Diff can be run synchronously or asynchronously (asynchronous is the default and is recommended if diffing more than a handful of securities).

Parameters

universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
infilepath_or_buffer (str or file-like object, optional) – limit to the sids in this file (specify ‘-‘ to read file from stdin)
fields (list of str, optional) – only diff these fields (field name should start with “ibkr”)
delist_missing (bool) – auto-delist securities that are no longer available from IBKR
delist_exchanges (list of str, optional) – auto-delist securities that are associated with these exchanges
wait (bool) – run the diff synchronously and return the diff (otherwise run asynchronously and log the results, if any, to flightlog)

Returns

dict of sids and fields that have changed (if wait), or status message

Return type

dict

quantrocket.master.download_master_file(filepath_or_buffer=None, output='csv', exchanges=None, sec_types=None, currencies=None, universes=None, symbols=None, sids=None, exclude_universes=None, exclude_sids=None, exclude_delisted=False, exclude_expired=False, frontmonth=False, vendors=None, fields=None)¶

Query security details from the securities master database and download to file.

Parameters

filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (csv or json, default is csv)
exchanges (list of str, optional) – limit to these exchanges. You can specify exchanges using the MIC or the vendor’s exchange code.
sec_types (list of str, optional) – limit to these security types. Possible choices: STK, ETF, FUT, CASH, IND, OPT, FOP, BAG
currencies (list of str, optional) – limit to these currencies
universes (list of str, optional) – limit to these universes
symbols (list of str, optional) – limit to these symbols
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
exclude_delisted (bool) – exclude delisted securities (default is to include them)
exclude_expired (bool) – exclude expired contracts (default is to include them)
frontmonth (bool) – exclude backmonth and expired futures contracts (default False)
vendors (list of str, optional) – limit to these vendors. Possible choices: alpaca, edi, ibkr, sharadar, usstock
fields (list of str, optional) – Return specific fields. By default a core set of fields is returned, but additional vendor-specific fields are also available. To return non-core fields, you can reference them by name, or pass “*” to return all available fields. To return all fields for a specific vendor, pass the vendor prefix followed by “*”, for example “edi*” for all EDI fields. Pass “?*” (or any invalid vendor prefix plus “*”) to see available vendor prefixes. Pass “?” or any invalid fieldname to see all available fields.

Returns

Return type

None

Examples

Download NYSE and NASDAQ securities to file, using MICs to specify the exchanges:

>>> download_master_file("securities.csv", exchanges=["XNYS","XNAS"])

Download NYSE and NASDAQ securities to file, using IBKR exchange codes to specify the exchanges, and include all IBKR fields:

>>> download_master_file("securities.csv", exchanges=["NYSE","NASDAQ"], fields="ibkr*")

Download securities for a particular universe to in-memory file, including all possible fields, and load the CSV into pandas.

>>> f = io.StringIO()
>>> download_master_file(f, fields="*", universes="my-universe")
>>> securities = pd.read_csv(f)

quantrocket.master.get_securities_reindexed_like(reindex_like, fields=None)¶

Return a multiindex DataFrame of securities master data, reindexed to match the index and columns (sids) of reindex_like.

Parameters

reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
fields (list of str) – a list of fields to include in the resulting DataFrame. By default a core set of fields is returned, but additional vendor-specific fields are also available. To return non-core fields, you can reference them by name, or pass “*” to return all available fields. To return all fields for a specific vendor, pass the vendor prefix followed by “*”, for example “edi*” for all EDI fields. Pass “?*” (or any invalid vendor prefix plus “*”) to see available vendor prefixes. Pass “?” or any invalid fieldname to see all available fields.

Returns

a multiindex (Field, Date) DataFrame of securities master data, shaped like the input DataFrame

Return type

DataFrame

Examples

Get exchanges (MICs) using a DataFrame of prices:

>>> closes = prices.loc["Close"]
>>> securities = get_securities_reindexed_like(
        closes, fields=["Exchange"])
>>> exchanges = securities.loc["Exchange"]
>>> nyse_closes = closes.where(exchanges == "XNYS")

quantrocket.master.get_contract_nums_reindexed_like(reindex_like, limit=5)¶

From a DataFrame of futures (with dates as the index and sids as columns), return a DataFrame of integers representing each sid’s sequence in the futures chain as of each date, where 1 is the front contract, 2 is the second nearest contract, etc.

Sequences are based on the RolloverDate field in the securities master file, which is based on configurable rollover rules.

Parameters

reindex_like (DataFrame, required) – a DataFrame (usually of prices) with dates for the index and sids for the columns, to which the shape of the resulting DataFrame will be conformed
limit (int) – how many contracts ahead to sequence. For example, assuming quarterly contracts, a limit of 5 will sequence 5 quarters out. Default 5.

Returns

a DataFrame of futures chain sequence numbers, shaped like the input DataFrame

Return type

DataFrame

Examples

Get a Boolean mask of front-month contracts:

>>> closes = prices.loc["Close"]
>>> contract_nums = get_contract_nums_reindexed_like(closes)
>>> are_front_months = contract_nums == 1

quantrocket.master.create_universe(code, infilepath_or_buffer=None, from_universes=None, exclude_delisted=False, append=False, replace=False)¶

Create a universe of securities.

Parameters

code (str, required) – the code to assign to the universe (lowercase alphanumerics and hyphens only)
infilepath_or_buffer (str or file-like object, optional) – create the universe from the sids in this file (specify ‘-‘ to read file from stdin)
from_universes (list of str, optional) – create the universe from these existing universes
exclude_delisted (bool) – exclude delisted securities and expired contracts that would otherwise be included (default is not to exclude them)
append (bool) – append to universe if universe already exists (default False)
replace (bool) – replace universe if universe already exists (default False)

Returns

status message

Return type

dict

Examples

Create a universe called ‘nyse-stk’ from a CSV file:

>>> create_universe("usa-stk", "nyse_securities.csv")

Create a universe from a DataFrame:

>>> import io
>>> f = io.StringIO()
>>> japan_securities.to_csv(f)
>>> create_universe("japan-stk", f)

quantrocket.master.delete_universe(code)¶

Delete a universe.

The listings details of the member securities won’t be deleted, only their grouping as a universe.

Parameters: code (str, required) – the universe code
Returns: status message
Return type: dict

quantrocket.master.list_universes()¶

List universes and their size.

Returns: dict of universe:size
Return type: dict

quantrocket.master.delist_ibkr_security(sid=None, symbol=None, exchange=None, currency=None, sec_type=None)¶

Mark an IBKR security as delisted.

The security can be specified by sid or a combination of other parameters (for example, symbol + exchange). As a precaution, the request will fail if the parameters match more than one security.

Parameters

sid (str, optional) – the sid of the security to be delisted
symbol (str, optional) – the symbol to be delisted (if sid not provided)
exchange (str, optional) – the exchange of the security to be delisted (if needed to disambiguate)
currency (str, optional) – the currency of the security to be delisted (if needed to disambiguate)
sec_type (str, optional) – the security type of the security to be delisted (if needed to disambiguate). Possible choices: STK, ETF, FUT, CASH, IND

Returns

status message

Return type

dict

quantrocket.master.create_ibkr_combo(combo_legs)¶

Create an IBKR combo (aka spread), which is a composite instrument consisting of two or more individual instruments (legs) that are traded as a single instrument.

If the combo already exists, its sid will be returned instead of creating a duplicate record.

Parameters: combo_legs (list, required) – a list of the combo legs, where each leg is a list specifying action, ratio, and sid
Returns: returns a dict containing the generated sid of the combo, and whether a new record was created
Return type: dict

Examples

To create a calendar spread on VX, first retrieve the sids of the legs:

>>> from quantrocket.master import download_master_file
>>> download_master_file("vx.csv", symbols="VIX", exchanges="CFE", sec_types="FUT")
>>> vx_sids = pd.read_csv("vx.csv", index_col="Symbol").Sid.to_dict()

Then create the combo:

>>> create_ibkr_combo([
        ["BUY", 1, vx_sids["VXV9"]],
        ["SELL", 1, vx_sids["VXQ9"]]
    ])
    {"sid": IC1, "created": True}

quantrocket.master.load_rollrules_config(filename)¶

Upload a new rollover rules config.

Parameters: filename (str, required) – the rollover rules YAML config file to upload
Returns: status message
Return type: dict

quantrocket.master.get_rollrules_config()¶

Returns the current rollover rules config.

Returns: the config as a dict
Return type: dict

quantrocket.master.collect_ibkr_calendar(exchanges=None)¶

Collect upcoming trading hours from IBKR for exchanges and save to securities master database.

Parameters: exchanges (list of str, optional) – limit to these exchanges
Returns: status message
Return type: dict

quantrocket.master.list_calendar_statuses(exchanges, sec_type=None, in_=None, ago=None, outside_rth=False)¶

Check whether exchanges are open or closed.

Parameters

exchanges (list of str, required) – the exchange(s) to check
sec_type (str, optional) – the security type, if needed to disambiguate for exchanges that trade multiple security types. Possible choices: STK, FUT, CASH, OPT
in (str, optional) – check whether exchanges will be open or closed at this point in the future (use Pandas timedelta string, e.g. 2h or 30min or 1d)
ago (str, optional) – check whether exchanges were open or closed this long ago (use Pandas timedelta string, e.g. 2h or 30min or 1d)
outside_rth (bool) – check extended hours calendar (default is to check regular trading hours calendar)

Returns

exchange calendar status

Return type

dict

quantrocket.master.round_to_tick_sizes(infilepath_or_buffer, round_fields, how=None, append_ticksize=False, outfilepath_or_buffer=None)¶

Round prices in a CSV file to valid tick sizes.

CSV should contain columns Sid, Exchange, and the columns to be rounded (e.g. LmtPrice). Additional columns will be ignored and returned unchanged.

Parameters

infilepath_or_buffer (str or file-like object, required) – CSV file with prices to be rounded (specify ‘-‘ to read file from stdin)
round_fields (list of str, required) – columns to be rounded
how (str, optional) – which direction to round to. Possible choices: ‘up’, ‘down’, ‘nearest’ (default is ‘nearest’)
append_ticksize (bool) – append a column of tick sizes for each field to be rounded (default False)
outfilepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)

Returns

Return type

None

Securities Master API

Resource Group ¶

Exchanges ¶

List Exchanges
GET`/master/exchanges/{vendor}{?regions,sec_types}`

List exchanges.

Example URI

GET http://houston/master/exchanges/ibkr?regions=asia&sec_types=STK

URI Parameters

vendor

str (required) Example: ibkr

the vendor to list exchanges for

Choices: ibkr

regions

str (optional) Example: asia

limit to these regions (pass multiple times for multiple regions)

Choices: north_america europe asia global

sec_types

str (optional) Example: STK

limit to these security types (pass multiple times for multiple security types)

Choices: STK ETF FUT CASH IND

Response 200

Headers

Content-Type: application/json

Body

{
  "STK": {
    "Australia": [
      "ASX",
      "CHIXAU"
    ],
    "Hong Kong": [
      "SEHK",
      "SEHKNTL",
      "SEHKSZSE"
    ],
    "India": [
      "NSE"
    ],
    "Japan": [
      "CHIXJ",
      "JPNNEXT",
      "TSEJ"
    ],
    "Singapore": [
      "SGX"
    ]
  }
}

Securities ¶

Collect Listings
POST`/master/securities/{vendor}{?exchanges,countries,sec_types,currencies,symbols,universes,sids}`

Collect securities listings from a vendor and store in securities master database.

Not all parameters are applicable to all vendors. Please see the Python API reference to determine which parameters are applicable to which vendors.

Example URI

POST http://houston/master/securities/usstock?exchanges=XNYS&countries=US&sec_types=STK&currencies=USD&symbols=LVS&universes=my-universe&sids=FI123456

URI Parameters

vendor

str (required) Example: usstock

the vendor to collect data from

Choices: alpaca edi figi ibkr sharadar usstock

exchanges

str (optional) Example: XNYS

the exchange code to collect listings for (required unless providing universes or sids) (pass multiple times for multiple sids)

sec_types

str (optional) Example: STK

limit to these security types (pass multiple times for multiple security types)

Choices: STK ETF FUT CASH IND

currencies

str (optional) Example: USD

limit to these currencies (pass multiple times for multiple currencies)

symbols

str (optional) Example: LVS

limit to these symbols (pass multiple times for multiple symbols)

universes

str (optional) Example: my-universe

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI123456

limit to these sids (pass multiple times for multiple sids)

countries

str (optional) Example: US

countries to collect listings for

Choices: US FREE

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the listing details will be collected asynchronously"
}

Download Master File
GET`/master/securities/{output}{?exchanges,sec_types,currencies,symbols,universes,sids,exclude_universes,exclude_sids,exclude_delisted,exclude_expired,vendors,fields,frontmonth}`

Query security details from the securities master database and download to file.

Example URI

GET http://houston/master/securities/.csv?exchanges=NYSE&sec_types=STK&currencies=USD&symbols=LVS&universes=my-universe&sids=FI123456&exclude_universes=another-universe&exclude_sids=234567&exclude_delisted=false&exclude_expired=false&vendors=usstock&fields=*&frontmonth=false

URI Parameters

output

str (required) Example: .csv

output format

Choices: .csv .json

exchanges

str (optional) Example: NYSE

limit to these exchanges. You can specify exchanges using the MIC or the vendor’s exchange code. (pass multiple times for multiple exchanges)

sec_types

str (optional) Example: STK

limit to these security types (pass multiple times for multiple security types)

Choices: STK ETF FUT CASH IND OPT FOP BAG

currencies

str (optional) Example: USD

limit to these currencies (pass multiple times for multiple currencies)

symbols

str (optional) Example: LVS

limit to these symbols (pass multiple times for multiple symbols)

universes

str (optional) Example: my-universe

limit to these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI123456

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: another-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: 234567

exclude these sids (pass multiple times for multiple sids)

exclude_delisted

bool (required) Example: false

exclude delisted securities (default is to include them)

exclude_expired

bool (required) Example: false

exclude expired contracts (default is to include them)

frontmonth

bool (required) Example: false

exclude backmonth and expired futures contracts (default False)

vendors

str (optional) Example: usstock

limit to these vendors (pass multiple times for multiple vendors)

Choices: alpaca edi ibkr sharadar usstock

fields

str (optional) Example: *

Return specific fields. By default a core set of fields is returned, but additional vendor-specific fields are also available. To return non-core fields, you can reference them by name, or pass * to return all available fields. To return all fields for a specific vendor, pass the vendor prefix followed by * , for example edi* for all EDI fields. Pass ?* (or any invalid vendor prefix plus * ) to see available vendor prefixes. Pass “?” or any invalid fieldname to see all available fields.

Response 200

Headers

Content-Type: text/csv

Body

279016041,NSC,FUT,0,ONE,USD,NSC3MM7,NSC3M,NSC3M,"NORFOLK SOUTHERN CORP",EST,Industrial,Transportation,Transport-Rail,0.01,1,1,20170619,201706,100,,0
279016083,NUS,FUT,0,ONE,USD,NUS3MM7,NUS3M,NUS3M,"NU SKIN ENTERPRISES INC - A",EST,"Consumer, Cyclical",Retail,"Multilevel Dir Selling",0.01,1,1,20170619,201706,100,,0
279016106,O,FUT,0,ONE,USD,O3MM7,O3M,O3M,"REALTY INCOME CORP",EST,Financial,REITS,"REITS-Single Tenant",0.01,1,1,20170619,201706,100,,0

Delist Security
DELETE`/master/securities/{vendor}{?exchange,sec_type,currency,symbols,sids}`

Mark an IBKR security as delisted.

The security can be specified by sid or a combination of other parameters (for example, symbol + exchange). As a precaution, the request will fail if the parameters match more than one security.

Example URI

DELETE http://houston/master/securities/ibkr?exchange=NYSE&sec_type=STK&currency=USD&symbols=ABC&sids=FI123456

URI Parameters

vendor

str (required) Example: ibkr

the vendor to delist the security for.

Choices: ibkr

sids

str (optional) Example: FI123456

the sid of the security to be delisted

symbols

str (optional) Example: ABC

the symbol to be delisted (if sid not provided)

exchange

str (optional) Example: NYSE

the exchange of the security to be delisted (if needed to disambiguate)

sec_type

str (optional) Example: STK

the security type of the security to be delisted (if needed to disambiguate)

Choices: STK ETF FUT CASH IND

currency

str (optional) Example: USD

the currency of the security to be delisted (if needed to disambiguate)

Response 200

Headers

Content-Type: application/json

Body

{
  "msg": "delisted sid FI123456"
}

Options ¶

Collect Option Chains
POST`/master/options/ibkr{?universes,sids}`

Collect IBKR option chains for underlying securities. Specify sids or universes or upload a CSV of sids as the request body.

Example URI

POST http://houston/master/options/ibkr?universes=my-universe&sids=FI123456

URI Parameters

universes: str (optional) Example: my-universe
collect options for these universes of underlying securities (pass multiple times for multiple universes)
sids: str (optional) Example: FI123456
collect options for these underlying sids (pass multiple times for multiple sids)

Request

Headers

Content-Type: text/csv

Body

Sid,OtherField,OtherField2
FI123456,other,fields
FI234567,will,be
FI345678,ignored,

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the option chains will be collected asynchronously"
}

Diff ¶

Diff Securities
GET`/master/diff/ibkr{?universes,sids,fields,delist_missing,delist_exchanges,wait}`

Flag security details that have changed in IBKR’s system since the time they were last loaded into the securities master database. Specify sids or universes or upload a CSV of sids as the request body.

Can be run synchronously or asynchronously (asynchronous is the default and is recommended if diffing more than a handful of securities).

Example URI

GET http://houston/master/diff/ibkr?universes=my-universe&sids=FI123456&fields=ibkr_PrimaryExchange&delist_missing=true&delist_exchanges=PINK&wait=true

URI Parameters

universes: str (optional) Example: my-universe
limit to these universes (pass multiple times for multiple universes)
sids: str (optional) Example: FI123456
limit to these sids (pass multiple times for multiple sids)
fields: str (optional) Example: ibkr_PrimaryExchange
only diff these fields (pass multiple times for multiple fields)
delist_missing: bool (optional) Example: true
auto-delist securities that are no longer available from IBKR
delist_exchanges: str (optional) Example: PINK
auto-delist securities that are associated with these exchanges
wait: bool (optional) Example: true
run the diff synchronously and return the diff (otherwise run asynchronously and log the results, if any, to flightlog)

Request

Headers

Content-Type: text/csv

Body

Sid,OtherField,OtherField2
FI123456,other,fields
FI234567,will,be
FI345678,ignored,

Response 200

Headers

Content-Type: application/json

Body

{
  "security_diffs": [
    {
      "as_stored_in_db": {
        "Symbol": "ABC",
        "Currency": "USD",
        "SecType": "STK",
        "PrimaryExchange": "NYSE",
        "Sid": "FI123456"
      },
      "changes_in_ibkr": {
        "PrimaryExchange": {
          "new": "PINK",
          "old": "NYSE"
        }
      }
    }
  ]
}

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the diff, if any, will be logged to flightlog asynchronously"
}

Universes ¶

List Universes
GET`/master/universes/`

List universes and their size.

Example URI

GET http://houston/master/universes/

Response 200

Headers

Content-Type: application/json

Body

{
  "jpn-fut": 196,
  "fx": 98,
  "arca-etf": 1514,
  "asx-stk": 2313
}

Create Universe
PUT`/master/universes/{code}{?from_universes,exclude_delisted,replace}`

Create a universe of securities, either from existing universes and/or from a CSV containing sids and uploaded as the request body.

Example URI

PUT http://houston/master/universes/arca-etf?from_universes=some-universe&exclude_delisted=true&replace=true

URI Parameters

code: str (required) Example: arca-etf
the code to assign to the universe (lowercase alphanumerics and hyphens only)
from_universes: str (optional) Example: some-universe
create the universe from these existing universes (pass multiple times for multiple existing universes)
exclude_delisted: bool (required) Example: true
exclude delisted securities that would otherwise be included (default is not to exclude them)
replace: bool (required) Example: true
replace universe if universe already exists (default is to fail if universe already exists)

Request

Headers

Content-Type: text/csv

Body

Sid,OtherField,OtherField2
FI123456,other,fields
FI234567,will,be
FI345678,ignored,

Response 200

Headers

Content-Type: application/json

Body

{
  "code": "arca-etf",
  "provided": 1514,
  "inserted": 1514,
  "total_after_insert": 1514
}

Append to Universe
PATCH`/master/universes/{code}{?from_universes,exclude_delisted}`

Append to a universe of securities, either from existing universes and/or from a CSV containing sids and uploaded as the request body.

Example URI

PATCH http://houston/master/universes/arca-etf?from_universes=some-universe&exclude_delisted=true

URI Parameters

code: str (required) Example: arca-etf
the code to assign to the universe (lowercase alphanumerics and hyphens only)
from_universes: str (optional) Example: some-universe
create the universe from these existing universes (pass multiple times for multiple existing universes)
exclude_delisted: bool (required) Example: true
exclude delisted securities that would otherwise be included (default is not to exclude them)

Request

Headers

Content-Type: text/csv

Body

Sid,OtherField,OtherField2
FI123456,other,fields
FI234567,will,be
FI345678,ignored,

Response 200

Headers

Content-Type: application/json

Body

{
  "code": "arca-etf",
  "provided": 1534,
  "inserted": 30,
  "total_after_insert": 1534
}

Delete Universe
DELETE`/master/universes/{code}`

Delete a universe. (The listings details of the member securities won’t be deleted, only their grouping as a universe).

Example URI

DELETE http://houston/master/universes/arca-etf

URI Parameters

code: str (required) Example: arca-etf
the universe code

Response 200

Headers

Content-Type: application/json

Body

{
  "code": "arca-etf",
  "deleted": 1534
}

Combos ¶

Create IBKR Combo
PUT`/master/combos/ibkr`

Create an IBKR combo (aka spread), which is a composite instrument consisting of two or more individual instruments (legs) that are traded as a single instrument.

If the combo already exists, its sid will be returned instead of creating a duplicate record.

Example URI

PUT http://houston/master/combos/ibkr

Request

Headers

Content-Type: application/json

Body

[
  [
    "BUY",
    1,
    "FI12345"
  ],
  [
    "SELL",
    1,
    "FI23456"
  ]
]

Response 200

Headers

Content-Type: application/json

Body

{
    "sid": IC1,
    "created": true
}

Rollover Config ¶

Get Rollover Config
GET`/master/config/rollover`

Returns the current rollover rules config.

Example URI

GET http://houston/master/config/rollover

Response 200

Headers

Content-Type: application/json

Body

{
  "GLOBEX": {
    "ES": {
      "rollrule": {
        "days": -8
      },
      "same_for": [
        "NQ",
        "RS",
        "YM"
      ]
    },
    "HE": {
      "only_months": [
        2,
        4,
        6,
        8,
        10,
        12
      ],
      "rollrule": {
        "months": -1,
        "day": 27
      },
      "same_for": [
        "LE"
      ]
    }
  },
  "NYMEX": {
    "CL": {
      "rollrule": {
        "days": -1
      },
      "same_for": [
        "NG"
      ]
    }
  }
}

Load Rollover Config
PUT`/master/config/rollover`

Upload a new rollover rules config.

Example URI

PUT http://houston/master/config/rollover

Request

Headers

Content-Type: application/x-yaml

Body

GLOBEX:
    ES:
        rollrule:
        days: -8
        same_for:
        - NQ
        - RS
        - YM
    HE:
        only_months:
        - 2
        - 4
        - 6
        - 8
        - 10
        - 12
        rollrule:
        months: -1
        day: 27
        same_for:
        - LE
NYMEX:
    CL:
        rollrule:
        days: -1
        same_for:
        - NG

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the config will be loaded asynchronously"
}

Calendars ¶

Collect IBKR Calendars
POST`/master/calendar/{vendor}{?exchanges}`

Collect upcoming trading hours from IBKR for exchanges and save to securities master database.

Example URI

POST http://houston/master/calendar/ibkr?exchanges=ARCA

URI Parameters

vendor

str (required) Example: ibkr

the vendor to collect trading hours from

Choices: ibkr

exchanges

str (optional) Example: ARCA

limit to these exchanges. Pass multiple times for multiple exchanges.

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the trading hours will be collected asynchronously"
}

Get Exchange Status
GET`/master/calendar/{?exchanges,sec_type,in,ago,outside_rth}`

Check whether exchanges are open or closed.

Example URI

GET http://houston/master/calendar/?exchanges=ARCA&sec_type=STK&in=1h&ago=30min&outside_rth=false

URI Parameters

exchanges

str (required) Example: ARCA

the exchange(s) to check. Pass multiple times for multiple exchanges.

sec_type

str (optional) Example: STK

the security type, if needed to disambiguate for exchanges that trade multiple security types.

Choices: STK FUT CASH OPT

in

str (optional) Example: 1h

check whether exchanges will be open or closed at this point in the future (use Pandas timedelta string, e.g. 2h or 30min or 1d)

ago

str (optional) Example: 30min

check whether exchanges were open or closed this long ago (use Pandas timedelta string, e.g. 2h or 30min or 1d)

outside_rth

bool (optional) Example: false

check extended hours calendar (default is to check regular trading hours calendar)

Response 200

Headers

Content-Type: application/json

Body

{
  "ARCA": {
    "status": "open",
    "since": "2018-05-10T09:30:00",
    "until": "2018-05-10T16:00:00",
    "timezone": "America/New_York"
  }
}

Tick Sizes ¶

Round prices
GET`/master/ticksizes{?round_fields,how,append_ticksize}`

Round prices in a CSV file to valid tick sizes.

CSV should contain columns Sid, Exchange, and the columns to be rounded (e.g. LmtPrice). Additional columns will be ignored and returned unchanged.

Example URI

GET http://houston/master/ticksizes?round_fields=LmtPrice&how=nearest&append_ticksize=true

URI Parameters

round_fields

str (required) Example: LmtPrice

columns to be rounded. Pass multiple times for multiple columns.

how

str (optional) Example: nearest

which direction to round to. Default ‘nearest’.

Choices: up down nearest

append_ticksize

boolean (optional) Example: true

append a column of tick sizes for each field to be rounded (default False)

Request

Headers

Content-Type: text/csv

Body

Sid,Account,Action,OrderRef,TotalQuantity,Exchange,OrderType,Tif,LmtPrice
FI13905888,DU12345,BUY,japan-strategy,1000,SMART,LMT,DAY,15203.1135
FI13905888,DDU12345,BUY,japan-strategy,1000,TSEJ,LMT,DAY,15203.1135

Response 200

Headers

Content-Type: text/csv

Body

Sid,Account,Action,OrderRef,TotalQuantity,Exchange,OrderType,Tif,LmtPrice
FI13905888,DU12345,BUY,japan-strategy,1000,SMART,LMT,DAY,15203.0
FI13905888,DDU12345,BUY,japan-strategy,1000,TSEJ,LMT,DAY,15205.0

quantrocket.moonshot

This API is for backtesting and live trading of Moonshot strategies. For writing Moonshot strategies, see the moonshot API.

QuantRocket Moonshot CLI

usage: quantrocket moonshot [-h] {backtest,paramscan,ml-walkforward,trade} ...

subcommands¶

subcommand: Possible choices: backtest, paramscan, ml-walkforward, trade

Sub-commands:¶

backtest¶

backtest one or more strategies

quantrocket moonshot backtest [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD] [-g FREQ]
                              [-l [CODE:FLOAT [CODE:FLOAT ...]]]
                              [-n [CURRENCY:NLV [CURRENCY:NLV ...]]]
                              [-p [PARAM:VALUE [PARAM:VALUE ...]]]
                              [--no-cache] [-d] [--pdf] [-o FILEPATH]
                              CODE [CODE ...]

Positional Arguments¶

CODE: one or more strategy codes

backtest options¶

-s, --start-date

the backtest start date (default is to use all available history)

-e, --end-date

the backtest end date (default is to use all available history)

-g, --segment

backtest in date segments of this size, to reduce memory usage (use Pandas frequency string, e.g. ‘A’ for annual segments or ‘Q’ for quarterly segments)

-l, --allocations

the allocation for each strategy, passed as ‘code:allocation’ (default allocation is 1.0 / number of strategies)

-n, --nlv

the NLV (net liquidation value, i.e. account balance) to assume for the backtest, expressed in each currency represented in the backtest (pass as ‘currency:nlv’)

-p, --params

one or more strategy params to set on the fly before backtesting (pass as ‘param:value’)

--no-cache

don’t use cached files even if available. Using cached files speeds up backtests but may be undesirable if underlying data has changed. See http://qrok.it/h/mcache to learn more about caching in Moonshot.

Default: False

output options¶

-d, --details

return detailed results for all securities instead of aggregating to strategy level (only supported for single-strategy backtests)

Default: False

--pdf

return a PDF performance tear sheet (default is to return a CSV of performance results)

-o, --outfile

the location to write the results file (omit to write to stdout)

Backtest one or more strategies.

By default returns a CSV of backtest results but can also return a PDF tear sheet of performance charts.

If testing multiple strategies, each column in the CSV represents a strategy. If testing a single strategy with the –details option, each column in the CSV represents a security in the strategy universe.

Examples:

Backtest several HML (High Minus Low) strategies from 2005-2015 and return a CSV of results:

quantrocket moonshot backtest hml-us hml-eur hml-asia -s 2005-01-01 -e 2015-12-31 -o hml_results.csv

Backtest a single strategy called demo using all available history and return a PDF tear sheet:

quantrocket moonshot backtest demo –pdf -o tearsheet.pdf

Run a backtest in 1-year segments to reduce memory usage:

quantrocket moonshot backtest big-strategy -s 2000-01-01 -e 2018-01-01 –segment A -o results.csv

paramscan¶

run a parameter scan for one or more strategies

quantrocket moonshot paramscan [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD] [-g FREQ]
                               -p PARAM -v VALUE [VALUE ...] [--param2 PARAM]
                               [--vals2 [VALUE [VALUE ...]]]
                               [-l [CODE:FLOAT [CODE:FLOAT ...]]]
                               [-n [CURRENCY:NLV [CURRENCY:NLV ...]]]
                               [--params [PARAM:VALUE [PARAM:VALUE ...]]]
                               [--no-cache] [--pdf] [-o FILEPATH]
                               CODE [CODE ...]

Positional Arguments¶

CODE: one or more strategy codes

backtest options¶

-s, --start-date

the backtest start date (default is to use all available history)

-e, --end-date

the backtest end date (default is to use all available history)

-g, --segment

backtest in date segments of this size, to reduce memory usage (use Pandas frequency string, e.g. ‘A’ for annual segments or ‘Q’ for quarterly segments)

-p, --param1

the name of the parameter to test (a class attribute on the strategy)

-v, --vals1

parameter values to test (values can be integers, floats, strings, ‘True’, ‘False’, ‘None’, or ‘default’ (to test current param value); for lists/tuples, use comma-separated values)

--param2

name of a second parameter to test (for 2-D parameter scans)

--vals2

values to test for parameter 2 (values can be integers, floats, strings, ‘True’, ‘False’, ‘None’, or ‘default’ (to test current param value); for lists/tuples, use comma-separated values)

-l, --allocations

the allocation for each strategy, passed as ‘code:allocation’ (default allocation is 1.0 / number of strategies)

-n, --nlv

the NLV (net liquidation value, i.e. account balance) to assume for the backtests, expressed in each currency represented in the backtest (pass as ‘currency:nlv’)

--params

one or more strategy params to set on the fly before backtesting (pass as ‘param:value’)

--no-cache

Default: False

output options¶

--pdf: return a PDF tear sheet of results (default is to return a CSV)
-o, --outfile: the location to write the results file (omit to write to stdout)

Run a parameter scan for one or more strategies.

By default returns a CSV of scan results but can also return a PDF tear sheet.

Examples:

Run a parameter scan for several different moving averages on a strategy called trend-friend and return a PDF:

quantrocket moonshot paramscan trend-friend -p MAVG_WINDOW -v 20 50 100 –pdf -o tearsheet.pdf

Run a 2-D parameter scan for multiple strategies and return a PDF:

quantrocket moonshot paramscan strat1 strat2 strat3 -p MIN_STD -v 1 1.5 2 –param2 STD_WINDOW –vals2 20 50 100 200 –pdf -o tearsheet.pdf

Run a parameter scan in 1-year segments to reduce memory usage:

quantrocket moonshot paramscan big-strategy -s 2000-01-01 -e 2018-01-01 –segment A -p MAVG_WINDOW -v 20 50 100 –pdf -o tearsheet.pdf

ml-walkforward¶

run a walk-forward optimization of a machine learning strategy

quantrocket moonshot ml-walkforward [-h] -s YYYY-MM-DD -e YYYY-MM-DD -t FREQ
                                    [-m FREQ] [-r FREQ] [-f MODEL_FILEPATH]
                                    [--force-nonincremental] [-g FREQ]
                                    [-l FLOAT]
                                    [-n [CURRENCY:NLV [CURRENCY:NLV ...]]]
                                    [-p [PARAM:VALUE [PARAM:VALUE ...]]]
                                    [--no-cache] [-d] [--progress]
                                    [-o FILEPATH]
                                    CODE

Positional Arguments¶

CODE: the strategy code

walk-forward analysis options¶

-s, --start-date

the analysis start date (note that model training will start on this date but backtesting will not start until after the initial training period)

-e, --end-date

the analysis end date

-t, --train

train model this frequently (use Pandas frequency string, e.g. ‘A’ for annual training or ‘Q’ for quarterly training)

-m, --min-train

don’t backtest until at least this much model training has occurred; defaults to the length of –train if not specified (use Pandas frequency string, e.g. ‘5Y’ for 5 years of initial training)

-r, --rolling-train

train model with a rolling window of this length; if omitted, train model with an expanding window (use Pandas frequency string, e.g. ‘3Y’ for a 3-year rolling training window)

-f, --model

filepath of serialized model to use, filename must end in ‘.joblib’ or ‘.pkl’ (if omitted, default model is scikit-learn’s StandardScaler+SGDRegressor)

--force-nonincremental

force the model to be trained non-incrementally (i.e. load entire training data set into memory) even if it supports incremental learning. Required in order to perform a rolling (as opposed to expanding) walk-forward optimization with a model that supports incremental learning.

Default: False

backtest options¶

-g, --segment

train and backtest in date segments of this size, to reduce memory usage; must be smaller than –train/–min-train or will have no effect (use Pandas frequency string, e.g. ‘A’ for annual segments or ‘Q’ for quarterly segments)

-l, --allocation

the allocation for the strategy (default 1.0)

-n, --nlv

the NLV (net liquidation value, i.e. account balance) to assume for the backtest, expressed in each currency represented in the backtest (pass as ‘currency:nlv’)

-p, --params

one or more strategy params to set on the fly before backtesting (pass as ‘param:value’)

--no-cache

Default: False

output options¶

-d, --details

return detailed results for all securities instead of aggregating

Default: False

--progress

log status and Sharpe ratios of each walk-forward segment during analysis (default False)

Default: False

-o, --outfile

the location to write the ZIP file to; or, if path ends with ‘*’, the pattern to use for extracting the zipped files. For example, if the path is my_ml*, files will extracted to my_ml_results.csv and my_ml_trained_model.joblib.

Run a walk-forward optimization of a machine learning strategy.

The date range will be split into segments of –train size. For each segment, the model will be trained with the data, then the trained model will be backtested on the following segment.

By default, uses scikit-learn’s StandardScaler+SGDRegressor. Also supports other scikit-learn models/pipelines and Keras models. To customize model, instantiate the model locally, serialize it to disk, and pass the filename of the serialized model as –model.

Supports expanding walk-forward optimizations (the default), which use an anchored start date for model training, or rolling walk-forward optimizations (by specifying –rolling-train), which use a rolling or non-anchored start date for model training.

Returns a backtest results CSV and a dump of the machine learning model as of the end of the analysis.

Examples:

Run a walk-forward optimization using the default model and retrain the model annually, writing the backtest results and trained model to demo_ml_results.csv and demo_ml_trained_model.joblib, respectively:

quantrocket moonshot ml-walkforward demo-ml -s 2007-01-01 -e 2018-12-31 –train A -o demo_ml*

Run a walk-forward optimization using a custom model (serialized with joblib), retrain the model annually, don’t perform backtesting until after 5 years of initial training, and further split the training and backtesting into quarterly segments to reduce memory usage:

quantrocket moonshot ml-walkforward demo-ml -s 2007-01-01 -e 2018-12-31 –model my_model.joblib –train A –min-train 5Y –segment Q -o demo_ml*

trade¶

run one or more strategies and generate orders.

quantrocket moonshot trade [-h] [-a [ACCOUNT [ACCOUNT ...]]] [-r YYYY-MM-DD]
                           [-j] [-o FILEPATH]
                           CODE [CODE ...]

Positional Arguments¶

CODE: one or more strategy codes

Named Arguments¶

-a, --accounts: limit to these accounts
-r, --review-date: generate orders as if it were this date, rather than using today’s date
-j, --json: format orders as JSON (default is CSV)
-o, --outfile: the location to write the orders file (omit to write to stdout)

Run one or more strategies and generate orders.

Allocations are read from configuration (quantrocket.moonshot.allocations.yml).

Examples:

Generate orders for a single strategy called umd-nyse:

quantrocket moonshot trade umd-nyse -o orders.csv

Generate orders and automatically place them (if any) through the blotter:

quantrocket moonshot trade umd-nyse | quantrocket blotter order -f -

Generate orders for multiple strategies for a particular account:

quantrocket moonshot trade umd-japan hml-japan –accounts DU12345 -o orders.csv

Generate orders as if it were an earlier date (for prupose of review):

quantrocket moonshot trade umd-nyse -o orders.csv –review-date 2018-05-11

quantrocket.moonshot.backtest(strategies, start_date=None, end_date=None, segment=None, allocations=None, nlv=None, params=None, details=None, output='csv', filepath_or_buffer=None, no_cache=False)¶

Backtest one or more strategies.

By default returns a CSV of backtest results but can also return a PDF tear sheet of performance charts.

If testing multiple strategies, each column in the CSV represents a strategy. If testing a single strategy and details=True, each column in the CSV represents a security in the strategy universe.

Parameters

strategies (list of str, required) – one or more strategy codes
start_date (str (YYYY-MM-DD), optional) – the backtest start date (default is to use all available history)
end_date (str (YYYY-MM-DD), optional) – the backtest end date (default is to use all available history)
segment (str, optional) – backtest in date segments of this size, to reduce memory usage (use Pandas frequency string, e.g. ‘A’ for annual segments or ‘Q’ for quarterly segments)
allocations (dict of CODE:FLOAT, optional) – the allocation for each strategy, passed as {code:allocation} (default allocation is 1.0 / number of strategies)
nlv (dict of CURRENCY:NLV, optional) – the NLV (net liquidation value, i.e. account balance) to assume for the backtest, expressed in each currency represented in the backtest (pass as {currency:nlv})
params (dict of PARAM:VALUE, optional) – one or more strategy params to set on the fly before backtesting (pass as {param:value})
details (bool) – return detailed results for all securities instead of aggregating to strategy level (only supported for single-strategy backtests)
output (str, required) – the output format (choices are csv or pdf)
filepath_or_buffer (str, optional) – the location to write the results file (omit to write to stdout)
no_cache (bool) – don’t use cached files even if available. Using cached files speeds up backtests but may be undesirable if underlying data has changed. See http://qrok.it/h/mcache to learn more about caching in Moonshot.

Returns

Return type

None

Examples

Backtest several HML (High Minus Low) strategies from 2005-2015 and return a CSV of results:

>>> backtest(["hml-us", "hml-eur", "hml-asia"],
             start_date="2005-01-01",
             end_date="2015-12-31",
             filepath_or_buffer="hml_results.csv")

Run a backtest in 1-year segments to reduce memory usage:

>>> backtest("big-strategy",
             start_date="2000-01-01",
             end_date="2018-01-01",
             segment="A",
             filepath_or_buffer="results.csv")

See also

read_moonshot_csv(): load a Moonshot backtest CSV into a DataFrame

quantrocket.moonshot.read_moonshot_csv(filepath_or_buffer)¶

Load a Moonshot backtest CSV into a DataFrame.

This is a light wrapper around pd.read_csv that handles setting index columns and casting to proper data types.

Parameters: filepath_or_buffer (string or file-like, required) – path to CSV
Returns: a multi-index (Field, Date[, Time]) DataFrame of backtest results, with sids or strategy codes as columns
Return type: DataFrame

Examples

>>> results = read_moonshot_csv("moonshot_backtest.csv")
>>> returns = results.loc["Return"]

quantrocket.moonshot.scan_parameters(strategies, start_date=None, end_date=None, segment=None, param1=None, vals1=None, param2=None, vals2=None, allocations=None, nlv=None, params=None, output='csv', filepath_or_buffer=None, no_cache=False)¶

Run a parameter scan for one or more strategies.

By default returns a CSV of scan results but can also return a PDF tear sheet.

Parameters

strategies (list of str, required) – one or more strategy codes
start_date (str (YYYY-MM-DD), optional) – the backtest start date (default is to use all available history)
end_date (str (YYYY-MM-DD), optional) – the backtest end date (default is to use all available history)
segment (str, optional) – backtest in date segments of this size, to reduce memory usage (use Pandas frequency string, e.g. ‘A’ for annual segments or ‘Q’ for quarterly segments)
param1 (str, required) – the name of the parameter to test (a class attribute on the strategy)
vals1 (list of int/float/str/tuple, required) – parameter values to test (values can be ints, floats, strings, False, True, None, ‘default’ (to test current param value), or lists of ints/floats/strings)
param2 (str, optional) – name of a second parameter to test (for 2-D parameter scans)
vals2 (list of int/float/str/tuple, optional) – values to test for parameter 2 (values can be ints, floats, strings, False, True, None, ‘default’ (to test current param value), or lists of ints/floats/strings)
allocations (dict of CODE:FLOAT, optional) – the allocation for each strategy, passed as {code:allocation} (default allocation is 1.0 / number of strategies)
nlv (dict of CURRENCY:NLV, optional) – the NLV (net liquidation value, i.e. account balance) to assume for the backtest, expressed in each currency represented in the backtest (pass as {currency:nlv})
params (dict of PARAM:VALUE, optional) – one or more strategy params to set on the fly before backtesting (pass as {param:value})
output (str, required) – the output format (choices are csv or pdf)
filepath_or_buffer (str, optional) – the location to write the results file (omit to write to stdout)
no_cache (bool) – don’t use cached files even if available. Using cached files speeds up backtests but may be undesirable if underlying data has changed. See http://qrok.it/h/mcache to learn more about caching in Moonshot.

Returns

Return type

None

Examples

Run a parameter scan for several different moving averages on a strategy called trend-friend and return a CSV (which can be rendered with Moonchart):

>>> scan_parameters("trend-friend",
                    param1="MAVG_WINDOW",
                    vals1=[20, 50, 100],
                    filepath_or_buffer="trend_friend_MAVG_WINDOW.csv")

Run a 2-D parameter scan for multiple strategies and return a CSV:

>>> scan_parameters(["strat1", "strat2", "strat3"],
                    param1="MIN_STD",
                    vals1=[1, 1.5, 2],
                    param2="STD_WINDOW",
                    vals2=[20, 50, 100, 200],
                    filepath_or_buffer="strategies_MIN_STD_and_STD_WINDOW.csv")

Run a parameter scan in 1-year segments to reduce memory usage:

>>> scan_parameters("big-strategy",
                    start_date="2000-01-01",
                    end_date="2018-01-01",
                    segment="A",
                    param1="MAVG_WINDOW",
                    vals1=[20, 50, 100],
                    filepath_or_buffer="big_strategy_MAVG_WINDOW.csv")

quantrocket.moonshot.ml_walkforward(strategy, start_date, end_date, train, min_train=None, rolling_train=None, model_filepath=None, force_nonincremental=None, segment=None, allocation=None, nlv=None, params=None, details=None, progress=False, filepath_or_buffer=None, no_cache=False)¶

Run a walk-forward optimization of a machine learning strategy.

The date range will be split into segments of train size. For each segment, the model will be trained with the data, then the trained model will be backtested on the following segment.

Supports expanding walk-forward optimizations (the default), which use an anchored start date for model training, or rolling walk-forward optimizations (by specifying rolling_train), which use a rolling or non-anchored start date for model training.

Returns a backtest results CSV and a dump of the machine learning model as of the end of the analysis.

Parameters

strategy (str, required) – the strategy code
start_date (str (YYYY-MM-DD), required) – the analysis start date (note that model training will start on this date but backtesting will not start until after the initial training period)
end_date (str (YYYY-MM-DD), required) – the analysis end date
train (str, required) – train model this frequently (use Pandas frequency string, e.g. ‘A’ for annual training or ‘Q’ for quarterly training)
min_train (str, optional) – don’t backtest until at least this much model training has occurred; defaults to the length of train if not specified (use Pandas frequency string, e.g. ‘5Y’ for 5 years of initial training)
rolling_train (str, optional) – train model with a rolling window of this length; if omitted, train model with an expanding window (use Pandas frequency string, e.g. ‘3Y’ for a 3-year rolling training window)
model_filepath (str, optional) – filepath of serialized model to use, filename must end in “.joblib” or “.pkl” (if omitted, default model is scikit-learn’s StandardScaler+SGDRegressor)
force_nonincremental (bool, optional) – force the model to be trained non-incrementally (i.e. load entire training data set into memory) even if it supports incremental learning. Must be True in order to perform a rolling (as opposed to expanding) walk-forward optimization with a model that supports incremental learning. Default False.
segment (str, optional) – train and backtest in date segments of this size, to reduce memory usage; must be smaller than train/min_train or will have no effect (use Pandas frequency string, e.g. ‘A’ for annual segments or ‘Q’ for quarterly segments)
allocation (float, optional) – the allocation for the strategy (default 1.0)
nlv (dict of CURRENCY:NLV, optional) – the NLV (net liquidation value, i.e. account balance) to assume for the backtest, expressed in each currency represented in the backtest (pass as {currency:nlv})
params (dict of PARAM:VALUE, optional) – one or more strategy params to set on the fly before backtesting (pass as {param:value})
details (bool) – return detailed results for all securities instead of aggregating
progress (bool) – log status and Sharpe ratios of each walk-forward segment during analysis (default False)
filepath_or_buffer (str, optional) – the location to write the ZIP file to; or, if path ends with “*”, the pattern to use for extracting the zipped files. For example, if the path is my_ml*, files will extracted to my_ml_results.csv and my_ml_trained_model.joblib.
no_cache (bool) – don’t use cached files even if available. Using cached files speeds up backtests but may be undesirable if underlying data has changed. See http://qrok.it/h/mcache to learn more about caching in Moonshot.

Returns

Return type

None

Examples

>>> ml_walkforward(
        "demo-ml",
        "2007-01-01",
        "2018-12-31",
        train="A",
        filepath_or_buffer="demo_ml*")

Create a scikit-learn model, serialize it with joblib, and use it to run the walkforward backtest:

>>> from sklearn.linear_model import SGDClassifier
>>> import joblib
>>> clf = SGDClassifier()
>>> joblib.dump(clf, "my_model.joblib")
>>> ml_walkforward(
        "demo-ml",
        "2007-01-01",
        "2018-12-31",
        train="A",
        model_filepath="my_model.joblib",
        filepath_or_buffer="demo_ml*")

>>> ml_walkforward(
        "demo-ml",
        "2007-01-01",
        "2018-12-31",
        model_filepath="my_model.joblib",
        train="A",
        min_train="5Y",
        segment="Q",
        filepath_or_buffer="demo_ml*")

Create a Keras model, serialize it, and use it to run the walkforward backtest:

>>> from keras.models import Sequential
>>> from keras.layers import Dense
>>> model = Sequential()
>>> # input_dim should match number of features in training data
>>> model.add(Dense(units=4, activation='relu', input_dim=5))
>>> # last layer should have a single unit
>>> model.add(Dense(units=1, activation='softmax'))
>>> model.compile(loss='sparse_categorical_crossentropy',
                  optimizer='sgd',
                  metrics=['accuracy'])
>>> model.save('my_model.keras.h5')
>>> ml_walkforward(
        "neuralnet-ml",
        "2007-01-01",
        "2018-12-31",
        train="A",
        model_filepath="my_model.keras.h5",
        filepath_or_buffer="neuralnet_ml*")

quantrocket.moonshot.trade(strategies, accounts=None, review_date=None, output='csv', filepath_or_buffer=None)¶

Run one or more strategies and generate orders.

Allocations are read from configuration (quantrocket.moonshot.allocations.yml).

Parameters

strategies (list of str, required) – one or more strategy codes
accounts (list of str, optional) – limit to these accounts
review_date (str (YYYY-MM-DD), optional) – generate orders as if it were this date, rather than using today’s date
output (str, required) – the output format (choices are csv or json)
filepath_or_buffer (str, optional) – the location to write the orders file (omit to write to stdout)

Returns

Return type

None

Moonshot API

Resource Group ¶

Backtests ¶

Run Backtest
POST`/moonshot/backtests.{output}{?strategies,start_date,end_date,segment,allocations,nlv,params,details,no_cache}`

Backtest one or more strategies and return a CSV of backtest results or a PDF tear sheet of performance charts.

If testing multiple strategies, each column in the CSV represents a strategy. If testing a single strategy and details=True, each column in the CSV represents a security in the strategy universe.

Example URI

POST http://houston/moonshot/backtests.csv?strategies=umd-nyse&start_date=2015-02-01&end_date=2017-06-06&segment=A&allocations=umd-nyse:0.25&nlv=USD:500000&params=BENCHMARK:None&details=true&no_cache=false

URI Parameters

strategies: str (required) Example: umd-nyse
the strategy code to test (pass multiple times for multiple strategies)
start_date: str (optional) Example: 2015-02-01
the backtest start date (default is to use all available history)
end_date: str (optional) Example: 2017-06-06
the backtest end date (default is to use all available history)
segment: str (optional) Example: A
backtest in date segments of this size, to reduce memory usage (use Pandas frequency string, e.g. ‘A’ for annual segments or ‘Q’ for quarterly segments)
allocations: str (optional) Example: umd-nyse:0.25
the allocation for each strategy, passed as ‘code:allocation’ (default allocation is 1.0 / number of strategies) (pass multiple times for multiple strategies)
nlv: str (optional) Example: USD:500000
the NLV (net liquidation value, i.e. account balance) to assume for the backtest, expressed in each currency represented in the backtest (pass as ‘currency:nlv’) (pass multiple times for multiple currencies)
params: str (optional) Example: BENCHMARK:None
one or more strategy params to set on the fly before backtesting (pass as ‘param:value’) (pass multiple times for multiple params)
details: bool (optional) Example: true
return detailed results for all securities instead of aggregating to strategy level (only supported for single-strategy backtests)
output: str (required) Example: csv
the output format (choices are csv or pdf)
no_cache: bool (required) Example: false
don’t use cached files even if available. Using cached files speeds up backtests but may be undesirable if underlying data has changed.

Response 200

Headers

Content-Type: text/csv

Response 200

Headers

Content-Type: application/pdf

Parameter Scans ¶

Run Parameter Scan
POST`/moonshot/paramscans.{output}{?strategies,start_date,end_date,segment,param1,vals1,param2,vals2,allocations,nlv,params,no_cache}`

Run a parameter scan for one or more strategies and return a PDF tear sheet of results or a CSV.

Example URI

POST http://houston/moonshot/paramscans.csv?strategies=umd-nyse&start_date=2015-02-01&end_date=2017-06-06&segment=A&param1=SMAVG_WINDOW&vals1=20&param2=LMAVG_WINDOW&vals2=180&allocations=umd-nyse:0.25&nlv=USD:500000&params=BENCHMARK:None&no_cache=false

URI Parameters

strategies: str (required) Example: umd-nyse
the strategy code to test (pass multiple times for multiple strategies)
start_date: str (optional) Example: 2015-02-01
the backtest start date (default is to use all available history)
end_date: str (optional) Example: 2017-06-06
the backtest end date (default is to use all available history)
segment: str (optional) Example: A
backtest in date segments of this size, to reduce memory usage (use Pandas frequency string, e.g. ‘A’ for annual segments or ‘Q’ for quarterly segments)
param1: str (required) Example: SMAVG_WINDOW
the name of the parameter to test (a class attribute on the strategy)
vals1: str (required) Example: 20
parameter values to test (values can be ints, floats, strings, False, True, None, ‘default’ (to test current param value), or lists of ints/floats/strings) (pass multiple times for multiple values)
param2: str (optional) Example: LMAVG_WINDOW
name of a second parameter to test (for 2-D parameter scans)
vals2: str (optional) Example: 180
values to test for parameter 2 (values can be ints, floats, strings, False, True, None, ‘default’ (to test current param value), or lists of ints/floats/strings) (pass multiple times for multiple values)
allocations: str (optional) Example: umd-nyse:0.25
the allocation for each strategy, passed as ‘code:allocation’ (default allocation is 1.0 / number of strategies) (pass multiple times for multiple strategies)
nlv: str (optional) Example: USD:500000
the NLV (net liquidation value, i.e. account balance) to assume for the backtest, expressed in each currency represented in the backtest (pass as ‘currency:nlv’) (pass multiple times for multiple currencies)
params: str (optional) Example: BENCHMARK:None
one or more strategy params to set on the fly before backtesting (pass as ‘param:value’) (pass multiple times for multiple params)
output: str (required) Example: csv
the output format (choices are csv or pdf)
no_cache: bool (required) Example: false
don’t use cached files even if available. Using cached files speeds up backtests but may be undesirable if underlying data has changed.

Response 200

Headers

Content-Type: text/csv

Response 200

Headers

Content-Type: application/pdf

Walk-forward Optimizations ¶

Run Walk-forward Optimization
POST`/moonshot/ml/walkforward/{code}.zip{?start_date,end_date,train,min_train,rolling_train,force_nonincremental,segment,allocation,nlv,params,details,progress,no_cache}`

Run a walk-forward optimization of a machine learning strategy.

The date range will be split into segments of train size. For each segment, the model will be trained with the data, then the trained model will be backtested on the following segment.

Supports expanding walk-forward optimizations (the default), which use an anchored start date for model training, or rolling walk-forward optimizations (by specifying rolling_train), which use a rolling or non-anchored start date for model training.

Returns a backtest results CSV and a dump of the machine learning model as of the end of the analysis.

Example URI

POST http://houston/moonshot/ml/walkforward/demo-ml.zip?start_date=2015-02-01&end_date=2017-06-06&train=Y&min_train=5Y&rolling_train=3Y&force_nonincremental=false&segment=A&allocation=1.0&nlv=USD:500000&params=BENCHMARK:None&details=true&progress=true&no_cache=false

URI Parameters

code: str (required) Example: demo-ml
the strategy code
start_date: str (required) Example: 2015-02-01
the analysis start date (note that model training will start on this date but backtesting will not start until after the initial training period)
end_date: str (required) Example: 2017-06-06
the analysis end date
train: str (required) Example: Y
train model this frequently (use Pandas frequency string, e.g. ‘A’ for annual training or ‘Q’ for quarterly training)
min_train: str (optional) Example: 5Y
don’t backtest until at least this much model training has occurred; defaults to the length of train if not specified (use Pandas frequency string, e.g. ‘5Y’ for 5 years of initial training)
rolling_train: str (optional) Example: 3Y
train model with a rolling window of this length; if omitted, train model with an expanding window (use Pandas frequency string, e.g. ‘3Y’ for a 3-year rolling training window)
force_nonincremental: bool (optional) Example: false
force the model to be trained non-incrementally (i.e. load entire training data set into memory) even if it supports incremental learning. Must be true in order to perform a rolling (as opposed to expanding) walk-forward optimization with a model that supports incremental learning. Default false.
segment: str (optional) Example: A
train and backtest in date segments of this size, to reduce memory usage; must be smaller than train/min_train or will have no effect (use Pandas frequency string, e.g. ‘A’ for annual segments or ‘Q’ for quarterly segments)
allocation: float (optional) Example: 1.0
the allocation for the strategy (default 1.0)
nlv: str (optional) Example: USD:500000
the NLV (net liquidation value, i.e. account balance) to assume for the backtest, expressed in each currency represented in the backtest (pass as ‘currency:nlv’) (pass multiple times for multiple currencies)
params: str (optional) Example: BENCHMARK:None
one or more strategy params to set on the fly before backtesting (pass as ‘param:value’) (pass multiple times for multiple params)
details: bool (optional) Example: true
return detailed results for all securities instead of aggregating
progress: bool (optional) Example: true
log status and Sharpe ratios of each walk-forward segment during analysis (default false)
no_cache: bool (required) Example: false
don’t use cached files even if available. Using cached files speeds up backtests but may be undesirable if underlying data has changed.

Response 200

Headers

Content-Type: application/zip

Orders ¶

Generate Orders
GET`/moonshot/orders.{output}{?strategies,accounts,review_date}`

Run one or more strategies and generate orders. Allocations are read from configuration (quantrocket.moonshot.allocations.yml).

Example URI

GET http://houston/moonshot/orders.csv?strategies=umd-nyse&accounts=U12345&review_date=2018-05-18

URI Parameters

strategies: str (required) Example: umd-nyse
the strategy code to run (pass multiple times for multiple strategies)
accounts: str (optional) Example: U12345
limit to these accounts (pass multiple times for multiple accounts)
review_date: str (optional) Example: 2018-05-18
generate orders as if it were this date, rather than using today’s date
output: str (required) Example: csv
the output format (choices are csv or json)

Response 200

Headers

Content-Type: text/csv

Response 200

Headers

Content-Type: application/json

quantrocket.realtime

real-time market data service

QuantRocket real-time market data CLI

usage: quantrocket realtime [-h]
                            {create-ibkr-tick-db,create-polygon-tick-db,create-agg-db,config,drop-db,drop-ticks,list,collect,active,cancel,get,stream}
                            ...

subcommands¶

subcommand: Possible choices: create-ibkr-tick-db, create-polygon-tick-db, create-agg-db, config, drop-db, drop-ticks, list, collect, active, cancel, get, stream

Sub-commands:¶

create-ibkr-tick-db¶

create a new database for collecting real-time tick data from Interactive Brokers

quantrocket realtime create-ibkr-tick-db [-h] [-u [UNIVERSE [UNIVERSE ...]]]
                                         [-i [SID [SID ...]]]
                                         [-f [FIELD [FIELD ...]]] [-p]
                                         CODE

Positional Arguments¶

CODE: the code to assign to the database (lowercase alphanumerics and hyphens only)

Named Arguments¶

-u, --universes

include these universes

-i, --sids

include these sids

-f, --fields

collect these fields (pass ‘?’ or any invalid fieldname to see available fields, default fields are ‘LastPrice’ and ‘Volume’)

-p, --primary-exchange

limit to data from the primary exchange

Default: False

Create a new database for collecting real-time tick data from Interactive Brokers.

The market data requirements you specify when you create a new database are applied each time you collect data for that database.

Examples:

Create a database for collecting real-time trades and volume for US stocks:

quantrocket realtime create-ibkr-tick-db usa-stk-trades -u usa-stk –fields LastPrice Volume

Create a database for collecting trades and quotes for a universe of futures:

quantrocket realtime create-ibkr-tick-db globex-fut-taq -u globex-fut –fields LastPrice Volume BidPrice AskPrice BidSize AskSize

create-polygon-tick-db¶

create a new database for collecting real-time tick data from Polygon

quantrocket realtime create-polygon-tick-db [-h]
                                            [-u [UNIVERSE [UNIVERSE ...]]]
                                            [-i [SID [SID ...]]]
                                            [-f [FIELD [FIELD ...]]]
                                            CODE

Positional Arguments¶

CODE: the code to assign to the database (lowercase alphanumerics and hyphens only)

Named Arguments¶

-u, --universes: include these universes
-i, --sids: include these sids
-f, --fields: collect these fields (pass ‘?’ or any invalid fieldname to see available fields, default fields are ‘LastPrice’ and ‘LastSize’)

Create a new database for collecting real-time tick data from Polygon.

The market data requirements you specify when you create a new database are applied each time you collect data for that database.

Examples:

Create a database for collecting real-time trade prices and sizes for US stocks:

quantrocket realtime create-polygon-tick-db usa-stk-trades -u usa-stk –fields LastPrice LastSize

create-agg-db¶

create an aggregate database from a tick database

quantrocket realtime create-agg-db [-h] -t CODE -z BAR_SIZE
                                   [-f [FIELD [FIELD ...]]]
                                   CODE

Positional Arguments¶

CODE: the code to assign to the aggregate database (lowercase alphanumerics and hyphens only)

Named Arguments¶

-t, --tick-db: the code of the tick database to aggregate
-z, --bar-size: the time frequency to aggregate to (use a Pandas timedelta string, for example 10s or 1m or 2h or 1d)
-f, --fields: include these fields in aggregate database, aggregated in these ways. Specify as a list of strings mapping tick db fields to a comma-separated list of aggregate functions to apply to the field. Format strings as ‘FIELD:FUNC1,FUNC2’. Available aggregate functions are ‘Close’, ‘Open’, ‘High’, ‘Low’, ‘Mean’, ‘Sum’, and ‘Count’. See examples. If not specified, defaults to including the ‘Close’ for each tick db field.

Create an aggregate database from a tick database.

Aggregate databases provide rolled-up views of the underlying tick data, aggregated to a desired frequency (such as 1-minute bars).

Examples:

Create an aggregate database of 1 minute bars consisting of OHLC trades and volume, from a tick database of US stocks, resulting in fields called LastPriceOpen, LastPriceHigh, LastPriceLow, LastPriceClose, and VolumeClose:

quantrocket realtime create-agg-db usa-stk-trades-1min –tick-db usa-stk-trades -z 1m -f LastPrice:Open,High,Low,Close Volume:Close

Create an aggregate database of 1 second bars containing the closing bid and ask and the mean bid size and ask size, from a tick database of futures trades and quotes, resulting in fields called BidPriceClose, AskPriceClose, BidSizeMean, and AskSizeMean:

quantrocket realtime create-agg-db globex-fut-taq-1sec –tick-db globex-fut-taq -z 1s -f BidPrice:Close AskPrice:Close BidSize:Mean AskSize:Mean

config¶

return the configuration for a tick database or aggregate database

quantrocket realtime config [-h] code

Positional Arguments¶

code: the tick database code or aggregate database code

Return the configuration for a tick database or aggregate database.

Examples:

Return the configuration for a tick database called “globex-fut-taq”:

quantrocket realtime config globex-fut-taq

Return the configuration for an aggregate database called “globex-fut-taq-1s”:

quantrocket realtime config globex-fut-taq-1s

drop-db¶

delete a tick database or aggregate database

quantrocket realtime drop-db [-h] --confirm-by-typing-db-code-again CODE
                             [--cascade]
                             code

Positional Arguments¶

code: the tick database code or aggregate database code

Named Arguments¶

--confirm-by-typing-db-code-again

enter the db code again to confirm you want to drop the database, its config, and all its data

--cascade

also delete associated aggregated databases, if any. Only applicable when deleting a tick database.

Default: False

Delete a tick database or aggregate database.

Deleting a tick database deletes its configuration and data and any associated aggregate databases. Deleting an aggregate database does not delete the tick database from which it is derived.

Deleting databases is irreversible.

Examples:

Delete a database called “usa-stk-trades”:

quantrocket realtime drop-db usa-stk-trades –confirm-by-typing-db-code-again usa-stk-trades

drop-ticks¶

delete ticks from a tick database

quantrocket realtime drop-ticks [-h] -o TIMEDELTA code

Positional Arguments¶

code: the tick database code

Named Arguments¶

-o, --older-than: delete ticks older than this (use a Pandas timedelta string, for example 7d)

Delete ticks from a tick database. Does not delete any aggregate database records.

Deleting ticks is a way to free up disk space by deleting ticks older than a certain threshold while maintaining the ability to continue collecting new ticks as well as use any aggregate databases derived from the ticks.

Note: ticks are stored in the database in chunks, and this command only deletes chunks in which all of the ticks are older than you specify. If some of the ticks are older but some are newer, the chunk is not deleted. This means you may still see older data returned in queries.

Examples:

Delete ticks older than 7 days in a database called ‘usa-tech-stk-tick’ (no aggregate records are deleted):

quantrocket realtime drop-ticks usa-tech-stk-tick –older-than 7d

list¶

list tick databases and associated aggregate databases

quantrocket realtime list [-h]

List tick databases and associated aggregate databases.

Examples:

quantrocket realtime list

collect¶

collect real-time market data and save it to a tick database

quantrocket realtime collect [-h] [-i [SID [SID ...]]]
                             [-u [UNIVERSE [UNIVERSE ...]]]
                             [-f [FIELD [FIELD ...]]]
                             [--until TIME_OR_TIMEDELTA] [-s] [-w]
                             CODE [CODE ...]

Positional Arguments¶

CODE: the tick database code(s) to collect data for

Named Arguments¶

-i, --sids

collect market data for these sids, overriding db config (typically used to collect a subset of securities)

-u, --universes

collect market data for these universes, overriding db config (typically used to collect a subset of securities)

-f, --fields

limit to these fields, overriding db config

--until

schedule data collection to end at this time. Can be a datetime (YYYY-MM-DD HH:MM:SS), a time (HH:MM:SS), or a Pandas timedelta string (e.g. 2h or 30min). If not provided, market data is collected until cancelled.

-s, --snapshot

collect a snapshot of market data (default is to collect a continuous stream of market data)

Default: False

-w, --wait

wait for market data snapshot to complete before returning (default is to return immediately). Requires –snapshot

Default: False

Collect real-time market data and save it to a tick database.

A single snapshot of market data or a continuous stream of market data can be collected, depending on the –snapshot parameter. (Snapshots are not supported for all vendors.)

Streaming real-time data is collected until cancelled, or can be scheduled for cancellation using the –until parameter.

Examples:

Collect market data for all securities in a tick database called ‘japan-banks-trades’:

quantrocket realtime collect japan-banks-trades

Collect market data for a subset of securities in a tick database called ‘usa-stk-trades’ and automatically cancel the data collection in 30 minutes:

quantrocket realtime collect usa-stk-trades –sids FIBBG12345 FIBBG23456 FIBBG34567 –until 30m

Collect a market data snapshot and wait until it completes:

quantrocket realtime collect usa-stk-trades –snapshot –wait

active¶

return the number of tickers currently being collected, by vendor and database

quantrocket realtime active [-h] [-d]

Named Arguments¶

-d, --detail

return lists of tickers (default is to return counts of tickers)

Default: False

Return the number of tickers currently being collected, by vendor and database.

Examples:

quantrocket realtime active

cancel¶

cancel market data collection

quantrocket realtime cancel [-h] [-i [SID [SID ...]]]
                            [-u [UNIVERSE [UNIVERSE ...]]] [-a]
                            [CODE [CODE ...]]

Positional Arguments¶

CODE: the tick database code(s) to cancel collection for

Named Arguments¶

-i, --sids

cancel market data for these sids, overriding db config

-u, --universes

cancel market data for these universes, overriding db config

-a, --all

cancel all market data collection

Default: False

Cancel market data collection.

Examples:

Cancel market data collection for a tick database called ‘globex-fut-taq’:

quantrocket realtime cancel globex-fut-taq

Cancel all market data collection:

quantrocket realtime cancel –all

get¶

query market data from a tick database or aggregate database and download to file

quantrocket realtime get [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                         [-u [UNIVERSE [UNIVERSE ...]]] [-i [SID [SID ...]]]
                         [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                         [--exclude-sids [SID [SID ...]]] [-o OUTFILE] [-j]
                         [-f [FIELD [FIELD ...]]]
                         CODE

Positional Arguments¶

CODE: the code of the tick database or aggregate database to query

filtering options¶

-s, --start-date: limit to market data on or after this datetime. Can pass a date (YYYY-MM-DD), datetime with optional timezone (YYYY-MM-DD HH:MM:SS TZ), or time with optional timezone. A time without date will be interpreted as referring to today if the time is earlier than now, or yesterday if the time is later than now.
-e, --end-date: limit to market data on or before this datetime. Can pass a date (YYYY-MM-DD), datetime with optional timezone (YYYY-MM-DD HH:MM:SS TZ), or time with optional timezone.
-u, --universes: limit to these universes
-i, --sids: limit to these sids
--exclude-universes: exclude these universes
--exclude-sids: exclude these sids

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-j, --json: format output as JSON (default is CSV)
-f, --fields: only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Query market data from a tick database or aggregate database and download to file.

Examples:

Download a CSV of futures market data since 08:00 AM Chicago time:

quantrocket realtime get globex-fut-taq –start-date ‘08:00:00 America/Chicago’ -o globex_taq.csv

stream¶

stream incoming market data

quantrocket realtime stream [-h] [-i [SID [SID ...]]]
                            [--exclude-sids [SID [SID ...]]]
                            [-f [FIELD [FIELD ...]]]

Named Arguments¶

-i, --sids: limit to these sids
--exclude-sids: exclude these sids
-f, --fields: limit to these fields

Stream incoming market data.

This command does not cause data to be collected but connects to the stream of data already being collected.

Examples:

Stream all incoming market data:

quantrocket realtime stream

Stream a subset of fields and sids:

quantrocket realtime stream –sids FIBBG265598 –fields BidPrice AskPrice

quantrocket.realtime.create_ibkr_tick_db(code, universes=None, sids=None, fields=None, primary_exchange=False)¶

Create a new database for collecting real-time tick data from Interactive Brokers.

The market data requirements you specify when you create a new database are applied each time you collect data for that database.

Parameters

code (str, required) – the code to assign to the database (lowercase alphanumerics and hyphens only)
universes (list of str) – include these universes
sids (list of str) – include these sids
fields (list of str) – collect these fields (pass ‘?’ or any invalid fieldname to see available fields, default fields are ‘LastPrice’ and ‘Volume’)
primary_exchange (bool) – limit to data from the primary exchange (default False)

Returns

status message

Return type

dict

Examples

Create a database for collecting real-time trades and volume for US stocks:

>>> create_ibkr_tick_db("usa-stk-trades", universes="usa-stk",
                        fields=["LastPrice", "Volume"])

Create a database for collecting trades and quotes for a universe of futures:

>>> create_ibkr_tick_db("globex-fut-taq", universes="globex-fut",
                        fields=["LastPrice", "Volume", "BidPrice", "AskPrice", "BidSize", "AskSize"])

quantrocket.realtime.create_polygon_tick_db(code, universes=None, sids=None, fields=None)¶

Create a new database for collecting real-time tick data from Polygon.

The market data requirements you specify when you create a new database are applied each time you collect data for that database.

Parameters

code (str, required) – the code to assign to the database (lowercase alphanumerics and hyphens only)
universes (list of str) – include these universes
sids (list of str) – include these sids
fields (list of str) – collect these fields (pass ‘?’ or any invalid fieldname to see available fields, default fields are ‘LastPrice’ and ‘LastSize’)

Returns

status message

Return type

dict

Examples

Create a database for collecting real-time trade prices and sizes for US stocks:

>>> create_polygon_tick_db("usa-stk-trades", universes="usa-stk", fields=["LastPrice", "LastSize"])

quantrocket.realtime.create_agg_db(code, tick_db_code, bar_size, fields=None)¶

Create an aggregate database from a tick database.

Aggregate databases provide rolled-up views of the underlying tick data, aggregated to a desired frequency (such as 1-minute bars).

Parameters

code (str, required) – the code to assign to the aggregate database (lowercase alphanumerics and hyphens only)
tick_db_code (str, required) – the code of the tick database to aggregate
bar_size (str, required) – the time frequency to aggregate to (use a Pandas timedelta string, for example 10s or 1m or 2h or 1d)
fields (dict of list of str, optional) – include these fields in aggregate database, aggregated in these ways. Provide a dict mapping tick db fields to lists of aggregate functions to apply to the field. Available aggregate functions are “Close”, “Open”, “High”, “Low”, “Mean”, “Sum”, and “Count”. See examples section. If not specified, defaults to including the “Close” for each tick db field.

Returns

status message

Return type

dict

Examples

>>> create_agg_db("usa-stk-trades-1min", tick_db_code="usa-stk-trades",
                  bar_size="1m",
                  fields={"LastPrice":["Open","High","Low","Close"],
                          "Volume": ["Close"]})

>>> create_agg_db("globex-fut-taq-1sec", tick_db_code="globex-fut-taq",
                  bar_size="1s",
                  fields={"BidPrice":["Close"],
                          "AskPrice": ["Close"],
                          "BidSize": ["Mean"],
                          "AskSize": ["Mean"]
                          })

quantrocket.realtime.get_db_config(code)¶

Return the configuration for a tick database or aggregate database.

Parameters: code (str, required) – the tick database code or aggregate database code
Returns: config
Return type: dict

quantrocket.realtime.drop_db(code, confirm_by_typing_db_code_again=None, cascade=False)¶

Delete a tick database or aggregate database.

Deleting a tick database deletes its configuration and data and any associated aggregate databases. Deleting an aggregate database does not delete the tick database from which it is derived.

Deleting databases is irreversible.

Parameters

code (str, required) – the tick database code or aggregate database code
confirm_by_typing_db_code_again (str, required) – enter the db code again to confirm you want to drop the database, its config, and all its data
cascade (bool) – also delete associated aggregated databases, if any. Only applicable when deleting a tick database.

Returns

status message

Return type

dict

See also

drop_ticks(): Delete ticks from a tick database.

quantrocket.realtime.drop_ticks(code, older_than=None)¶

Delete ticks from a tick database. Does not delete any aggregate database records.

Note: ticks are stored in the database in chunks, and this function only deletes chunks in which all of the ticks are older than you specify. If some of the ticks are older but some are newer, the chunk is not deleted. This means you may still see older data returned in queries.

Parameters

code (str, required) – the tick database code
older_than (str, required) –

delete ticks older than this (use a Pandas timedelta string, for example
7d)

Returns

status message

Return type

dict

See also

drop_db(): Delete a tick database or aggregate database.

Examples

Delete ticks older than 7 days in a database called ‘usa-tech-stk-tick’ (no aggregate records are deleted):

>>> drop_ticks("usa-tech-stk-tick", older_than="7d")

quantrocket.realtime.list_databases()¶

List tick databases and associated aggregate databases.

Returns: dict of {tick_db: [agg_dbs]}
Return type: dict

quantrocket.realtime.collect_market_data(codes, sids=None, universes=None, fields=None, until=None, snapshot=False, wait=False)¶

Collect real-time market data and save it to a tick database.

A single snapshot of market data or a continuous stream of market data can be collected, depending on the snapshot parameter. (Snapshots are not supported for all vendors.)

Streaming real-time data is collected until cancelled, or can be scheduled for cancellation using the until parameter.

Parameters

codes (list of str, required) – the tick database code(s) to collect data for
sids (list of str, optional) – collect market data for these sids, overriding db config (typically used to collect a subset of securities)
universes (list of str, optional) – collect market data for these universes, overriding db config (typically used to collect a subset of securities)
fields (list of str, optional) – limit to these fields, overriding db config
until (str, optional) – schedule data collection to end at this time. Can be a datetime (YYYY-MM-DD HH:MM:SS), a time (HH:MM:SS), or a Pandas timedelta string (e.g. 2h or 30min). If not provided, market data is collected until cancelled.
snapshot (bool) – collect a snapshot of market data (default is to collect a continuous stream of market data)
wait (bool) – wait for market data snapshot to complete before returning (default is to return immediately). Requires ‘snapshot=True’

Returns

status message

Return type

dict

Examples

Collect market data for all securities in a tick database called ‘japan-banks-trades’:

>>> collect_market_data("japan-banks-trades")

Collect market data for a subset of securities in a tick database called ‘usa-stk-trades’ and automatically cancel the data collection in 30 minutes:

>>> collect_market_data("usa-stk-trades",
                        sids=["FIBBG12345", "FIBBG23456", "FIBBG34567"],
                        until="30m")

Collect a market data snapshot and wait until it completes:

>>> collect_market_data("usa-stk-trades", snapshot=True, wait=True)

quantrocket.realtime.get_active_collections(detail=False)¶

Return the number of tickers currently being collected, by vendor and database.

Parameters: detail (bool) – return lists of tickers (default is to return counts of tickers)
Returns: subscribed tickers by vendor and database
Return type: dict

quantrocket.realtime.cancel_market_data(codes=None, sids=None, universes=None, cancel_all=False)¶

Cancel market data collection.

Parameters

codes (list of str, optional) – the tick database code(s) to cancel collection for
sids (list of str, optional) – cancel market data for these sids, overriding db config
universes (list of str, optional) – cancel market data for these universes, overriding db config
cancel_all (bool) – cancel all market data collection

Returns

subscribed tickers by vendor and database, after cancellation

Return type

dict

Examples

Cancel market data collection for a tick database called ‘globex-fut-taq’:

>>> cancel_market_data("globex-fut-taq")

Cancel all market data collection:

>>> cancel_market_data(cancel_all=True)

quantrocket.realtime.download_market_data_file(code, filepath_or_buffer=None, output='csv', start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, fields=None)¶

Query market data from a tick database or aggregate database and download to file.

Parameters

code (str, required) – the code of the tick database or aggregate database to query
filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
output (str) – output format (json, csv, default is csv)
start_date (str (YYYY-MM-DD HH:MM:SS), optional) – limit to market data on or after this datetime. Can pass a date (YYYY-MM-DD), datetime with optional timezone (YYYY-MM-DD HH:MM:SS TZ), or time with optional timezone. A time without date will be interpreted as referring to today if the time is earlier than now, or yesterday if the time is later than now.
end_date (str (YYYY-MM-DD HH:MM:SS), optional) – limit to market data on or before this datetime. Can pass a date (YYYY-MM-DD), datetime with optional timezone (YYYY-MM-DD HH:MM:SS TZ), or time with optional timezone.
universes (list of str, optional) – limit to these universes (default is to return all securities in database)
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
fields (list of str, optional) – only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

Download a CSV of futures market data since 08:00 AM Chicago time:

>>> download_market_data_file("globex-fut-taq",
                             start_date="08:00:00 America/Chicago",
                             filepath_or_buffer="globex_taq.csv")
>>> market_data = pd.read_csv("globex_taq.csv", parse_dates=["Date"])

See also

quantrocket.get_prices(): load prices into a DataFrame

Real-Time Data API

Resource Group ¶

Tick Database ¶

Create Tick Database
PUT`/realtime/databases/{code}{?universes,sids,vendor,fields,primary_exchange}`

Create a new database for collecting real-time tick data.

The market data requirements you specify when you create a new database are applied each time you collect data for that database.

Example URI

PUT http://houston/realtime/databases/globex-fut-taq?universes=globex-fut&sids=FI12345&vendor=ibkr&fields=Last&primary_exchange=true

URI Parameters

code

str (required) Example: globex-fut-taq

the code to assign to the database (lowercase alphanumerics and hyphens only)

universes

str (optional) Example: globex-fut

include these universes (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

include these sids (pass multiple times for multiple sids)

vendor

str (optional) Example: ibkr

the vendor to collect data from

Choices: ibkr polygon

fields

str (optional) Example: Last

collect these fields (pass multiple times for multiple fields) (pass ‘?’ or any invalid fieldname to see available fields, default fields are ‘Last’ and ‘Volume’)

primary_exchange

bool (required) Example: true

limit to data from the primary exchange (default False)

Response 200

Headers

Content-Type: application/json

Body

{
  "status": "status: successfully created tick database globex-fut-taq"
}

Get Tick Database Config
GET`/realtime/databases/{code}`

Return the configuration for a tick database.

Example URI

GET http://houston/realtime/databases/globex-fut-taq

URI Parameters

code: str (required) Example: globex-fut-taq
the tick database code

Response 200

Headers

Content-Type: application/json

Body

{
  "universes": [
    "globex-fut"
  ],
  "vendor": "ibkr",
  "fields": [
    "Last",
    "Volume",
    "Bid",
    "Ask",
    "BidSize",
    "AskSize"
  ]
}

Delete Tick Database
DELETE`/realtime/databases/{code}{?confirm_by_typing_db_code_again,cascade}`

Delete a tick database.

Deleting a tick database deletes its configuration and data and any associated aggregate databases.

Example URI

DELETE http://houston/realtime/databases/globex-fut-taq?confirm_by_typing_db_code_again=globex-fut-taq&cascade=true

URI Parameters

code: str (required) Example: globex-fut-taq
the tick database code
confirm_by_typing_db_code_again: str (required) Example: globex-fut-taq
enter the db code again to confirm you want to drop the database, its config, and all its data
cascade: bool (required) Example: true
also delete associated aggregated databases, if any.

Response 200

Headers

Content-Type: application/json

Body

{
  "status": "deleted tick database globex-fut-taq"
}

Ticks ¶

Delete Ticks
DELETE`/realtime/ticks/{code}{?older_than,cascade}`

Delete ticks from a tick database.

Note: when using cascade=True to also delete records from aggregate databases, the only aggregate records that will be deleted are ones corresponding to the ticks being deleted at the same time. This can have unintuitive consequences if you sometimes use cascade=True and sometimes don’t. For example, if you delete ticks older than 1 hour without cascade, then repeat the function with cascade=True, no aggregate records will be deleted. This is because the tick records older than 1 hour were already deleted previously and thus there can be no cascading delete of aggregate records on the subsequent call.

Example URI

DELETE http://houston/realtime/ticks/globex-fut-taq?older_than=7d&cascade=true

URI Parameters

code: str (required) Example: globex-fut-taq
the tick database code
older_than: str (required) Example: 7d
delete ticks older than this (use a Pandas timedelta string, for example 7d)
cascade: bool (required) Example: true
also delete records that are older than older_than from this tick database’s aggregate database(s), if any. By default, does not delete any aggregate database records.

Response 200

Headers

Content-Type: application/json

Body

{
  "status": "dropped ticks older than 7d from database globex-fut-taq"
}

Aggregate Database ¶

Create Aggregate Database
PUT`/realtime/databases/{tick_db_code}/aggregates/{code}{?bar_size,fields}`

Create an aggregate database from a tick database.

Aggregate databases provide rolled-up views of the underlying tick data, aggregated to a desired frequency (such as 1-minute bars).

Example URI

PUT http://houston/realtime/databases/globex-fut-taq/aggregates/globex-fut-taq-1s?bar_size=1s&fields=Last:Close,Open

URI Parameters

code: str (required) Example: globex-fut-taq-1s
the code to assign to the aggregate database (lowercase alphanumerics and hyphens only)
tick_db_code: str (required) Example: globex-fut-taq
the code of the tick database to aggregate
bar_size: str (required) Example: 1s
the time frequency to aggregate to (use a Pandas timedelta string, for example 10s or 1m or 2h or 1d)
fields: str (optional) Example: Last:Close,Open
include these fields in aggregate database, aggregated in these ways. Specify as a list of strings mapping tick db fields to a comma-separated list of aggregate functions to apply to the field. Format strings as ‘FIELD:FUNC1,FUNC2’. Available aggregate functions are ‘Close’, ‘Open’, ‘High’, ‘Low’, ‘Mean’, ‘Sum’, and ‘Count’. If not specified, defaults to including the ‘Close’ for each tick db field (pass multiple times for multiple fields)

Response 200

Headers

Content-Type: application/json

Body

{
  "status": "successfully created aggregate database globex-fut-taq-1sec from tick database globex-fut-taq"
}

Get Aggregate Database Config
GET`/realtime/databases/{tick_db_code}/aggregates/{code}`

Return the configuration for an aggregate database.

Example URI

GET http://houston/realtime/databases/globex-fut-taq/aggregates/globex-fut-taq-1s

URI Parameters

code: str (required) Example: globex-fut-taq-1s
the aggregate database code
tick_db_code: str (required) Example: globex-fut-taq
the tick database code

Response 200

Headers

Content-Type: application/json

Body

{
  "tick_db_code": "globex-fut-taq",
  "bar_size": "1s",
  "fields": [
    "AskClose",
    "AskSizeMean",
    "BidClose",
    "BidSizeMean"
  ]
}

Delete Aggregate Database
DELETE`/realtime/databases/{tick_db_code}/aggregates/{code}{?confirm_by_typing_db_code_again}`

Delete an aggregate database.

Deleting an aggregate database does not delete the tick database from which it is derived.

Example URI

DELETE http://houston/realtime/databases/globex-fut-taq/aggregates/globex-fut-taq-1s?confirm_by_typing_db_code_again=globex-fut-taq-1s

URI Parameters

code: str (required) Example: globex-fut-taq-1s
the aggregate database code
tick_db_code: str (required) Example: globex-fut-taq
the tick database code
confirm_by_typing_db_code_again: str (required) Example: globex-fut-taq-1s
enter the aggregate db code again to confirm you want to drop the database, its config, and all its data

Response 200

Headers

Content-Type: application/json

Body

{
  "status": "deleted aggregate database globex-fut-taq-1sec"
}

Databases ¶

List Real-Time Databases
GET`/realtime/databases`

List tick databases and associated aggregate databases.

Example URI

GET http://houston/realtime/databases

Response 200

Headers

Content-Type: application/json

Body

{
  "globex-fut-taq": [
    "globex-fut-taq-1s"
  ],
  "usa-liquid-taq": [
    "usa-liquid-taq-1h"
  ]
}

Market Data Collection ¶

Collect Market Data
POST`/realtime/collections{?codes,sids,universes,fields,until,snapshot,wait}`

Collect real-time market data and save it to a tick database.

A single snapshot of market data or a continuous stream of market data can be collected, depending on the snapshot parameter. (Snapshots are not supported for all vendors.)

Streaming real-time data is collected until cancelled, or can be scheduled for cancellation using the until parameter.

Example URI

POST http://houston/realtime/collections?codes=globex-fut-taq&sids=FI12345&universes=globex-fut&fields=Last&until=30m&snapshot=false&wait=false

URI Parameters

codes: str (required) Example: globex-fut-taq
the tick database code(s) to collect data for (pass multiple times for multiple codes)
sids: str (optional) Example: FI12345
collect market data for these sids, overriding db config (typically used to collect a subset of securities) (pass multiple times for multiple sids)
universes: str (optional) Example: globex-fut
collect market data for these universes, overriding config (typically used to collect a subset of securities) (pass multiple times for multiple universes)
fields: str (optional) Example: Last
limit to these fields, overriding db config (pass multiple times for multiple fields)
until: str (optional) Example: 30m
schedule data collection to end at this time. Can be a datetime (YYYY-MM-DD HH:MM:SS), a time (HH:MM:SS), or a Pandas timedelta string (e.g. 2h or 30min). If not provided, market data is collected until cancelled.
snapshot: bool (required) Example: false
collect a snapshot of market data (default is to collect a continuous stream of market data)
wait: bool (required) Example: false
wait for market data snapshot to complete before returning (default is to return immediately). Requires ‘snapshot=true’

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the market data will be collected asynchronously"
}

Get Active Market Data Collections
GET`/realtime/collections{?detail}`

Return the number of tickers currently being collected, by vendor and database.

Example URI

GET http://houston/realtime/collections?detail=false

URI Parameters

detail: bool (required) Example: false
return lists of tickers (default is to return counts of tickers)

Response 200

Headers

Content-Type: application/json

Body

{
  "ibkr": {
    "globex-fut-taq": 17
  },
  "polygon": {
    "us-stk-tick": 53
  }
}

Cancel Market Data Collection
DELETE`/realtime/collections{?codes,sids,universes,cancel_all}`

Cancel market data collection.

Example URI

DELETE http://houston/realtime/collections?codes=globex-fut-taq&sids=FI12345&universes=globex-fut&cancel_all=true

URI Parameters

codes: str (required) Example: globex-fut-taq
the tick database code(s) to cancel collection for (pass multiple times for multiple codes)
sids: str (optional) Example: FI12345
cancel market data for these sids, overriding db config (pass multiple times for multiple sids)
universes: str (optional) Example: globex-fut
cancel market data for these universes, overriding config (pass multiple times for multiple universes)
cancel_all: bool (required) Example: true
cancel all market data collection

Response 200

Headers

Content-Type: application/json

Body

{}

Market Data ¶

Query Market Data
GET`/realtime/{code}.{filetype}{?start_date,end_date,universes,sids,exclude_universes,exclude_sids,fields}`

Query market data from a tick database or aggregate database and download to file.

Example URI

GET http://houston/realtime/globex-fut-taq.csv?start_date=2016-06-01&end_date=2017-06-01&universes=es-fut&sids=FI12345&exclude_universes=other-universe&exclude_sids=FI23456&fields=LastPriceClose

URI Parameters

code

str (required) Example: globex-fut-taq

the code of the tick database or aggregate database to query

filetype

str (required) Example: csv

output format

Choices: csv json

start_date

str (optional) Example: 2016-06-01

limit to market data on or after this datetime. Can pass a date (YYYY-MM-DD), datetime with optional timezone (YYYY-MM-DD HH:MM:SS TZ), or time with optional timezone. A time without date will be interpreted as referring to today if the time is earlier than now, or yesterday if the time is later than now.

end_date

str (optional) Example: 2017-06-01

limit to market data on or before this datetime. Can pass a date (YYYY-MM-DD), datetime with optional timezone (YYYY-MM-DD HH:MM:SS TZ), or time with optional timezone.

universes

str (optional) Example: es-fut

limit to these universes (default is to return all securities in database) (pass multiple times for multiple universes)

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

fields

str (optional) Example: LastPriceClose

only return these fields (pass ‘?’ or any invalid fieldname to see available fields) (pass multiple times for multiple fields)

Response 200

Headers

Content-Type: text/csv

Body

Sid,Date,Last
FI756733,2019-05-28 19:23:16.850314+00,281.34
FI756733,2019-05-28 19:23:17.188008+00,281.38
FI756733,2019-05-28 19:23:17.939423+00,281.37
FI756733,2019-05-28 19:23:19.195198+00,281.39
FI756733,2019-05-28 19:23:20.695623+00,281.41

Streaming Market Data ¶

Stream Market Data
GET`/realtime/stream{?sids,exclude_sids,fields}`

Stream real-time data over WebSockets.

Example URI

GET http://houston/realtime/stream?sids=FI12345&exclude_sids=FI23456&fields=BidSize

URI Parameters

sids: str (optional) Example: FI12345
limit to these sids (pass multiple times for multiple sids)
exclude_sids: str (optional) Example: FI23456
exclude these sids (pass multiple times for multiple sids)
fields: str (optional) Example: BidSize
limit to these fields (pass multiple times for multiple fields)

quantrocket.satellite

satellite service

QuantRocket Satellite CLI

usage: quantrocket satellite [-h] {exec} ...

subcommands¶

subcommand: Possible choices: exec

Sub-commands:¶

exec¶

execute a Python function or abitrary shell command on a satellite service

quantrocket satellite exec [-h] [-r FILEPATH] [-o FILEPATH]
                           [-p [PARAM:VALUE [PARAM:VALUE ...]]]
                           [-s SERVICE_NAME]
                           CMD

Positional Arguments¶

CMD: the shell command to run, or the Python function in dot notation (must start with ‘codeload.’ to be interpreted as a Python function)

Named Arguments¶

-r, --return-file

the path of a file to be returned after the command completes

-o, --outfile

the location to write the return_file (omit to write to stdout)

-p, --params

one or more params to pass to the Python function (pass as {param:value})

-s, --service

the service name (default ‘satellite’)

Default: “satellite”

Execute a Python function or abitrary shell command on a satellite service.

Examples:

Run a Python function called ‘create_calendar_spread’ defined in ‘/codeload/scripts/combos.py’ and pass it arguments:

quantrocket satellite exec ‘codeload.scripts.combos.create_calendar_spread’ –params ‘universe:cl-fut’ ‘contract_months:[1,2]’

Run a backtrader backtest and save the performance chart to file:

quantrocket satellite exec ‘python /codeload/backtrader/dual_moving_average.py’ –return-file ‘/tmp/backtrader-plot.pdf’ –outfile ‘backtrader-plot.pdf’

quantrocket.satellite.execute_command(cmd, return_file=None, filepath_or_buffer=None, params=None, service='satellite')¶

Execute a Python function or abitrary shell command on a satellite service.

Parameters

cmd (str, required) – the shell command to run, or the Python function in dot notation (must start with “codeload.” to be interpreted as a Python function).
return_file (str, optional) – the path of a file to be returned after the command completes
filepath_or_buffer (str, optional) – the location to write the return_file (omit to write to stdout)
params (dict of PARAM:VALUE, optional) – one or more params to pass to the Python function (pass as {param:value})
service (str, optional) – the service name (default ‘satellite’)

Returns

None if return_file, otherwise status message

Return type

dict or None

Examples

Run a Python function called ‘create_calendar_spread’ defined in ‘/codeload/scripts/combos.py’ and pass it arguments:

>>> execute_command("codeload.scripts.combos.create_calendar_spread",
                    params={"universe":"cl-fut", "contract_months":[1,2]})

Run a backtrader backtest and save the performance chart to file:

>>> execute_command("python /codeload/backtrader/dual_moving_average.py",
                    return_file="/tmp/backtrader-plot.pdf"
                    outfile="backtrader-plot.pdf")

Satellite API

Resource Group ¶

Commands ¶

Execute Command
POST`/{service}/commands{?cmd,return_file,params}`

Execute a Python function or abitrary shell command on a satellite service.

Example URI

POST http://houston/satellite/commands?cmd=python%20%2Fcodeload%2Fbacktrader%2Fdual_moving_average.py&return_file=%2Ftmp%2Fbacktrader-plot.pdf&params=myarg:myval

URI Parameters

service: str (required) Example: satellite
the service name
cmd: str (required) Example: python%20%2Fcodeload%2Fbacktrader%2Fdual_moving_average.py
the shell command to run, or the Python function in dot notation (must start with “codeload.” to be interpreted as a Python function).
return_file: str (optional) Example: %2Ftmp%2Fbacktrader-plot.pdf
the path of a file to be returned after the command completes
params: str (optional) Example: myarg:myval
one or more params to pass to the Python function (pass as param:value)

Response 200

Headers

Content-Type: application/octet-stream

quantrocket.utils

Utility functions

Utils¶

quantrocket.utils.segmented_date_range(start_date, end_date, segment='A')¶

Split a date range into smaller segments.

Parameters

start_date (str (YYYY-MM-DD), required) – start date, inclusive
end_date (str (YYYY-MM-DD), required) – end date, inclusive
segment (str, required) – split date range into segments of this size (use Pandas frequency string, e.g. ‘A’ for annual segments or ‘Q’ for quarterly segments; default ‘A’)

Returns

list of tuples of (start_date, end_date)

Return type

list

Examples

>>> segmented_date_range("2013-06-01", "2015-12-15")
[('2013-06-01', '2013-12-30'),
('2013-12-31', '2014-12-30'),
('2014-12-31', '2015-12-15')]

quantrocket.zipline

This API is for backtesting and live trading of Zipline strategies, as well as managing data bundles. For writing Zipline strategies, see the zipline API.

QuantRocket CLI for Zipline

usage: quantrocket zipline [-h]
                           {create-usstock-bundle,create-bundle-from-db,ingest,list-bundles,config,drop-bundle,default-bundle,get,backtest,tearsheet,trade,active,cancel}
                           ...

subcommands¶

subcommand: Possible choices: create-usstock-bundle, create-bundle-from-db, ingest, list-bundles, config, drop-bundle, default-bundle, get, backtest, tearsheet, trade, active, cancel

Sub-commands:¶

create-usstock-bundle¶

create a Zipline bundle for US stocks

quantrocket zipline create-usstock-bundle [-h] [-i SID] [-u UNIVERSE] [--free]
                                          CODE

Positional Arguments¶

CODE: the code to assign to the bundle (lowercase alphanumerics and hyphens only)

Named Arguments¶

-i, --sids

limit to these sids

-u, --universes

limit to these universes

--free

limit to free sample data

Default: False

Create a Zipline bundle for US stocks.

This command defines the bundle parameters but does not ingest the actual data. To ingest the data, see quantrocket zipline ingest.

Examples:

Create a bundle for all US stocks:

quantrocket zipline create-usstock-bundle usstock-1min

Create a bundle based on a universe:

quantrocket zipline create-usstock-bundle usstock-tech-1min –universes us-tech

Create a bundle of free sample data:

quantrocket zipline create-usstock-bundle usstock-free-1min –free

create-bundle-from-db¶

create a Zipline bundle from a history database or real-time aggregate database

quantrocket zipline create-bundle-from-db [-h] [-d CODE] [-c NAME]
                                          [-f [ZIPLINE_FIELD:DB_FIELD [ZIPLINE_FIELD:DB_FIELD ...]]]
                                          -s YYYY-MM-DD [-e YYYY-MM-DD]
                                          [-u [UNIVERSE [UNIVERSE ...]]]
                                          [-i [SID [SID ...]]]
                                          [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                                          [--exclude-sids [SID [SID ...]]]
                                          CODE

Positional Arguments¶

CODE: the code to assign to the bundle (lowercase alphanumerics and hyphens only)

Named Arguments¶

-d, --from-db: the code of a history database or real-time aggregate database to ingest
-c, --calendar: the name of the calendar to use with this bundle (provide ‘?’ or any invalid calendar name to see available choices)
-f, --fields: mapping of Zipline fields (open, high, low, close, volume) to db fields. Pass as ‘zipline_field:db_field’. Defaults to mapping Zipline ‘open’ to db ‘Open’, etc.

filtering options for db ingestion¶

-s, --start-date: limit to historical data on or after this date. This parameter is required and also determines the default start date for backtests and queries.
-e, --end-date: limit to historical data on or before this date
-u, --universes: limit to these universes
-i, --sids: limit to these sids
--exclude-universes: exclude these universes
--exclude-sids: exclude these sids

Create a Zipline bundle from a history database or real-time aggregate database.

You can ingest 1-minute or 1-day databases.

This command defines the bundle parameters but does not ingest the actual data. To ingest the data, see quantrocket zipline ingest.

Examples:

Create a bundle from a history database called “es-fut-1min” and name it like the history database:

quantrocket zipline create-bundle-from-db es-fut-1min –from-db es-fut-1min –calendar us_futures –start-date 2015-01-01

Create a bundle named “usa-stk-1min-2017” for ingesting a single year of US 1-minute stock data from a history database called “usa-stk-1min”:

quantrocket zipline create-bundle-from-db usa-stk-1min-2017 –from-db usa-stk-1min -s 2017-01-01 -e 2017-12-31 –calendar XNYS

Create a bundle from a real-time aggregate database and specify how to map Zipline fields to the database fields:

quantrocket zipline create-bundle-from-db free-stk-1min –from-db free-stk-tick-1min –calendar XNYS –start-date 2020-06-01 –fields close:LastPriceClose open:LastPriceOpen high:LastPriceHigh low:LastPriceLow volume:VolumeClose

ingest¶

ingest data into a previously defined bundle

quantrocket zipline ingest [-h] [-i [SID [SID ...]]]
                           [-u [UNIVERSE [UNIVERSE ...]]]
                           CODE

Positional Arguments¶

CODE: the bundle code

Named Arguments¶

-i, --sids: limit to these sids, overriding stored config
-u, --universes: limit to these universes, overriding stored config

Ingest data into a previously defined bundle.

Examples:

Ingest data into a bundle called usstock-1min:

quantrocket zipline ingest usstock-1min

list-bundles¶

list available data bundles and whether data has been ingested into them

quantrocket zipline list-bundles [-h]

List available data bundles and whether data has been ingested into them.

Examples:

quantrocket zipline list-bundles

config¶

return the configuration of a bundle

quantrocket zipline config [-h] CODE

Positional Arguments¶

CODE: the bundle code

Return the configuration of a bundle.

Examples:

Return the configuration of a bundle called ‘usstock-1min’:

quantrocket zipline config usstock-1min

drop-bundle¶

delete a bundle

quantrocket zipline drop-bundle [-h] --confirm-by-typing-bundle-code-again
                                CODE
                                CODE

Positional Arguments¶

CODE: the bundle code

Named Arguments¶

--confirm-by-typing-bundle-code-again: enter the bundle code again to confirm you want to drop the bundle, its config, and all its data

Delete a bundle.

Examples:

Delete a bundle called ‘es-fut-1min’:

quantrocket zipline drop-bundle es-fut-1min –confirm-by-typing-bundle-code-again es-fut-1min

default-bundle¶

set or show the default bundle to use for backtesting and trading

quantrocket zipline default-bundle [-h] [bundle]

Positional Arguments¶

bundle: the bundle code

Set or show the default bundle to use for backtesting and trading.

Setting a default bundle is a convenience and is optional. It can be overridden by manually specifying a bundle when backtesting or trading.

Examples:

Set a bundle named usstock-1min as the default:

quantrocket zipline default-bundle usstock-1min

Show current default bundle:

quantrocket zipline default-bundle

get¶

query minute data from a Zipline bundle and download to a CSV file

quantrocket zipline get [-h] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                        [-u [UNIVERSE [UNIVERSE ...]]] [-i [SID [SID ...]]]
                        [--exclude-universes [UNIVERSE [UNIVERSE ...]]]
                        [--exclude-sids [SID [SID ...]]]
                        [-t [HH:MM:SS [HH:MM:SS ...]]] [-o OUTFILE]
                        [-f [FIELD [FIELD ...]]]
                        CODE

Positional Arguments¶

CODE: the bundle code

filtering options¶

-s, --start-date: limit to history on or after this date
-e, --end-date: limit to history on or before this date
-u, --universes: limit to these universes
-i, --sids: limit to these sids
--exclude-universes: exclude these universes
--exclude-sids: exclude these sids
-t, --times: limit to these times

output options¶

-o, --outfile: filename to write the data to (default is stdout)
-f, --fields: only return these fields (pass ‘?’ or any invalid fieldname to see available fields)

Query minute data from a Zipline bundle and download to a CSV file.

Examples:

Download a CSV of minute prices since 2015 for a single security from a bundle called “usstock-1min”:

quantrocket zipline get usstock-1min –start-date 2015-01-01 -i FIBBG12345 -o minute_prices.csv

backtest¶

backtest a Zipline strategy and write the test results to a CSV file

quantrocket zipline backtest [-h] [-f {daily,minute}] [--capital-base FLOAT]
                             [-b CODE] [-s YYYY-MM-DD] [-e YYYY-MM-DD]
                             [-p FREQ] [-o FILENAME]
                             CODE

Positional Arguments¶

CODE: the strategy to run (strategy filename without extension)

Named Arguments¶

-f, --data-frequency

Possible choices: daily, minute

the data frequency to use. Possible choices: [‘daily’, ‘minute’] (default is minute)

--capital-base

the starting capital for the simulation (default is 1e6 (1 million))

-b, --bundle

the data bundle to use for the simulation. If omitted, the default bundle (if set) is used.

-s, --start-date

the start date of the simulation (defaults to the bundle start date)

-e, --end-date

the end date of the simulation (defaults to today)

-p, --progress

log backtest progress at this interval (use a pandas offset alias, for example ‘D’ for daily, ‘W’ for weeky, ‘M’ for monthly, ‘A’ for annually)

-o, --output

the location to write the output file (omit to write to stdout)

Backtest a Zipline strategy and write the test results to a CSV file.

The CSV result file contains several DataFrames stacked into one: the Zipline performance results, plus the extracted returns, transactions, positions, and benchmark returns from those results.

Examples:

Run a backtest from a strategy file called etf-arb.py and save a CSV file of results, logging backtest progress at annual intervals:

quantrocket zipline backtest etf-arb –bundle arca-etf-eod -s 2010-04-01 -e 2016-02-01 -o results.csv –progress A

tearsheet¶

create a pyfolio tear sheet from a Zipline backtest result

quantrocket zipline tearsheet [-h] -o FILENAME [FILENAME]

Positional Arguments¶

FILENAME

the CSV file from a Zipline backtest (omit to read file from stdin)

Default: “-“

Named Arguments¶

-o, --output: the location to write the pyfolio tear sheet

Create a pyfolio PDF tear sheet from a Zipline backtest result.

Examples:

Create a pyfolio tear sheet from a Zipline CSV results file:

quantrocket zipline tearsheet results.csv -o results.pdf

Run a Zipline backtest and create a pyfolio tear sheet without saving the CSV file:

quantrocket zipline backtest dma -s 2010-04-01 -e 2016-02-01 | quantrocket zipline tearsheet -o dma.pdf

trade¶

trade a Zipline strategy

quantrocket zipline trade [-h] [-b CODE] [-a ACCOUNT] [-f {daily,minute}] CODE

Positional Arguments¶

CODE: the strategy to run (strategy filename without extension)

Named Arguments¶

-b, --bundle

the data bundle to use. If omitted, the default bundle (if set) is used.

-a, --account

the account to run the strategy in. Only required if the strategy is allocated to more than one account in quantrocket.zipline.allocations.yml

-f, --data-frequency

Possible choices: daily, minute

the data frequency to use. Possible choices: [‘daily’, ‘minute’] (default is minute)

Trade a Zipline strategy.

Examples:

Trade a strategy defined in momentum-pipeline.py:

quantrocket zipline trade momentum-pipeline –bundle my-bundle

active¶

list actively trading Zipline strategies

quantrocket zipline active [-h]

List actively trading Zipline strategies.

Examples:

List strategies:

quantrocket zipline active

cancel¶

cancel actively trading strategies

quantrocket zipline cancel [-h] [-s [CODE [CODE ...]]]
                           [-a [ACCOUNT [ACCOUNT ...]]] [--all]

Named Arguments¶

-s, --strategies

limit to these strategies

-a, --accounts

limit to these accounts

--all

cancel all actively trading strategies

Default: False

Cancel actively trading strategies.

Examples:

Cancel a single strategy:

quantrocket zipline cancel –strategies momentum-pipeline

Cancel all strategies:

quantrocket zipline cancel –all

quantrocket.zipline.create_usstock_bundle(code, sids=None, universes=None, free=False)¶

Create a Zipline bundle for US stocks.

This function defines the bundle parameters but does not ingest the actual data. To ingest the data, see ingest_bundle.

Parameters

code (str, required) – the code to assign to the bundle (lowercase alphanumerics and hyphens only)
sids (list of str, optional) – limit to these sids
universes (list of str, optional) – limit to these universes
free (bool) – limit to free sample data

Returns

status message

Return type

dict

Examples

Create a bundle for all US stocks:

>>> create_usstock_bundle("usstock-1min")

Create a bundle based on a universe:

>>> create_usstock_bundle("usstock-tech-1min", universes="us-tech")

Create a bundle of free sample data:

>>> create_usstock_bundle("usstock-free-1min", free=True)

quantrocket.zipline.create_bundle_from_db(code, from_db, calendar, start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, fields=None)¶

Create a Zipline bundle from a history database or real-time aggregate database.

You can ingest 1-minute or 1-day databases.

This function defines the bundle parameters but does not ingest the actual data. To ingest the data, see ingest_bundle.

Parameters

code (str, required) – the code to assign to the bundle (lowercase alphanumerics and hyphens only)
from_db (str, required) – the code of a history database or real-time aggregate database to ingest
calendar (str, required) – the name of the calendar to use with this bundle (provide ‘?’ or any invalid calendar name to see available choices)
start_date (str (YYYY-MM-DD), required) – limit to historical data on or after this date. This parameter is required and also determines the default start date for backtests and queries.
end_date (str (YYYY-MM-DD), optional) – limit to historical data on or before this date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
fields (dict, optional) – mapping of Zipline fields (open, high, low, close, volume) to db fields. Defaults to mapping Zipline ‘open’ to db ‘Open’, etc.

Returns

status message

Return type

dict

Examples

Create a bundle from a history database called “es-fut-1min” and name it like the history database:

>>> create_bundle_from_db("es-fut-1min", from_db="es-fut-1min", calendar="us_futures")

Create a bundle named “usa-stk-1min-2017” for ingesting a single year of US 1-minute stock data from a history database called “usa-stk-1min”:

>>> create_bundle_from_db("usa-stk-1min-2017", from_db="usa-stk-1min",
>>>                      calendar="XNYS",
>>>                      start_date="2017-01-01", end_date="2017-12-31")

Create a bundle from a real-time aggregate database and specify how to map Zipline fields to the database fields:

>>> create_bundle_from_db("free-stk-1min", from_db="free-stk-tick-1min",
>>>                       calendar="XNYS", start_date="2020-06-01",
>>>                       fields={
>>>                           "close": "LastPriceClose",
>>>                           "open": "LastPriceOpen",
>>>                           "high": "LastPriceHigh",
>>>                           "low": "LastPriceLow",
>>>                           "volume": "VolumeClose"})

quantrocket.zipline.ingest_bundle(code, sids=None, universes=None)¶

Ingest data into a previously defined bundle.

Parameters

code (str, required) – the bundle code
sids (list of str, optional) – limit to these sids, overriding stored config
universes (list of str, optional) – limit to these universes, overriding stored config

Returns

status message

Return type

dict

Examples

Ingest data into a bundle called usstock-1min:

>>> ingest_bundle("usstock-1min")

quantrocket.zipline.list_bundles()¶

List available data bundles and whether data has been ingested into them.

Returns: data bundles and whether they have data (True indicates data, False indicates config only)
Return type: dict

quantrocket.zipline.get_bundle_config(code)¶

Return the configuration of a bundle.

Parameters: code (str, required) – the bundle code
Returns: config
Return type: dict

quantrocket.zipline.drop_bundle(code, confirm_by_typing_bundle_code_again=None)¶

Delete a bundle.

Parameters

code (str, required) – the bundle code
confirm_by_typing_bundle_code_again (str, required) – enter the bundle code again to confirm you want to drop the bundle, its config, and all its data

Returns

status message

Return type

dict

Examples

Delete a bundle called ‘es-fut-1min’:

>>> drop_bundle("es-fut-1min")

quantrocket.zipline.get_default_bundle()¶

Return the current default bundle, if any.

Returns: default bundle
Return type: dict

quantrocket.zipline.set_default_bundle(bundle)¶

Set the default bundle to use for backtesting and trading.

Setting a default bundle is a convenience and is optional. It can be overridden by manually specifying a bundle when backtesting or trading.

Parameters: bundle (str, required) – the bundle code
Returns: status message
Return type: dict

quantrocket.zipline.download_minute_file(code, filepath_or_buffer=None, start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, times=None, fields=None)¶

Query minute data from a Zipline bundle and download to a CSV file.

Parameters

code (str, required) – the bundle code
filepath_or_buffer (str or file-like object) – filepath to write the data to, or file-like object (defaults to stdout)
start_date (str (YYYY-MM-DD), optional) – limit to history on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to history on or before this date
universes (list of str, optional) – limit to these universes
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
times (list of str (HH:MM:SS), optional) – limit to these times
fields (list of str, optional) – only return these fields (pass [‘?’] or any invalid fieldname to see available fields)

Returns

Return type

None

Examples

Load minute prices into pandas:

>>> download_minute_file("usstock-1min", sids=["FIBBG12345"])
>>> prices = pd.read_csv(f, parse_dates=["Date"], index_col=["Field","Date"])

Isolate fields with .loc:

>>> closes = prices.loc["Close"]

See also

quantrocket.get_prices(): load prices into a DataFrame

quantrocket.zipline.backtest(strategy, data_frequency=None, capital_base=None, bundle=None, start_date=None, end_date=None, progress=None, filepath_or_buffer=None)¶

Backtest a Zipline strategy and write the test results to a CSV file.

The CSV result file contains several DataFrames stacked into one: the Zipline performance results, plus the extracted returns, transactions, positions, and benchmark returns from those results.

Parameters

strategy (str, required) – the strategy to run (strategy filename without extension)
data_frequency (str, optional) – the data frequency of the simulation. Possible choices: daily, minute (default is minute)
capital_base (float, optional) – the starting capital for the simulation (default is 1e6 (1 million))
bundle (str, optional) – the data bundle to use for the simulation. If omitted, the default bundle (if set) is used.
start_date (str (YYYY-MM-DD), optional) – the start date of the simulation (defaults to the bundle start date)
end_date (str (YYYY-MM-DD), optional) – the end date of the simulation (defaults to today)
progress (str, optional) – log backtest progress at this interval (use a pandas offset alias, for example “D” for daily, “W” for weeky, “M” for monthly, “A” for annually)
filepath_or_buffer (str, optional) – the location to write the output file (omit to write to stdout)

Returns

Return type

None

Examples

Run a backtest defined in momentum-pipeline.py and save to CSV, logging backtest progress at weekly intervals.

>>> backtest("momentum-pipeline", bundle="my-bundle",
             start_date="2015-02-04", end_date="2015-12-31",
             progress="W",
             filepath_or_buffer="momentum_pipeline_results.csv")

Get a pyfolio tear sheet from the results:

>>> import pyfolio as pf
>>> pf.from_zipline_csv("momentum_pipeline_results.csv")

quantrocket.zipline.create_tearsheet(infilepath_or_buffer, outfilepath_or_buffer=None)¶

Create a pyfolio PDF tear sheet from a Zipline backtest result.

Parameters

infilepath_or_buffer (str, required) – the CSV file from a Zipline backtest (specify ‘-‘ to read file from stdin)
outfilepath_or_buffer (str or file-like, optional) – the location to write the pyfolio tear sheet (write to stdout if omitted)

Returns

Return type

None

quantrocket.zipline.trade(strategy, bundle=None, account=None, data_frequency=None)¶

Trade a Zipline strategy.

Parameters

strategy (str, required) – the strategy to run (strategy filename without extension)
bundle (str, optional) – the data bundle to use. If omitted, the default bundle (if set) is used.
account (str, optional) – the account to run the strategy in. Only required if the strategy is allocated to more than one account in quantrocket.zipline.allocations.yml.
data_frequency (str, optional) – the data frequency to use. Possible choices: daily, minute (default is minute)

Returns

Return type

None

Examples

Trade a strategy defined in momentum-pipeline.py:

>>> trade("momentum-pipeline", bundle="my-bundle")

quantrocket.zipline.list_active_strategies()¶

List actively trading Zipline strategies.

Returns: dict of account: strategies
Return type: dict

quantrocket.zipline.cancel_strategies(strategies=None, accounts=None, cancel_all=False)¶

Cancel actively trading strategies.

Parameters

strategies (list of str, optional) – limit to these strategies
accounts (list of str, optional) – limit to these accounts
cancel_all (bool) – cancel all actively trading strategies

Returns

dict of actively trading strategies after canceling

Return type

dict

Examples

Cancel a single strategy:

>>> cancel_strategies(strategies="momentum-pipeline")

Cancel all strategies:

>>> cancel_strategies(cancel_all=True)

class quantrocket.zipline.ZiplineBacktestResult¶

Convenience class for parsing a CSV result file from a Zipline backtest into a variety of useful DataFrames, which can be passed to pyfolio or inspected by the user.

Examples

Run a Zipline backtest and parse the CSV results:

>>> f = io.StringIO()
>>> run_algorithm("momentum_pipeline.py",
          bundle="etf-sampler-1d",
          start="2015-02-04",
          end="2015-12-31",
          filepath_or_buffer=f)
>>> zipline_result = ZiplineBacktestResult.from_csv(f)

The ZiplineBacktestResult object contains returns, positions, transactions, benchmark_returns, and the performance DataFrame.

>>> print(zipline_result.returns.head())
>>> print(zipline_result.positions.head())
>>> print(zipline_result.transactions.head())
>>> print(zipline_result.benchmark_returns.head())
>>> print(zipline_result.perf.head())

The outputs are ready to be passed to pyfolio:

>>> pf.create_full_tear_sheet(
        zipline_result.returns,
        positions=zipline_result.positions,
        transactions=zipline_result.transactions,
        benchmark_rets=zipline_result.benchmark_returns)

Zipline API

Resource Group ¶

Bundles ¶

Create Bundle
PUT`/zipline/bundles/{code}{?ingest_type,sids,universes,exclude_sids,exclude_universes,free,start_date,end_date,from_db,calendar,fields}`

Create a Zipline bundle.

This endpoint defines the bundle parameters but does not ingest the actual data. To ingest the data, see the ingestion endpoint.

Not all parameters are applicable to all ingestion types. Please see the Python API reference to determine which parameters are applicable to which ingestion types.

Example URI

PUT http://houston/zipline/bundles/usstock-1min?ingest_type=usstock&sids=FI12345&universes=us-tech&exclude_sids=FI23456&exclude_universes=other-universe&free=false&start_date=2010-01-01&end_date=2019-01-01&from_db=globex-fut-1min&calendar=us_futures&fields=close:Close

URI Parameters

code

str (required) Example: usstock-1min

the code to assign to the bundle (lowercase alphanumerics and hyphens only)

ingest_type

str (required) Example: usstock

the type of ingestion

Choices: from_db usstock

from_db

str (optional) Example: globex-fut-1min

the code of a history database or real-time aggregate database to ingest

calendar

str (optional) Example: us_futures

the name of the calendar to use with this bundle

sids

str (optional) Example: FI12345

limit to these sids (pass multiple times for multiple sids)

universes

str (optional) Example: us-tech

limit to these universes (pass multiple times for multiple universes)

exclude_sids

str (optional) Example: FI23456

exclude these sids (pass multiple times for multiple sids)

exclude_universes

str (optional) Example: other-universe

exclude these universes (pass multiple times for multiple universes)

free

bool (optional) Example: false

limit to free sample data

start_date

str (required) Example: 2010-01-01

limit to historical data on or after this date. This parameter is required and also determines the default start date for backtests and queries.

end_date

str (optional) Example: 2019-01-01

limit to historical data on or before this date

fields

str (optional) Example: close:Close

mapping of Zipline fields (open, high, low, close, volume) to db fields. Defaults to mapping Zipline ‘open’ to db ‘Open’, etc.

Response 200

Headers

Content-Type: application/json

Body

{
  "status": "success",
  "msg": "successfully created usstock-1min bundle"
}

List Bundles
GET`/zipline/bundles/`

List available data bundles and whether data has been ingested into them.

Example URI

GET http://houston/zipline/bundles/

Response 200

Headers

Content-Type: application/json

Body

{
  "usstock-1min": true
}

Delete Bundle
DELETE`/zipline/bundles/{code}{?confirm_by_typing_bundle_code_again}`

Delete a bundle.

Example URI

DELETE http://houston/zipline/bundles/usstock-1min?confirm_by_typing_bundle_code_again=usstock-1min

URI Parameters

code: str (required) Example: usstock-1min
the bundle code
confirm_by_typing_bundle_code_again: str (required) Example: usstock-1min
enter the bundle code again to confirm you want to drop the bundle, its config, and all its data

Response 200

Headers

Content-Type: application/json

Body

{
  "status": "deleted usstock-1min bundle"
}

Bundle Config ¶

Get Bundle Config
GET`/zipline/bundles/config/{code}`

Return the configuration of a bundle.

Example URI

GET http://houston/zipline/bundles/config/usstock-1min

URI Parameters

code: str (required) Example: usstock-1min
the bundle code

Response 200

Headers

Content-Type: application/json

Body

{
  "ingest_type": "usstock",
  "sids": null,
  "universes": null,
  "free": false,
  "data_frequency": "minute",
  "calendar": "XNYS",
  "start_date": "2007-01-03"
}

Ingestions ¶

Ingest Bundle
POST`/zipline/ingestions/{code}{?sids,universes}`

Ingest data into a previously defined bundle.

Example URI

POST http://houston/zipline/ingestions/usstock-1min?sids=FI123456&universes=nyse-stk-pharma

URI Parameters

code: str (required) Example: usstock-1min
the bundle code
sids: str (optional) Example: FI123456
limit to these sids, overriding stored config (pass multiple times for multiple sids)
universes: str (optional) Example: nyse-stk-pharma
limit to these universes, overriding stored config (pass multiple times for multiple universes)

Response 200

Headers

Content-Type: application/json

Body

{
  "status": "the data will be ingested asynchronously"
}

Zipline Config ¶

Get Default Bundle
GET`/zipline/config`

Return the current default bundle, if any.

Example URI

GET http://houston/zipline/config

Response 200

Headers

Content-Type: application/json

Set Default Bundle
PUT`/zipline/config{?default_bundle}`

Set the default bundle to use for backtesting and trading.

Setting a default bundle is a convenience and is optional. It can be overridden by manually specifying a bundle when backtesting or trading.

Example URI

PUT http://houston/zipline/config?default_bundle=usstock-1min

URI Parameters

default_bundle: str (required) Example: usstock-1min
the bundle code

Response 200

Headers

Content-Type: application/json

Bundle Data ¶

Query Minute Data
GET`/zipline/bundles/data/{code}.csv{?start_date,end_date,sids,universes,exclude_sids,exclude_universes,times,fields}`

Query minute data from a Zipline bundle and download to a CSV file.

Example URI

GET http://houston/zipline/bundles/data/usstock-1min.csv?start_date=2016-06-01&end_date=2017-06-01&sids=FI12345&universes=japan-bank&exclude_sids=FI23456&exclude_universes=other-universe&times=09:30:00&fields=Close

URI Parameters

code: str (required) Example: usstock-1min
the bundle code
start_date: str (optional) Example: 2016-06-01
limit to history on or after this date
end_date: str (optional) Example: 2017-06-01
limit to history on or before this date
universes: str (optional) Example: japan-bank
limit to these universes (default is to return all securities in database) (pass multiple times for multiple universes)
sids: str (optional) Example: FI12345
limit to these sids (pass multiple times for multiple sids)
exclude_universes: str (optional) Example: other-universe
exclude these universes (pass multiple times for multiple universes)
exclude_sids: str (optional) Example: FI23456
exclude these sids (pass multiple times for multiple sids)
times: str (optional) Example: 09:30:00
limit to these times (pass multiple times for multiple times)
fields: str (optional) Example: Close
only return these fields

Response 200

Headers

Content-Type: text/csv

Body

Sid,Date,Close
FI1715006,2017-01-27T09:30:00,48.65
FI1715006,2017-01-30T09:30:00,47.67
FI1715006,2017-01-31T09:30:00,48.97
FI1715006,2017-02-01T09:30:00,49.26

Backtests ¶

Run Backtest
POST`/zipline/backtests/{strategy}{?data_frequency,capital_base,bundle,start_date,end_date}`

Run a Zipline backtest and write the test results to a CSV file.

The CSV result file contains several DataFrames stacked into one: the Zipline performance results, plus the extracted returns, transactions, positions, and benchmark returns from those results.

Example URI

POST http://houston/zipline/backtests/dual_moving_average.py?data_frequency=minute&capital_base=100000&bundle=usstock-1min&start_date=2010-01-01&end_date=2020-01-01

URI Parameters

strategy

str (required) Example: dual_moving_average.py

the file that contains the strategy to run

data_frequency

str (optional) Example: minute

the data frequency of the simulation

Choices: daily minute

capital_base

float (optional) Example: 100000

the starting capital for the simulation (default is 10000000.0)

bundle

str (optional) Example: usstock-1min

the data bundle to use for the simulation. If omitted, the default bundle (if set) is used.

start_date

str (required) Example: 2010-01-01

the start date of the simulation

end_date

str (required) Example: 2020-01-01

the end date of the simulation

Response 200

Headers

Content-Type: text/csv

Body

dataframe,index,date,column,value
benchmark,1,2010-01-05 00:00:00+00:00,benchmark,0.0016353229762877675
benchmark,2,2010-01-06 00:00:00+00:00,benchmark,-0.015836734693877474
transactions,754,2014-12-30 21:00:00+00:00,price,112.5200000000018
transactions,754,2014-12-30 21:00:00+00:00,sid,Equity(265598 [AAPL])
transactions,754,2014-12-30 21:00:00+00:00,symbol,Equity(265598 [AAPL])

Tear Sheets ¶

Create Tear Sheet
POST`/zipline/tearsheets`

Create a pyfolio PDF tear sheet from a Zipline backtest result.

Example URI

POST http://houston/zipline/tearsheets

Request

Headers

Content-Type: text/csv

Body

dataframe,index,date,column,value
benchmark,1,2010-01-05 00:00:00+00:00,benchmark,0.0016353229762877675
benchmark,2,2010-01-06 00:00:00+00:00,benchmark,-0.015836734693877474
transactions,754,2014-12-30 21:00:00+00:00,price,112.5200000000018
transactions,754,2014-12-30 21:00:00+00:00,sid,Equity(265598 [AAPL])
transactions,754,2014-12-30 21:00:00+00:00,symbol,Equity(265598 [AAPL])

Response 200

Headers

Content-Type: application/pdf

Trade ¶

Trade Strategy
POST`/zipline/trade/{strategy}{?bundle,account,data_frequency}`

Trade a Zipline strategy.

Example URI

POST http://houston/zipline/trade/dual_moving_average.py?bundle=usstock-1min&account=U12345&data_frequency=minute

URI Parameters

strategy

str (required) Example: dual_moving_average.py

the file that contains the strategy to run

bundle

str (optional) Example: usstock-1min

the data bundle to use. If omitted, the default bundle (if set) is used.

account

str (optional) Example: U12345

the account to run the strategy in. Only required if the strategy is allocated to more than one account in quantrocket.zipline.allocations.yml.

data_frequency

str (optional) Example: minute

the data frequency to use. Default is minute.

Choices: daily minute

Response 202

Headers

Content-Type: application/json

Body

{
  "status": "the strategy will be traded asynchronously"
}

List Strategies
GET`/zipline/trade/`

List actively trading Zipline strategies.

Example URI

GET http://houston/zipline/trade/

Response 200

Headers

Content-Type: application/json

Body

{
  "U12345": [
    "dual_moving_average.py"
  ]
}

Cancel Strategies
DELETE`/zipline/trade/{?strategies,accounts,cancel_all}`

Cancel actively trading strategies.

Example URI

DELETE http://houston/zipline/trade/?strategies=dual_moving_average.py&accounts=U12345&cancel_all=true

URI Parameters

strategies: str (optional) Example: dual_moving_average.py
limit to these strategies (pass multiple times for multiple strategies)
accounts: str (optional) Example: U12345
limit to these accounts (pass multiple times for multiple accounts)
cancel_all: bool (optional) Example: true
cancel all actively trading strategies

Response 200

Headers

Content-Type: application/json

Body

{}

alphalens

Performance analysis of alpha factors

Contents

Alphalens Tearsheets
Alphalens Utilities

Alphalens Tearsheets ¶

alphalens.tears.create_event_returns_tear_sheet(factor_data, returns, avgretplot=5, 15, long_short=True, group_neutral=False, std_bar=True, by_group=False)¶

Creates a tear sheet to view the average cumulative returns for a factor within a window (pre and post event).

Parameters

factor_data (pd.DataFrame - MultiIndex) –
A MultiIndex Series indexed by date (level 0) and asset (level 1), containing the values for a single alpha factor, the factor quantile/bin that factor value belongs to and (optionally) the group the asset belongs to.
- See full explanation in alphalens.utils.get_clean_factor_and_forward_returns
returns (pd.DataFrame) –
A DataFrame indexed by date with assets in the columns containing daily returns.
- See full explanation in alphalens.utils.get_clean_factor_and_forward_returns
avgretplot (tuple (int, int) - (before, after)) – If not None, plot quantile average cumulative returns
long_short (bool) – Should this computation happen on a long short portfolio? if so then factor returns will be demeaned across the factor universe
group_neutral (bool) – Should this computation happen on a group neutral portfolio? if so, returns demeaning will occur on the group level.
std_bar (boolean, optional) – Show plots with standard deviation bars, one for each quantile
by_group (bool) – If True, display graphs separately for each group.

alphalens.tears.create_event_study_tear_sheet(factor_data, returns, avgretplot=5, 15, rate_of_ret=True, n_bars=50)¶

Creates an event study tear sheet for analysis of a specific event.

Parameters

factor_data (pd.DataFrame - MultiIndex) – A MultiIndex DataFrame indexed by date (level 0) and asset (level 1), containing the values for a single event, forward returns for each period, the factor quantile/bin that factor value belongs to, and (optionally) the group the asset belongs to.
returns (pd.DataFrame, required only if 'avgretplot' is provided) –
A DataFrame indexed by date with assets in the columns containing daily returns.
- See full explanation in alphalens.utils.get_clean_factor_and_forward_returns
avgretplot (tuple (int, int) - (before, after), optional) – If not None, plot event style average cumulative returns within a window (pre and post event).
rate_of_ret (bool, optional) – Display rate of return instead of simple return in ‘Mean Period Wise Return By Factor Quantile’ and ‘Period Wise Return By Factor Quantile’ plots
n_bars (int, optional) – Number of bars in event distribution plot

alphalens.tears.create_full_tear_sheet(factor_data, long_short=True, group_neutral=False, by_group=False)¶

Creates a full tear sheet for analysis and evaluating single return predicting (alpha) factor.

Parameters

factor_data (pd.DataFrame - MultiIndex) –
A MultiIndex DataFrame indexed by date (level 0) and asset (level 1), containing the values for a single alpha factor, forward returns for each period, the factor quantile/bin that factor value belongs to, and (optionally) the group the asset belongs to.
- See full explanation in alphalens.utils.get_clean_factor_and_forward_returns
long_short (bool) –
Should this computation happen on a long short portfolio?
- See alphalens.tears.create_returns_tear_sheet for details on how this flag affects returns analysis
group_neutral (bool) –
Should this computation happen on a group neutral portfolio?
- See alphalens.tears.create_returns_tear_sheet for details on how this flag affects returns analysis
- See alphalens.tears.create_information_tear_sheet for details on how this flag affects information analysis
by_group (bool) – If True, display graphs separately for each group.

alphalens.tears.create_information_tear_sheet(factor_data, group_neutral=False, by_group=False)¶

Creates a tear sheet for information analysis of a factor.

Parameters

factor_data (pd.DataFrame - MultiIndex) –
A MultiIndex DataFrame indexed by date (level 0) and asset (level 1), containing the values for a single alpha factor, forward returns for each period, the factor quantile/bin that factor value belongs to, and (optionally) the group the asset belongs to.
- See full explanation in alphalens.utils.get_clean_factor_and_forward_returns
group_neutral (bool) – Demean forward returns by group before computing IC.
by_group (bool) – If True, display graphs separately for each group.

alphalens.tears.create_returns_tear_sheet(factor_data, long_short=True, group_neutral=False, by_group=False)¶

Creates a tear sheet for returns analysis of a factor.

Parameters

factor_data (pd.DataFrame - MultiIndex) –
A MultiIndex DataFrame indexed by date (level 0) and asset (level 1), containing the values for a single alpha factor, forward returns for each period, the factor quantile/bin that factor value belongs to, and (optionally) the group the asset belongs to.
- See full explanation in alphalens.utils.get_clean_factor_and_forward_returns
long_short (bool) – Should this computation happen on a long short portfolio? if so, then mean quantile returns will be demeaned across the factor universe. Additionally factor values will be demeaned across the factor universe when factor weighting the portfolio for cumulative returns plots
group_neutral (bool) – Should this computation happen on a group neutral portfolio? if so, returns demeaning will occur on the group level. Additionally each group will weight the same in cumulative returns plots
by_group (bool) – If True, display graphs separately for each group.

alphalens.tears.create_summary_tear_sheet(factor_data, long_short=True, group_neutral=False)¶

Creates a small summary tear sheet with returns, information, and turnover analysis.

Parameters

factor_data (pd.DataFrame - MultiIndex) –
A MultiIndex DataFrame indexed by date (level 0) and asset (level 1), containing the values for a single alpha factor, forward returns for each period, the factor quantile/bin that factor value belongs to, and (optionally) the group the asset belongs to.
- See full explanation in alphalens.utils.get_clean_factor_and_forward_returns
long_short (bool) – Should this computation happen on a long short portfolio? if so, then mean quantile returns will be demeaned across the factor universe.
group_neutral (bool) – Should this computation happen on a group neutral portfolio? if so, returns demeaning will occur on the group level.

alphalens.tears.create_turnover_tear_sheet(factor_data, turnover_periods=None)¶

Creates a tear sheet for analyzing the turnover properties of a factor.

Parameters

factor_data (pd.DataFrame - MultiIndex) –
A MultiIndex DataFrame indexed by date (level 0) and asset (level 1), containing the values for a single alpha factor, forward returns for each period, the factor quantile/bin that factor value belongs to, and (optionally) the group the asset belongs to.
- See full explanation in alphalens.utils.get_clean_factor_and_forward_returns
turnover_periods (sequence[string], optional) – Periods to compute turnover analysis on. By default periods in ‘factor_data’ are used but custom periods can provided instead. This can be useful when periods in ‘factor_data’ are not multiples of the frequency at which factor values are computed i.e. the periods are 2h and 4h and the factor is computed daily and so values like [‘1D’, ‘2D’] could be used instead

Alphalens Utilities ¶

alphalens.utils.get_clean_factor(factor, forward_returns, groupby=None, binning_by_group=False, quantiles=5, bins=None, groupby_labels=None, max_loss=0.35, zero_aware=False)¶

Formats the factor data, forward return data, and group mappings into a DataFrame that contains aligned MultiIndex indices of timestamp and asset. The returned data will be formatted to be suitable for Alphalens functions.

It is safe to skip a call to this function and still make use of Alphalens functionalities as long as the factor data conforms to the format returned from get_clean_factor_and_forward_returns and documented here

Parameters

factor (pd.Series - MultiIndex) –

A MultiIndex Series indexed by timestamp (level 0) and asset (level 1), containing the values for a single alpha factor.

-----------------------------------
    date    |    asset   |
-----------------------------------
            |   AAPL     |   0.5
            -----------------------
            |   BA       |  -1.1
            -----------------------
2014-01-01  |   CMG      |   1.7
            -----------------------
            |   DAL      |  -0.1
            -----------------------
            |   LULU     |   2.7
            -----------------------

forward_returns (pd.DataFrame - MultiIndex) –

A MultiIndex DataFrame indexed by timestamp (level 0) and asset (level 1), containing the forward returns for assets. Forward returns column names must follow the format accepted by pd.Timedelta (e.g. ‘1D’, ‘30m’, ‘3h15m’, ‘1D1h’, etc). ‘date’ index freq property must be set to a trading calendar (pandas DateOffset), see infer_trading_calendar for more details. This information is currently used only in cumulative returns computation

-----------------------------------------
           |       |  1D  |  5D  | 10D
-----------------------------------------
    date   | asset |      |      |
-----------------------------------------
           | AAPL  |  0.09| -0.01| -0.079
           ------------------------------
           | BA    |  0.02|  0.06|  0.020
           ------------------------------
2014-01-01 | CMG   |  0.03|  0.09|  0.036
           ------------------------------
           | DAL   | -0.02| -0.06| -0.029
           ------------------------------
           | LULU  | -0.03|  0.05| -0.009
           ------------------------------

groupby (pd.Series - MultiIndex or dict) – Either A MultiIndex Series indexed by date and asset, containing the period wise group codes for each asset, or a dict of asset to group mappings. If a dict is passed, it is assumed that group mappings are unchanged for the entire time period of the passed factor data.
binning_by_group (bool) – If True, compute quantile buckets separately for each group. This is useful when the factor values range vary considerably across gorups so that it is wise to make the binning group relative. You should probably enable this if the factor is intended to be analyzed for a group neutral portfolio
quantiles (int or sequence[float]) – Number of equal-sized quantile buckets to use in factor bucketing. Alternately sequence of quantiles, allowing non-equal-sized buckets e.g. [0, .10, .5, .90, 1.] or [.05, .5, .95] Only one of ‘quantiles’ or ‘bins’ can be not-None
bins (int or sequence[float]) – Number of equal-width (valuewise) bins to use in factor bucketing. Alternately sequence of bin edges allowing for non-uniform bin width e.g. [-4, -2, -0.5, 0, 10] Chooses the buckets to be evenly spaced according to the values themselves. Useful when the factor contains discrete values. Only one of ‘quantiles’ or ‘bins’ can be not-None
groupby_labels (dict) – A dictionary keyed by group code with values corresponding to the display name for each group.
max_loss (float, optional) – Maximum percentage (0.00 to 1.00) of factor data dropping allowed, computed comparing the number of items in the input factor index and the number of items in the output DataFrame index. Factor data can be partially dropped due to being flawed itself (e.g. NaNs), not having provided enough price data to compute forward returns for all factor values, or because it is not possible to perform binning. Set max_loss=0 to avoid Exceptions suppression.
zero_aware (bool, optional) – If True, compute quantile buckets separately for positive and negative signal values. This is useful if your signal is centered and zero is the separation between long and short signals, respectively. ‘quantiles’ is None.

Returns

merged_data – A MultiIndex Series indexed by date (level 0) and asset (level 1), containing the values for a single alpha factor, forward returns for each period, the factor quantile/bin that factor value belongs to, and (optionally) the group the asset belongs to.

forward returns column names follow the format accepted by pd.Timedelta (e.g. ‘1D’, ‘30m’, ‘3h15m’, ‘1D1h’, etc)

’date’ index freq property (merged_data.index.levels[0].freq) is the same as that of the input forward returns data. This is currently used only in cumulative returns computation

-------------------------------------------------------------------------
           |       |  1D  |  5D  |  10D  | factor| group| factor_quantile
-------------------------------------------------------------------------
    date   | asset |      |      |       |       |      |
-------------------------------------------------------------------------
           | AAPL  |  0.09| -0.01| -0.079|   0.5 |   G1 |      3
           --------------------------------------------------------------
           | BA    |  0.02|  0.06|  0.020|  -1.1 |   G2 |      5
           --------------------------------------------------------------
2014-01-01 | CMG   |  0.03|  0.09|  0.036|   1.7 |   G2 |      1
           --------------------------------------------------------------
           | DAL   | -0.02| -0.06| -0.029|  -0.1 |   G3 |      5
           --------------------------------------------------------------
           | LULU  | -0.03|  0.05| -0.009|   2.7 |   G1 |      2
           --------------------------------------------------------------

Return type

pd.DataFrame - MultiIndex

alphalens.utils.get_clean_factor_and_forward_returns(factor, prices, groupby=None, binning_by_group=False, quantiles=5, bins=None, periods=1, 5, 10, filter_zscore=20, groupby_labels=None, max_loss=0.35, zero_aware=False, cumulative_returns=True)¶

Formats the factor data, pricing data, and group mappings into a DataFrame that contains aligned MultiIndex indices of timestamp and asset. The returned data will be formatted to be suitable for Alphalens functions.

Parameters

factor (pd.Series - MultiIndex) –

A MultiIndex Series indexed by timestamp (level 0) and asset (level 1), containing the values for a single alpha factor.

-----------------------------------
    date    |    asset   |
-----------------------------------
            |   AAPL     |   0.5
            -----------------------
            |   BA       |  -1.1
            -----------------------
2014-01-01  |   CMG      |   1.7
            -----------------------
            |   DAL      |  -0.1
            -----------------------
            |   LULU     |   2.7
            -----------------------

prices (pd.DataFrame) –
A wide form Pandas DataFrame indexed by timestamp with assets in the columns. Pricing data must span the factor analysis time period plus an additional buffer window that is greater than the maximum number of expected periods in the forward returns calculations. It is important to pass the correct pricing data in depending on what time of period your signal was generated so to avoid lookahead bias, or delayed calculations. ‘Prices’ must contain at least an entry for each timestamp/asset combination in ‘factor’. This entry should reflect the buy price for the assets and usually it is the next available price after the factor is computed but it can also be a later price if the factor is meant to be traded later (e.g. if the factor is computed at market open but traded 1 hour after market open the price information should be 1 hour after market open). ‘Prices’ must also contain entries for timestamps following each timestamp/asset combination in ‘factor’, as many more timestamps as the maximum value in ‘periods’. The asset price after ‘period’ timestamps will be considered the sell price for that asset when computing ‘period’ forward returns.
```
-----------------------------------------------------
            |  AAPL |  BA  |  CMG  |  DAL  |  LULU  |
-----------------------------------------------------
   Date     |       |      |       |       |        |
-----------------------------------------------------
2014-01-01  | 605.12| 24.58|  11.72| 54.43 |  37.14 |
-----------------------------------------------------
2014-01-02  | 604.35| 22.23|  12.21| 52.78 |  33.63 |
-----------------------------------------------------
2014-01-03  | 607.94| 21.68|  14.36| 53.94 |  29.37 |
-----------------------------------------------------
```
groupby (pd.Series - MultiIndex or dict) – Either A MultiIndex Series indexed by date and asset, containing the period wise group codes for each asset, or a dict of asset to group mappings. If a dict is passed, it is assumed that group mappings are unchanged for the entire time period of the passed factor data.
binning_by_group (bool) – If True, compute quantile buckets separately for each group. This is useful when the factor values range vary considerably across gorups so that it is wise to make the binning group relative. You should probably enable this if the factor is intended to be analyzed for a group neutral portfolio
quantiles (int or sequence[float]) – Number of equal-sized quantile buckets to use in factor bucketing. Alternately sequence of quantiles, allowing non-equal-sized buckets e.g. [0, .10, .5, .90, 1.] or [.05, .5, .95] Only one of ‘quantiles’ or ‘bins’ can be not-None
bins (int or sequence[float]) – Number of equal-width (valuewise) bins to use in factor bucketing. Alternately sequence of bin edges allowing for non-uniform bin width e.g. [-4, -2, -0.5, 0, 10] Chooses the buckets to be evenly spaced according to the values themselves. Useful when the factor contains discrete values. Only one of ‘quantiles’ or ‘bins’ can be not-None
periods (sequence[int]) – periods to compute forward returns on.
filter_zscore (int or float, optional) – Sets forward returns greater than X standard deviations from the the mean to nan. Set it to ‘None’ to avoid filtering. Caution: this outlier filtering incorporates lookahead bias.
groupby_labels (dict) – A dictionary keyed by group code with values corresponding to the display name for each group.
max_loss (float, optional) – Maximum percentage (0.00 to 1.00) of factor data dropping allowed, computed comparing the number of items in the input factor index and the number of items in the output DataFrame index. Factor data can be partially dropped due to being flawed itself (e.g. NaNs), not having provided enough price data to compute forward returns for all factor values, or because it is not possible to perform binning. Set max_loss=0 to avoid Exceptions suppression.
zero_aware (bool, optional) – If True, compute quantile buckets separately for positive and negative signal values. This is useful if your signal is centered and zero is the separation between long and short signals, respectively.
cumulative_returns (bool, optional) – If True, forward returns columns will contain cumulative returns. Setting this to False is useful if you want to analyze how predictive a factor is for a single forward day.

Returns

forward returns column names follow the format accepted by pd.Timedelta (e.g. ‘1D’, ‘30m’, ‘3h15m’, ‘1D1h’, etc)

’date’ index freq property (merged_data.index.levels[0].freq) will be set to a trading calendar (pandas DateOffset) inferred from the input data (see infer_trading_calendar for more details). This is currently used only in cumulative returns computation

-------------------------------------------------------------------------
           |       |  1D  |  5D  |  10D  | factor| group| factor_quantile
-------------------------------------------------------------------------
    date   | asset |      |      |       |       |      |
-------------------------------------------------------------------------
           | AAPL  |  0.09| -0.01| -0.079|   0.5 |   G1 |      3
           --------------------------------------------------------------
           | BA    |  0.02|  0.06|  0.020|  -1.1 |   G2 |      5
           --------------------------------------------------------------
2014-01-01 | CMG   |  0.03|  0.09|  0.036|   1.7 |   G2 |      1
           --------------------------------------------------------------
           | DAL   | -0.02| -0.06| -0.029|  -0.1 |   G3 |      5
           --------------------------------------------------------------
           | LULU  | -0.03|  0.05| -0.009|   2.7 |   G1 |      2
           --------------------------------------------------------------

Return type

pd.DataFrame - MultiIndex

See also

alphalens.utils.get_clean_factor: For use when forward returns are already available.

moonchart

Moonchart tear sheets and performance analysis

Contents

DailyPerformance
AggregateDailyPerformance
Tearsheet
ParamscanTearsheet
ShortfallTearsheet
Utils

DailyPerformance ¶

class moonchart.DailyPerformance(returns, pnl=None, net_exposures=None, abs_exposures=None, total_holdings=None, turnover=None, commission_amounts=None, commissions=None, slippages=None, benchmark=None, riskfree=0, compound=True, rolling_sharpe_window=200, trim_outliers=None)¶

Class representing daily performance and derived statistics.

Typically constructed using DailyPerformance.from_moonshot_csv.

Parameters

returns (DataFrame, required) – a Dataframe of pct returns
pnl (DataFrame, optional) – a DataFrame of pnl
net_exposures (DataFrame, optional) – a Dataframe of net (hedged) exposure
abs_exposures (DataFrame, optional) – a Dataframe of absolute exposure (ignoring hedging)
total_holdings (DataFrame, optional) – a Dataframe of the number of holdings
turnover (DataFrame, optional) – a DataFrame of turnover, that is, changes to positions
commission_amounts (DataFrame, optional) – a DataFrame of commission amounts, in the base currency
commissions (DataFrame, optional) – a DataFrame of commissions, as a proportion of capital
slippages (DataFrame, optional) – a DataFrame of slippages, as a proportion of capital
benchmark (Series, optional) – a Series of prices for a benchmark
riskfree (float, optional) – the riskfree rate (default 0)
compound (bool) – True for compound/geometric returns, False for arithmetic returns (default True)
rolling_sharpe_window (int, optional) – compute rolling Sharpe over this many periods (default 200)
trim_outliers (int or float, optional) – discard returns that are more than this many standard deviations from the mean

classmethod from_moonshot_csv(filepath_or_buffer, start_date=None, end_date=None, trim_outliers=None, how_to_aggregate=None, riskfree=0, compound=True, rolling_sharpe_window=200)¶

Creates a DailyPerformance instance from a Moonshot backtest results CSV.

Parameters

filepath_or_buffer (str or file-like object) – filepath or file-like object of the CSV
start_date (str (YYYY-MM-DD), optional) – truncate at this start date (otherwise include entire date range)
end_date (str (YYYY-MM-DD), optional) – truncate at this end date (otherwise include entire date range)
trim_outliers (int or float, optional) – discard returns that are more than this many standard deviations from the mean. Useful for dealing with data anomalies that cause large spikes in plots.
how_to_aggregate (dict, optional) – a dict of {fieldname: aggregation method} specifying how to aggregate fields from intraday to daily. See the docstring for moonchart.utils.intraday_to_daily for more details.
riskfree (float, optional) – the riskfree rate (default 0)
compound (bool) – True for compound/geometric returns, False for arithmetic returns (default True)
rolling_sharpe_window (int, optional) – compute rolling Sharpe over this many periods (default 200)

Returns

Return type

DailyPerformance

Examples

Plot cumulative returns:

>>> perf = DailyPerformance.from_moonshot_csv("backtest_results.csv")
>>> perf.cum_returns.plot()

classmethod from_pnl_csv(filepath_or_buffer, start_date=None, end_date=None, trim_outliers=None, how_to_aggregate=None, riskfree=0, compound=True, rolling_sharpe_window=200)¶

Creates a DailyPerformance instance from a PNL CSV.

Parameters

filepath_or_buffer (str or file-like object) – filepath or file-like object of the CSV
start_date (str (YYYY-MM-DD), optional) – truncate at this start date (otherwise include entire date range)
end_date (str (YYYY-MM-DD), optional) – truncate at this end date (otherwise include entire date range)
trim_outliers (int or float, optional) – discard returns that are more than this many standard deviations from the mean
how_to_aggregate (dict, optional) – a dict of {fieldname: aggregation method} specifying how to aggregate fields from intraday to daily. See the docstring for moonchart.utils.intraday_to_daily for more details.
riskfree (float, optional) – the riskfree rate (default 0)
compound (bool) – True for compound/geometric returns, False for arithmetic returns (default True)
rolling_sharpe_window (int, optional) – compute rolling Sharpe over this many periods (default 200)

Returns

Return type

DailyPerformance

Examples

Plot cumulative returns:

>>> perf = DailyPerformance.from_pnl_csv("pnl.csv")
>>> perf.cum_returns.plot()

AggregateDailyPerformance ¶

class moonchart.AggregateDailyPerformance(performance, riskfree=None, compound=None, rolling_sharpe_window=None, trim_outliers=None)¶

Class representing aggregate daily performance.

Given a DailyPerformance instance containing multi-column (that is, multi-strategy or detailed single-strategy) DataFrames, this class represents the aggregate performance.

Parameters

performance (DailyPerformance, required) – daily performance results to aggregate
trim_outliers (int or float, optional) – discard returns that are more than this many standard deviations from the mean (copied from DailyPerformance if omitted)
riskfree (float, optional) – the riskfree rate (copied from DailyPerformance if omitted)
compound (bool) – True for compound/geometric returns, False for arithmetic returns (copied from DailyPerformance if omitted)
rolling_sharpe_window (int, optional) – compute rolling Sharpe over this many periods (copied from DailyPerformance if omitted)

Returns

Return type

AggregatePerformance

Examples

Plot aggregate cumulative returns:

>>> perf = DailyPerformance.from_moonshot_csv("backtest_results.csv")
>>> agg_perf = AggregateDailyPerformance(perf)
>>> agg_perf.cum_returns.plot()

__init__(performance, riskfree=None, compound=None, rolling_sharpe_window=None, trim_outliers=None)¶: Initialize self. See help(type(self)) for accurate signature.

Tearsheet ¶

class moonchart.Tearsheet(pdf_filename=None, figsize=None, max_cols_for_details=25)¶

Generates a tear sheet of performance stats and graphs.

classmethod from_moonshot_csv(filepath_or_buffer, figsize=None, max_cols_for_details=25, trim_outliers=None, how_to_aggregate=None, pdf_filename=None, riskfree=0, compound=True, rolling_sharpe_window=200)¶

Create a full tear sheet from a moonshot backtest results CSV.

Parameters

filepath_or_buffer (str or file-like object) – filepath of CSV or file-like object
figsize (tuple (width, height), optional) – (width, height) of matplotlib figure. Default is (16, 12)
max_cols_for_details (int, optional) – suppress detailed plots if there are more than this many columns (i.e. strategies or securities). Too many plots may cause slow rendering. Default 25.
trim_outliers (int or float, optional) – discard returns that are more than this many standard deviations from the mean. Useful for dealing with data anomalies that cause large spikes in plots.
how_to_aggregate (dict, optional) – a dict of {fieldname: aggregation method} specifying how to aggregate fields from intraday to daily. See the docstring for moonchart.utils.intraday_to_daily for more details.
pdf_filename (string, optional) – save tear sheet to this filepath as a PDF instead of displaying
riskfree (float, optional) – the riskfree rate (default 0)
compound (bool) – True for compound/geometric returns, False for arithmetic returns. Default True
rolling_sharpe_window (int, optional) – compute rolling Sharpe over this many periods (default 200)

Returns

Return type

None

Examples

>>> from moonshot import Tearsheet
>>> Tearsheet.from_moonshot_csv("backtest_results.csv")

classmethod from_pnl_csv(filepath_or_buffer, figsize=None, max_cols_for_details=25, trim_outliers=None, how_to_aggregate=None, pdf_filename=None, riskfree=0, compound=True, rolling_sharpe_window=200)¶

Create a full tear sheet from a pnl CSV.

Parameters

filepath_or_buffer (str or file-like object) – filepath or file-like object of the CSV
figsize (tuple (width, height), optional) – (width, height) of matplotlib figure. Default is (16, 12)
max_cols_for_details (int, optional) – suppress detailed plots if there are more than this many columns (i.e. strategies or securities). Too many plots may cause slow rendering. Default 25.
trim_outliers (int or float, optional) – discard returns that are more than this many standard deviations from the mean
how_to_aggregate (dict, optional) – a dict of {fieldname: aggregation method} specifying how to aggregate fields from intraday to daily. See the docstring for moonchart.utils.intraday_to_daily for more details.
pdf_filename (string, optional) – save tear sheet to this filepath as a PDF instead of displaying
riskfree (float, optional) – the riskfree rate (default 0)
compound (bool) – True for compound/geometric returns, False for arithmetic returns. Default True
rolling_sharpe_window (int, optional) – compute rolling Sharpe over this many periods (default 200)

Returns

Return type

None

create_montecarlo_tearsheet(performance, cycles=5, aggregate_before_shuffle=True)¶

Run a Montecarlo simulation by shuffling the DataFrame of returns a specified number of times and plotting the shuffled returns against the original returns.

Parameters

performance (DailyPerformance, required) – a DailyPerformance instance
cycles (int, optional) – the number of Montecarlo simulations (default 5)
aggregate_before_shuffle (bool) – whether to aggregate daily returns before or after shuffling. Only relevant to multi-column (that is, multi-strategy or detailed single-strategy) DataFrames. If True, aggregated daily returns are preserved and only the order of days is randomized. If False, each column’s returns are shuffled separately, without preservation of daily aggregations. False is more random. True may be preferable if daily returns across columns are expected to be correlated. Default True.

Returns

Return type

None

Examples

>>> from moonchart import DailyPerformance, Tearsheet
>>> perf = DailyPerformance.from_moonshot_csv("backtest_results.csv")
>>> t = Tearsheet()
>>> t.create_montecarlo_tearsheet(perf, cycles=10)

ParamscanTearsheet ¶

class moonchart.ParamscanTearsheet(pdf_filename=None, figsize=None, max_cols_for_details=25)¶

classmethod from_moonshot_csv(filepath_or_buffer, figsize=None, pdf_filename=None)¶

Create a parameter scan tear sheet from a Moonshot paramscan results CSV.

Parameters

filepath_or_buffer (str or file-like object) – filepath or file-like object of the CSV
figsize (tuple (width, height), optional) – (width, height) of matplotlib figure. Default is (16, 12)
pdf_filename (string, optional) – save tear sheet to this filepath as a PDF instead of displaying

Returns

Return type

None

Examples

>>> from moonshot import ParamscanTearsheet
>>> ParamscanTearsheet.from_moonshot_csv("paramscan_results.csv")

ShortfallTearsheet ¶

class moonchart.ShortfallTearsheet(*args, labels='simulated', 'actual', **kwargs)¶

Generate a tear sheet of performance stats and plots highlighting the shortfall between simulated or benchmark results and actual results.

See also

ShortfallTearsheet.from_csvs: Create a shortfall tear sheet from CSVs.

classmethod from_csvs(x_filepath_or_buffer, y_filepath_or_buffer, labels='simulated', 'actual', start_date=None, end_date=None, largest_n=None, shift_x_positions=0, figsize=None, trim_outliers=None, how_to_aggregate=None, pdf_filename=None, riskfree=0, compound=True, rolling_sharpe_window=200)¶

Create a shortfall tear sheet comparing simulated results (or other benchmark results) with actual results.

Parameters

x_filepath_or_buffer (str or file-like object) – filepath or file-like object of the CSV containing simulated results or other benchmark results, usually a Moonshot backtest CSV
y_filepath_or_buffer (str or file-like object) – filepath or file-like object of the CSV containing actual results, usually a PNL CSV from the blotter
labels (tuple, optional) – labels for the x and y results, default (‘simulated’, ‘actual’)
start_date (str (YYYY-MM-DD), optional) – truncate at this start date (otherwise include entire date range)
end_date (str (YYYY-MM-DD), optional) – truncate at this end date (otherwise include entire date range)
largest_n (int, optional) – include a “largest shortfalls” table with this many records highligting the dates and specific instruments or strategies (depending on whether the columns of the input CSVs are instruments or strategies) with the largest magnitude shortfall (positive or negative). Also results in additional plots depicting performance exluding the largest shortfalls. Default is None, meaning don’t include a largest shortfalls table or additional plots.
shift_x_positions (int, optional) – shift positions forward (positive integer) or backward (negative integer) in simulated/benchmark results. Can be used to align simulated positions with actual positions.
figsize (tuple (width, height), optional) – (width, height) of matplotlib figure. Default is (16, 12)
trim_outliers (int or float, optional) – discard returns that are more than this many standard deviations from the mean
how_to_aggregate (dict, optional) – a dict of {fieldname: aggregation method} specifying how to aggregate fields from intraday to daily. See the docstring for moonchart.utils.intraday_to_daily for more details.
pdf_filename (string, optional) – save tear sheet to this filepath as a PDF instead of displaying
riskfree (float, optional) – the riskfree rate (default 0)
compound (bool) – True for compound/geometric returns, False for arithmetic returns. Default True
rolling_sharpe_window (int, optional) – compute rolling Sharpe over this many periods (default 200)

Returns

DataFrame of largest shortfalls if largest_n is not None, otherwise None

Return type

DataFrame or None

Examples

>>> from moonshot import ShortfallTearsheet
>>> ShortfallTearsheet.from_csvs("backtest.csv", "pnl.csv")

Utils ¶

moonchart.utils.set_default_palette()¶: Sets the default palette so that the first 3 colors are blue, green, red. This was the case in Matplotlib 2 but in Matplotlib the default sequence is blue, orange, green, red, which is not as good for Moonchart plots. This function will remove orange from position 2 and put it at the end.

moonchart.utils.get_zscores(returns)¶

Returns the Z-scores of the input returns.

Parameters: returns (Series or DataFrame, required) – Series or DataFrame of returns
Returns
Return type: Series or DataFrame

moonchart.utils.trim_outliers(returns, z_score)¶

Zeroes out observations that are too many standard deviations from the mean.

Parameters

returns (Series or DataFrame, required) – Series or DataFrame of returns
z_score (int or float, required) – maximum standard deviation values are allowed to be from the mean

Returns

Return type

Series or DataFrame

moonchart.utils.with_baseline(data, value=1)¶

Prepends a date-indexed Series or DataFrame with an initial row that is one period earlier than the first row and has the specified value.

The typical use case is for generating plots: without a baseline row, a cumulative returns plot won’t start from 1 if the first day’s return is nonzero.

Parameters

data (Series or DataFrame, required) – Series or DataFrame (for example, of returns)
value (required) – value to insert in the baseline row

Returns

Return type

Series or DataFrame

Examples

Typical usage:

>>> with_baseline(cum_returns).plot()

Under the hood:

>>> cum_returns.head()
    2019-01-02   1.01
    2019-01-03  0.995
>>> with_baseline(cum_returns)
    2019-01-01      1
    2019-01-02   1.01
    2019-01-03  0.995

moonchart.utils.get_sharpe(returns, riskfree=0)¶

Returns the Sharpe ratio of the returns.

Parameters

returns (Series or DataFrame, required) – a Series or DataFrame of returns
riskfree (float, optional) – the risk-free rate (default 0)

Returns

Return type

float or Series of floats

moonchart.utils.get_rolling_sharpe(returns, window, riskfree=0)¶

Computes rolling Sharpe ratios for the returns.

Parameters

returns (Series or DataFrame, required) – a Series or DataFrame of returns
window (int, required) – rolling window length
riskfree (float, optional) – the risk-free rate (default 0)

Returns

Return type

Series or DataFrame

moonchart.utils.get_cum_returns(returns, compound=True)¶

Computes the cumulative returns of the provided returns.

Parameters

returns (Series or DataFrame, required) – a Series or DataFrame of returns
compound (bool) – True for compounded (geometric) returns, False for arithmetic returns (default True)

Returns

Return type

Series or DataFrame

moonchart.utils.get_cagr(cum_returns, compound=True)¶

Computes the CAGR from the cumulative returns.

Parameters

cum_returns (Series or DataFrame, required) – a Series or DataFrame of cumulative returns
compound (bool) – compute compound annual growth rate if True, otherwise compute average annual return (default True)

Returns

Return type

float or Series of floats

moonchart.utils.get_drawdowns(cum_returns)¶

Computes the drawdowns of the cumulative returns.

Parameters: cum_returns (Series or DataFrame, required) – a Series or DataFrame of cumulative returns
Returns
Return type: Series or DataFrame

moonchart.utils.get_top_movers(returns, n=10)¶

Returns the biggest gainers and losers in the returns.

Parameters

returns (Series or DataFrame, required) – a Series or DataFrame of returns
n (int, optional) – the number of biggest gainers and losers to return (default 10)

Returns

Return type

Series or DataFrame

moonchart.utils.intraday_to_daily(results, how=None)¶

Roll up a DataFrame of intraday performance results to daily, dropping the “Time” level from the multi-index.

The following aggregation methods are supported:

extreme: min or max of day, whichever is of greater absolute magnitude last: last value of day max: max of day mean: mean of day sum: sum of day

By default, supported fields are aggregated as follows:

AbsExposure: max AbsWeight: max Benchmark: last Commission: sum CommissionAmount: sum NetExposure: extreme NetLiquidation: mean Pnl: sum PositionQuantity: extreme PositionValue: extreme Price: last Return: sum Slippage: sum TotalHoldings: max Turnover: sum Weight: extreme

This can be overridden with the how parameter.

Parameters

results (DataFrame, required) – a DataFrame of intraday Moonshot backtest results or PNL results, with a “Time” level in the index
how (dict, optional) – a dict of {fieldname: aggregation method} specifying how to aggregate fields. This is combined with and overrides the default methods.

Returns

a DataFrame of daily results, without a “Time” level in the index

Return type

DataFrame

Examples

Convert intraday Moonshot results to daily:

>>> intraday_results = read_moonshot_csv("moonshot_intraday_backtest.csv")
>>> daily_results = intraday_to_daily(intraday_results)

moonshot

This API is for writing Moonshot strategies. For backtesting and live trading of Moonshot strategies, see the quantrocket.moonshot API.

Contents

Moonshot strategy
Moonshot machine learning strategy
Strategy mixins
Commissions
Slippage

Moonshot strategy ¶

class moonshot.Moonshot¶

Base class for Moonshot strategies.

To create a strategy, subclass this class. Implement your trading logic in the class methods, and store your strategy parameters as class attributes.

Class attributes include built-in Moonshot parameters which you can override, as well as your own custom parameters.

To run a backtest, at minimum you must implement prices_to_signals, but in general you will want to implement the following methods (which are called in the order shown):

prices_to_signals -> signals_to_target_weights -> target_weights_to_positions -> positions_to_gross_returns

To trade (i.e. generate orders intended to be placed, but actually placed by other services than Moonshot), you must also implement order_stubs_to_orders. Order generation for trading follows the path shown below:

prices_to_signals -> signals_to_target_weights -> order_stubs_to_orders

Parameters

CODE (str, required) – the strategy code
DB (str, required) – code of db to pull data from
DB_FIELDS (list of str, optional) – fields to retrieve from db (defaults to [“Open”, “Close”, “Volume”])
DB_TIMES (list of str (HH:MM:SS), optional) – for intraday databases, only retrieve these times
SIDS (list of str, optional) – limit db query to these sids
UNIVERSES (list of str, optional) – limit db query to these universes
EXCLUDE_SIDS (list of str, optional) – exclude these sids from db query
EXCLUDE_UNIVERSES (list of str, optional) – exclude these universes from db query
CONT_FUT (str, optional) – pass this cont_fut option to db query (default None)
LOOKBACK_WINDOW (int, optional) – get this many days additional data prior to the backtest start date or trade date to account for rolling windows. If set to None (the default), will use the largest value of any attributes ending with *_WINDOW, or 252 if no such attributes, and will further pad window based on any *_INTERVAL attributes, which are interpreted as pandas offset aliases (for example REBALANCE_INTERVAL = ‘Q’). Set to 0 to disable.
NLV (dict, optional) – dict of currency:NLV for each currency represented in the strategy. Can alternatively be passed directly to backtest method.
COMMISSION_CLASS (Class or dict of (sectype,exchange,currency):Class, optional) – the commission class to use. If strategy includes a mix of security types, exchanges, or currencies, you can pass a dict mapping tuples of (sectype,exchange,currency) to the different commission classes. By default no commission is applied.
SLIPPAGE_CLASSES (iterable of slippage classes, optional) – one or more slippage classes. By default no slippage is applied.
SLIPPAGE_BPS (float, optional) – amount on one-slippage to apply to each trade in BPS (for example, enter 5 to deduct 5 BPS)
BENCHMARK (str, optional) – the sid of a security in the historical data to use as the benchmark
BENCHMARK_DB (str, optional) – the database containing the benchmark, if different from DB. BENCHMARK_DB should contain end-of-day data, not intraday (but can be used with intraday backtests).
BENCHMARK_TIME (str (HH:MM:SS), optional) – use prices from this time of day as benchmark prices. Only applicable if benchmark prices originate in DB (not BENCHMARK_DB), DB contains intraday data, and backtest results are daily.
TIMEZONE (str, optional) – convert timestamps to this timezone (if not provided, will be inferred from securities universe if possible)
CALENDAR (str, optional) – use this exchange’s trading calendar to determine which date’s signals should be used for live trading. If the exchange is currently open, today’s signals will be used. If currently closed, the signals corresponding to the last date the exchange was open will be used. If no calendar is specified, today’s signals will be used.
POSITIONS_CLOSED_DAILY (bool) – if True, positions in backtests that fall on adjacent days are assumed to be closed out and reopened each day rather than held continuously; this impacts commission and slippage calculations (default is False, meaning adjacent positions are assumed to be held continuously)
ALLOW_REBALANCE (bool or float) – in live trading, whether to allow rebalancing of existing positions that are already on the correct side. If True (the default), allow rebalancing. If False, no rebalancing. If set to a positive decimal, allow rebalancing only when the existing position differs from the target position by at least this percentage. For example 0.5 means don’t rebalance a position unless the position will change by +/-50%.
CONTRACT_VALUE_REFERENCE_FIELD (str, optional) – the price field to use for determining contract values for the purpose of applying commissions and constraining weights in backtests and calculating order quantities in trading. Defaults to the first available of Close, Open, LastPriceClose, BidPriceClose, AskPriceClose, TimeSalesLastPriceClose, TimeSalesFilteredLastPriceClose, LastPriceMean, BidPriceMean, AskPriceMean, TimeSalesLastPriceMean, TimeSalesFilteredLastPriceMean, LastPriceOpen, BidPriceOpen, AskPriceOpen, TimeSalesLastPriceOpen, TimeSalesFilteredLastPriceOpen.

Examples

Example of a minimal strategy that runs on a history db called “mexi-stk-1d” and buys when the securities are above their 200-day moving average:

>>> MexicoMovingAverage(Moonshot):
>>>
>>>     CODE = "mexi-ma"
>>>     DB = "mexi-stk-1d"
>>>     MAVG_WINDOW = 200
>>>
>>>     def prices_to_signals(self, prices):
>>>         closes = prices.loc["Close"]
>>>         mavgs = closes.rolling(self.MAVG_WINDOW).mean()
>>>         signals = closes > mavgs.shift()
>>>         return signals.astype(int)

prices_to_signals(prices)¶

From a DataFrame of prices, return a DataFrame of signals. By convention, signals should be 1=long, 0=cash, -1=short.

Must be implemented by strategy subclasses.

Parameters: prices (DataFrame, required) – multiindex (Field, Date) or (Field, Date, Time) DataFrame of price/market data
Returns: signals
Return type: DataFrame

Examples

Buy when the close is above yesterday’s 50-day moving average:

>>> def prices_to_signals(self, prices):
>>>     closes = prices.loc["Close"]
>>>     mavgs = closes.rolling(50).mean()
>>>     signals = closes > mavgs.shift()
>>>     return signals.astype(int)

signals_to_target_weights(signals, prices)¶

From a DataFrame of signals, return a DataFrame of target weights.

Whereas signals indicate the direction of the trades, weights indicate both the direction and size. For example, -0.5 means a short position equal to 50% of the equity allocated to the strategy.

Weights are used to help create orders in live trading, and to help simulate executed positions in backtests.

The default implemention of this method evenly divides allocated capital among the signals each period, but it is intended to be overridden by strategy subclasses.

A variety of built-in weight allocation algorithms are provided by and documented under moonshot.mixins.WeightAllocationMixin.

Parameters

signals (DataFrame, required) – a DataFrame of signals
prices (DataFrame, required) – multiindex (Field, Date) or (Field, Date, Time) DataFrame of price/market data

Returns

weights

Return type

DataFrame

Examples

The default implementation is shown below:

>>> def signals_to_target_weights(self, signals, prices):
>>>     weights = self.allocate_equal_weights(signals) # provided by moonshot.mixins.WeightAllocationMixin
>>>     return weights

target_weights_to_positions(weights, prices)¶

From a DataFrame of target weights, return a DataFrame of simulated positions.

The positions should shift the weights based on when the weights would be filled in live trading.

By default, assumes the position are taken in the period after the weights were allocated. Intended to be overridden by strategy subclasses.

Parameters

weights (DataFrame, required) – a DataFrame of weights
prices (DataFrame, required) – multiindex (Field, Date) or (Field, Date, Time) DataFrame of price/market data

Returns

positions

Return type

DataFrame

Examples

The default implemention is shown below (enter position in the period after signal generation/weight allocation):

>>> def target_weights_to_positions(self, weights, prices):
>>>     positions = weights.shift()
>>>     return positions

positions_to_gross_returns(positions, prices)¶

From a DataFrame of positions, return a DataFrame of returns before commissions and slippage.

By default, assumes entry on the close on the period the position is taken and calculates the return through the following period’s close. Intended to be overridden by strategy subclasses.

Parameters

positions (DataFrame, required) – a DataFrame of positions
prices (DataFrame, required) – multiindex (Field, Date) or (Field, Date, Time) DataFrame of price/market data

Returns

gross returns

Return type

DataFrame

Examples

The default implementation is shown below:

>>> def positions_to_gross_returns(self, positions, prices):
>>>     closes = prices.loc["Close"]
>>>     gross_returns = closes.pct_change() * positions.shift()
>>>     return gross_returns

order_stubs_to_orders(orders, prices)¶

From a DataFrame of order stubs, creates a DataFrame of fully specified orders.

Parameters

orders (DataFrame) – a DataFrame of order stubs, with columns Sid, Account, Action, OrderRef, and TotalQuantity
prices (DataFrame) – multiindex (Field, Date) or (Field, Date, Time) DataFrame of price/market data

Returns

a DataFrame of fully specified orders, with (at minimum) columns Exchange, Tif, OrderType added

Return type

DataFrame

Examples

The orders DataFrame provided to this method resembles the following:

>>> print(orders)
      Sid  Account Action     OrderRef  TotalQuantity
 12345   U12345   SELL  my-strategy            100
 12345   U55555   SELL  my-strategy             50
 23456   U12345    BUY  my-strategy            100
 23456   U55555    BUY  my-strategy             50
 34567   U12345    BUY  my-strategy            200
 34567   U55555    BUY  my-strategy            100

The default implemention creates MKT DAY orders and is shown below:

>>> def order_stubs_to_orders(self, orders, prices):
>>>     orders["OrderType"] = "MKT"
>>>     orders["Tif"] = "DAY"
>>>     return orders

Set a limit price equal to the prior closing price:

>>> closes = prices.loc["Close"]
>>> prior_closes = closes.shift()
>>> prior_closes = self.reindex_like_orders(prior_closes, orders)
>>> orders["OrderType"] = "LMT"
>>> orders["LmtPrice"] = prior_closes

reindex_like_orders(df, orders)¶

Reindexes a DataFrame (having Sids as columns and dates as index) to match the shape of the orders DataFrame.

Parameters

df (DataFrame, required) – a DataFrame of arbitrary values with Sids as columns and dates as index
orders (DataFrame, required) – an orders DataFrame with a Sid column

Returns

a Series with an index matching orders

Return type

Series

Examples

Calculate prior closes (assuming daily bars) and reindex like orders:

>>> closes = prices.loc["Close"]
>>> prior_closes = closes.shift()
>>> prior_closes = self.reindex_like_orders(prior_closes, orders)

Calculate prior closes (assuming 30-min bars) and reindex like orders:

>>> session_closes = prices.loc["Close"].xs("15:30:00", level="Time")
>>> prior_closes = session_closes.shift()
>>> prior_closes = self.reindex_like_orders(prior_closes, orders)

orders_to_child_orders(orders)¶

From a DataFrame of orders, returns a DataFrame of child orders (bracket orders) to be submitted if the parent orders fill.

An OrderId column will be added to the orders DataFrame, and child orders will be linked to it via a ParentId column. The Action (BUY/SELL) will be reversed on the child orders but otherwise the child orders will be identical to the parent orders.

Parameters: orders (DataFrame, required) – an orders DataFrame
Returns: a DataFrame of child orders
Return type: DataFrame

Examples

>>> orders.head()
      Sid   Action  TotalQuantity Exchange OrderType  Tif
0   12345      BUY            200    SMART       MKT  Day
1   23456      BUY            400    SMART       MKT  Day
>>> child_orders = self.orders_to_child_orders(orders)
>>> child_orders.loc[:, "OrderType"] = "MOC"
>>> orders = pd.concat([orders,child_orders])
>>> orders.head()
      Sid   Action  TotalQuantity Exchange OrderType  Tif  OrderId  ParentId
0   12345      BUY            200    SMART       MKT  Day        0       NaN
1   23456      BUY            400    SMART       MKT  Day        1       NaN
0   12345     SELL            200    SMART       MOC  Day      NaN         0
1   23456     SELL            400    SMART       MOC  Day      NaN         1

limit_position_sizes(prices)¶

This method should return a tuple of DataFrames:

return max_quantities_for_longs, max_quantities_for_shorts

where the DataFrames define the maximum number of shares/contracts that can be held long and short, respectively. Maximum limits might be based on available liquidity (recent volume), shortable shares available, etc.

The shape and alignment of the returned DataFrames should match that of the target_weights returned by signals_to_target_weights. Target weights will be reduced, if necessary, based on max_quantities_for_longs and max_quantities_for_shorts.

Return None for one or both DataFrames to indicate “no limits.” For example to limit shorts but not longs:

return None, max_quantities_for_shorts

Within a DataFrame, any None or NaNs will be treated as “no limit” for that particular security and date.

Note that max_quantities_for_shorts can equivalently be represented with positive or negative numbers. This is OK:

            AAPL
2018-05-18   100
2018-05-19   100

This is also OK:

            AAPL
2018-05-18  -100
2018-05-19  -100

Both of the above DataFrames would mean: short no more than 100 shares of AAPL.

Parameters: prices (DataFrame, required) – multiindex (Field, Date) or (Field, Date, Time) DataFrame of price/market data
Returns: max quantities for long, max quantities for shorts
Return type: tuple of (DataFrame, DataFrame)

Examples

Limit quantities to 1% of 15-day average daily volume:

>>> def limit_position_sizes(self, prices):
>>>     # assumes end-of-day bars, for intraday bars, use `.xs` to
>>>     # select a time of day
>>>     volumes = prices.loc["Volume"]
>>>     mean_volumes = volumes.rolling(15).mean()
>>>     max_shares = (mean_volumes * 0.01).round()
>>>     max_quantities_for_longs = max_quantities_for_shorts = max_shares
>>>     return max_quantities_for_longs, max_quantities_for_shorts

get_prices(start_date, end_date=None, nlv=None, no_cache=False)¶: Downloads prices from a history db and/or real-time aggregate db. Downloads security details from the master db.

save_to_results(name, df)¶

Saves the DataFrame to the backtest results output.

DataFrame should have a Date or (Date, Time) index with Sids as columns.

Parameters

name (str, required) – the name to assign to the DataFrame
df (DataFrame, required) – the DataFrame to save

Returns

Return type

None

Examples

Save moving averages of closing prices to results:

>>> closes = prices.loc["Close"]
>>> mavgs = closes.rolling(50).mean()
>>> self.save_to_results("MAvg", mavgs)

Moonshot machine learning strategy ¶

class moonshot.MoonshotML(*args, **kwargs)¶

Base class for Moonshot machine learning strategies.

To create a strategy, subclass this class. Implement your trading logic in the class methods, and store your strategy parameters as class attributes.

Class attributes include built-in Moonshot parameters which you can override, as well as your own custom parameters.

To run a backtest, at minimum you must implement prices_to_features and predictions_to_signals, but in general you will want to implement the following methods (which are called in the order shown):

prices_to_features -> predictions_to_signals -> signals_to_target_weights -> target_weights_to_positions -> positions_to_gross_returns

prices_to_features -> predictions_to_signals -> signals_to_target_weights -> order_stubs_to_orders

Parameters

CODE (str, required) – the strategy code
MODEL (str, optional) – path of machine learning model to load (for scikit-learn models, a joblib or pickle file); alternatively model can be passed as a parameter to backtest method, in which case the MODEL parameter is ignored
DB (str, required) – code of db to pull data from
DB_FIELDS (list of str, optional) – fields to retrieve from db (defaults to [“Open”, “Close”, “Volume”])
DB_TIMES (list of str (HH:MM:SS), optional) – for intraday databases, only retrieve these times
SIDS (list of str, optional) – limit db query to these sids
UNIVERSES (list of str, optional) – limit db query to these universes
EXCLUDE_SIDS (list of str, optional) – exclude these sids from db query
EXCLUDE_UNIVERSES (list of str, optional) – exclude these universes from db query
CONT_FUT (str, optional) – pass this cont_fut option to db query (default None)
LOOKBACK_WINDOW (int, optional) – get this many days additional data prior to the backtest start date or trade date to account for rolling windows. If set to None (the default), will use the largest value of any attributes ending with *_WINDOW, or 252 if no such attributes, and will further pad window based on any *_INTERVAL attributes, which are interpreted as pandas offset aliases (for example REBALANCE_INTERVAL = ‘Q’). Set to 0 to disable.
NLV (dict, optional) – dict of currency:NLV for each currency represented in the strategy. Can alternatively be passed directly to backtest method.
COMMISSION_CLASS (Class or dict of (sectype,exchange,currency):Class, optional) – the commission class to use. If strategy includes a mix of security types, exchanges, or currencies, you can pass a dict mapping tuples of (sectype,exchange,currency) to the different commission classes. By default no commission is applied.
SLIPPAGE_CLASSES (iterable of slippage classes, optional) – one or more slippage classes. By default no slippage is applied.
SLIPPAGE_BPS (float, optional) – amount on one-slippage to apply to each trade in BPS (for example, enter 5 to deduct 5 BPS)
BENCHMARK (str, optional) – the sid of a security in the historical data to use as the benchmark
BENCHMARK_DB (str, optional) – the database containing the benchmark, if different from DB. BENCHMARK_DB should contain end-of-day data, not intraday (but can be used with intraday backtests).
BENCHMARK_TIME (str (HH:MM:SS), optional) – use prices from this time of day as benchmark prices. Only applicable if benchmark prices originate in DB (not BENCHMARK_DB), DB contains intraday data, and backtest results are daily.
TIMEZONE (str, optional) – convert timestamps to this timezone (if not provided, will be inferred from securities universe if possible)
CALENDAR (str, optional) – use this exchange’s trading calendar to determine which date’s signals should be used for live trading. If the exchange is currently open, today’s signals will be used. If currently closed, the signals corresponding to the last date the exchange was open will be used. If no calendar is specified, today’s signals will be used.
POSITIONS_CLOSED_DAILY (bool) – if True, positions in backtests that fall on adjacent days are assumed to be closed out and reopened each day rather than held continuously; this impacts commission and slippage calculations (default is False, meaning adjacent positions are assumed to be held continuously)
ALLOW_REBALANCE (bool or float) – in live trading, whether to allow rebalancing of existing positions that are already on the correct side. If True (the default), allow rebalancing. If False, no rebalancing. If set to a positive decimal, allow rebalancing only when the existing position differs from the target position by at least this percentage. For example 0.5 means don’t rebalance a position unless the position will change by +/-50%.

Examples

Example of a minimal strategy that runs on a history db called “usa-stk-1d”, trains the model using the 1-day and 2-day returns, and buys when the machine learning model predicts a positive 1-day forward return:

>>> class DemoMLStrategy(MoonshotML):
>>>
>>>     CODE = "demo-ml"
>>>     DB = "usa-stk-1d"
>>>     MODEL = "my_ml_model.pkl"
>>>
>>>     def prices_to_features(self, prices):
>>>         closes = prices.loc["Close"]
>>>         features = {}
>>>         features["returns_1d"]= closes.pct_change()
>>>         features["returns_2d"] = (closes - closes.shift(2)) / closes.shift(2)
>>>         targets = closes.pct_change().shift(-1)
>>>         return features, targets
>>>
>>>     def predictions_to_signals(self, predictions, prices):
>>>         signals = predictions > 0
>>>         return signals.astype(int)

prices_to_features(prices)¶

From a DataFrame of prices, return a tuple of features and targets to be provided to the machine learning model.

The returned features can be a list or dict of DataFrames, where each DataFrame is a feature and should have the same shape, with a Date or (Date, Time) index and sids as columns. (Moonshot will convert the DataFrames to the format expected by the machine learning model).

Alternatively, a list or dict of Series can be provided, which is suitable if using multiple securities to make predictions for a single security (for example, an index).

The returned targets should be a DataFrame or Series with an index matching the index of the features DataFrames or Series. Targets are used in training and are ignored for prediction. (Model training is not handled by the MoonshotML class.) Alternatively return None if using an already trained model.

Must be implemented by strategy subclasses.

Parameters: prices (DataFrame, required) – multiindex (Field, Date) or (Field, Date, Time) DataFrame of price/market data
Returns: features
Return type: dict or list of DataFrames or Series

Examples

Predict next-day returns based on 1-day and 2-day returns:

>>> def prices_to_features(self, prices):
>>>     closes = prices.loc["Close"]
>>>     features = {}
>>>     features["returns_1d"]= closes.pct_change()
>>>     features["returns_2d"] = (closes - closes.shift(2)) / closes.shift(2)
>>>     targets = closes.pct_change().shift(-1)
>>>     return features, targets

Predict next-day returns for a single security in the prices DataFrame using another security’s returns:

>>> def prices_to_features(self, prices):
>>>     closes = prices.loc["Close"]
>>>     closes_to_predict = closes[12345]
>>>     closes_to_predict_with = closes[23456]
>>>     features = {}
>>>     features["returns_1d"]= closes_to_predict_with.pct_change()
>>>     features["returns_2d"] = (closes_to_predict_with - closes_to_predict_with.shift(2)) / closes_to_predict_with.shift(2)
>>>     targets = closes_to_predict.pct_change().shift(-1)
>>>     return features, targets

predictions_to_signals(predictions, prices)¶

From a DataFrame of predictions produced by a machine learning model, return a DataFrame of signals. By convention, signals should be 1=long, 0=cash, -1=short.

The index of predictions will match the index of the features DataFrames or Series returned in prices_to_features.

Must be implemented by strategy subclasses.

Parameters

predictions (DataFrame, required) – DataFrame of machine learning predictions
prices (DataFrame, required) – multiindex (Field, Date) or (Field, Date, Time) DataFrame of price/market data

Returns

signals

Return type

DataFrame

Examples

Buy when prediction (a DataFrame) is above zero.

>>> def predictions_to_signals(self, predictions, prices):
>>>     signals = predictions > 0
>>>     return signals.astype(int)

Buy a single security when the predictions (a Series) is above zero.

>>> def predictions_to_signals(self, predictions, prices):
>>>     closes = prices.loc["Close"]
>>>     signals = pd.DataFrame(False, index=closes.index, columns=closes.columns)
>>>     signals.loc[:, 12345] = predictions > 0
>>>     return signals.astype(int)

Strategy mixins ¶

class moonshot.mixins.WeightAllocationMixin¶

Mixin class with utilities for turning signals into weights.

allocate_equal_weights(signals, cap=1.0)¶: For multi-security strategies. Given a dataframe of whole number signals (-1, 0, 1), reduces the position size so that the absolute sum of all weights is never greater than the cap.

allocate_fixed_weights(signals, weight)¶: Applies the specified fixed weight to the signals.

allocate_fixed_weights_capped(signals, weight, cap=1.0)¶: Applies fixed weights, but if the sum of the weights exceeds the cap, applies equal weights.

allocate_market_neutral_fixed_weights_capped(signals, weight, cap=1.0, neutralize_weights=True)¶: Applies fixed capped weights to the long and short side separately to ensure the strategy is hedged.

neutralize_weights(weights)¶: If the long or short side has a greater total weight than the opposite side, proportionately reduces the overweight side.

Commissions ¶

class moonshot.commission.PercentageCommission¶

Base class for commissions which are a fixed percentage of the trade value. These commissions consist of a broker commission percentage rate (which might vary based on monthly trade volume) plus a fixed exchange fee percentage rate.

This class can’t be used directly but should be subclassed with the appropriate parameters.

Parameters

BROKER_COMMISSION_RATE (float, required) – the commission rate (as a percentage of trade value) charged by the broker
BROKER_COMMISSION_RATE_TIER_2 (float, optional) – the commission rate (as a percentage of trade value) charged by the broker at monthly volume tier 2
TIER_2_RATIO (float, optional) – the ratio of monthly trades at volume tier 2 (default 0)
EXCHANGE_FEE_RATE (float, required) – the exchange fee as a percentage of trade value
MIN_COMMISSION (float, optional) – the minimum commission charged by the broker. Only enforced if NLVs are passed by the backtest.

Examples

Example commission subclass for Tokyo Stock Exchange:

>>> class JapanStockCommission(PercentageCommission):
>>>     BROKER_COMMISSION_RATE = 0.0005
>>>     EXCHANGE_FEE_RATE = 0.000004
>>>     MIN_COMMISSION = 80.00 # JPY
>>>
>>>  # then, use this on your strategy:
>>>  class MyJapanStrategy(Moonshot):
>>>      COMMISSION_CLASS = JapanStockCommission

class moonshot.commission.PerShareCommission¶

Base class for commissions which are primarily based on the number of shares.

This class can’t be used directly but should be subclassed with the appropriate parameters.

Parameters

BROKER_COMMISSION_PER_SHARE (float, required) – the broker commission per share at the lowest volume tier
BROKER_COMMISSION_PER_SHARE_TIER_2 (float, optional) – the broker commission per share at volume tier 2
TIER_2_RATIO (float, optional) – ratio of monthly trades at volume tier 2
EXCHANGE_FEE_PER_SHARE (float, optional) – the sum of all exchange fees which are assessed per share (excluding maker-taker fees, if defined separately)
MAKER_FEE_PER_SHARE (float, optional) – the “maker” fee from the exchange for adding liquidity. Use a negative value to indicate a rebate
TAKER_FEE_PER_SHARE (float, optional) – the “taker” fee paid to the exchange for removing liquidity
MAKER_RATIO (float, optional) – the ratio of trades that earn the maker fee (for example if 75% of trades add liquidty and 25% remove liqudity, this value should be 0.75)
PERCENTAGE_FEE_RATE (float, optional) – the sum of all fees which are assessed as a percentage of trade value
COMMISSION_PERCENTAGE_FEE_RATE (float, optional) – the sum of all fees which are assessed as a percentage of the broker commission
MIN_COMMISSION (float, optional) – the minimum commission charged by the broker. Only enforced if NLVs are passed by the backtest.

Examples

Example subclass for US stock comission with fixed pricing:

>>> class USStockCommission(PerShareCommission):
>>>     BROKER_COMMISSION_PER_SHARE = 0.005
>>>     MIN_COMMISSION = 1.00
>>>
>>>  # then, use this on your strategy:
>>>  class MyUSAStrategy(Moonshot):
>>>      COMMISSION_CLASS = USStockCommission

Example subclass for US Cost-Plus stock comissions:

>>> class CostPlusUSStockCommission(PerShareCommission):
>>>     BROKER_COMMISSION_PER_SHARE = 0.0035
>>>     EXCHANGE_FEE_PER_SHARE = (0.0002 # clearing fee per share
>>>                              + (0.000119/2)) # FINRA activity fee (per share sold)
>>>     MAKER_FEE_PER_SHARE = -0.002 # exchange rebate (varies)
>>>     TAKER_FEE_PER_SHARE = 0.00118 # exchange fee (varies)
>>>     MAKER_RATIO = 0.25 # assume 25% of our trades add liquidity, 75% take liquidity
>>>     COMMISSION_PERCENTAGE_FEE_RATE = (0.000175 # NYSE pass-through (% of broker commission)
>>>                                      + 0.00056) # FINRA pass-through (% of broker commission)
>>>     PERCENTAGE_FEE_RATE = 0.0000231 # Transaction fees
>>>     MIN_COMMISSION = 0.35
>>>
>>>  # then, use this on your strategy:
>>>  class MyUSAStrategy(Moonshot):
>>>      COMMISSION_CLASS = CostPlusUSStockCommission

class moonshot.commission.FuturesCommission¶

Base class for futures commissions.

Parameters

BROKER_COMMISSION_PER_CONTRACT (float) – the commission per contract
EXCHANGE_FEE_PER_CONTRACT (float) – the exchange and regulatory fees per contract
CARRYING_FEE_PER_CONTRACT (float) – the overnight carrying fee per contract (depends on equity in excess of margin requirement)

Examples

Example subclass for Globex E-Mini commissions:

>>> class GlobexEquityEMiniFixedCommission(FuturesCommission):
>>>     BROKER_COMMISSION_PER_CONTRACT = 0.85
>>>     EXCHANGE_FEE_PER_CONTRACT = 1.18
>>>     CARRYING_FEE_PER_CONTRACT = 0 # Depends on equity in excess of margin requirement
>>>
>>>  # then, use this on your strategy:
>>>  class MyEminiStrategy(Moonshot):
>>>      COMMISSION_CLASS = GlobexEquityEMiniFixedCommission

moonshot.commission.SpotForexCommission¶: alias of moonshot.commission.fx.SpotFXCommission

Slippage ¶

class moonshot.slippage.FixedSlippage(one_way_slippage=None)¶

Applies a fixed pct slippage to each trade.

This slippage class can be used on strategies indirectly (and more easily) by simply specifying SLIPPAGE_BPS on the strategy.

Parameters: ONE_WAY_SLIPPAGE (float) – the slippage to apply to each trade (default 0.0005 = 5 basis points); overridden if one_way_slippage is passed to __init__

pyfolio

Performance and risk analysis tear sheets

pyfolio.from_moonshot_csv(filepath_or_buffer, **kwargs)¶

Creates a full tear sheet from a moonshot backtest results CSV.

Additional kwargs are passed to pyfolio.create_full_tear_sheet.

Parameters: filepath_or_buffer (str or file-like object) – filepath or file-like object of the CSV
Returns
Return type: None

pyfolio.from_zipline_csv(filepath_or_buffer, **kwargs)¶

Creates a full tear sheet from a zipline backtest results CSV.

Additional kwargs are passed to pyfolio.create_full_tear_sheet.

Parameters: filepath_or_buffer (str or file-like object) – filepath or file-like object of the CSV
Returns
Return type: None

pyfolio.create_capacity_tear_sheet(returns, positions, transactions, market_data, liquidation_daily_vol_limit=0.2, trade_daily_vol_limit=0.05, last_n_days=126, days_to_liquidate_limit=1, estimate_intraday='infer', return_fig=False)¶

Generates a report detailing portfolio size constraints set by least liquid tickers. Plots a “capacity sweep,” a curve describing projected sharpe ratio given the slippage penalties that are applied at various capital bases.

Parameters

returns (pd.Series) –
Daily returns of the strategy, noncumulative.
- See full explanation in pyfolio.create_full_tear_sheet.
positions (pd.DataFrame) –
Daily net position values.
- See full explanation in pyfolio.create_full_tear_sheet.
transactions (pd.DataFrame) –
Prices and amounts of executed trades. One row per trade.
- See full explanation in pyfolio.create_full_tear_sheet.
market_data (pd.DataFrame) –
Daily market_data
- DataFrame has a multi-index index, one level is dates and another is market_data contains volume & price, equities as columns
liquidation_daily_vol_limit (float) – Max proportion of a daily bar that can be consumed in the process of liquidating a position in the “days to liquidation” analysis.
trade_daily_vol_limit (float) – Flag daily transaction totals that exceed proportion of daily bar.
last_n_days (integer) – Compute max position allocation and dollar volume for only the last N days of the backtest
days_to_liquidate_limit (integer) – Display all tickers with greater max days to liquidation.
estimate_intraday (boolean or str, optional) – Approximate returns for intraday strategies. See description in pyfolio.create_full_tear_sheet.
return_fig (boolean, optional) – If True, returns the figure that was plotted on.

pyfolio.create_full_tear_sheet(returns, positions=None, transactions=None, market_data=None, benchmark_rets=None, slippage=None, live_start_date=None, sector_mappings=None, round_trips=False, estimate_intraday='infer', hide_positions=False, cone_std=1.0, 1.5, 2.0, bootstrap=False, unadjusted_returns=None, turnover_denom='AGB', set_context=True, factor_returns=None, factor_loadings=None, pos_in_dollars=True, header_rows=None, factor_partitions={'sector': ['basic_materials', 'consumer_cyclical', 'financial_services', 'real_estate', 'consumer_defensive', 'health_care', 'utilities', 'communication_services', 'energy', 'industrials', 'technology'], 'style': ['momentum', 'size', 'value', 'reversal_short_term', 'volatility']})¶

Generate a number of tear sheets that are useful for analyzing a strategy’s performance.

Fetches benchmarks if needed.
Creates tear sheets for returns, and significant events. If possible, also creates tear sheets for position analysis and transaction analysis.

Parameters

returns (pd.Series) –

Daily returns of the strategy, noncumulative.

Time series with decimal returns.

Example:

2015-07-16    -0.012143
2015-07-17    0.045350
2015-07-20    0.030957
2015-07-21    0.004902

positions (pd.DataFrame, optional) –

Daily net position values.

Time series of dollar amount invested in each position and cash.
Days where stocks are not held can be represented by 0 or NaN.
Non-working capital is labelled ‘cash’

Example:

index         'AAPL'         'MSFT'          cash
2004-01-09    13939.3800     -14012.9930     711.5585
2004-01-12    14492.6300     -14624.8700     27.1821
2004-01-13    -13853.2800    13653.6400      -43.6375

transactions (pd.DataFrame, optional) –

Executed trade volumes and fill prices.

One row per trade.
Trades on different names that occur at the same time will have identical indicies.

Example:

index                  amount   price    symbol
2004-01-09 12:18:01    483      324.12   'AAPL'
2004-01-09 12:18:01    122      83.10    'MSFT'
2004-01-13 14:12:23    -75      340.43   'AAPL'

market_data (pd.DataFrame, optional) –
Daily market_data
- DataFrame has a multi-index index, one level is dates and another is market_data contains volume & price, equities as columns
slippage (int/float, optional) –
Basis points of slippage to apply to returns before generating tearsheet stats and plots. If a value is provided, slippage parameter sweep plots will be generated from the unadjusted returns. Transactions and positions must also be passed.
- See txn.adjust_returns_for_slippage for more details.
live_start_date (datetime, optional) – The point in time when the strategy began live trading, after its backtest period. This datetime should be normalized.
hide_positions (bool, optional) – If True, will not output any symbol names.
round_trips (boolean, optional) – If True, causes the generation of a round trip tear sheet.
sector_mappings (dict or pd.Series, optional) – Security identifier to sector mapping. Security ids as keys, sectors as values.
estimate_intraday (boolean or str, optional) – Instead of using the end-of-day positions, use the point in the day where we have the most $ invested. This will adjust positions to better approximate and represent how an intraday strategy behaves. By default, this is ‘infer’, and an attempt will be made to detect an intraday strategy. Specifying this value will prevent detection.
cone_std (float, or tuple, optional) –
If float, The standard deviation to use for the cone plots. If tuple, Tuple of standard deviation values to use for the cone plots
- The cone is a normal distribution with this standard deviation centered around a linear regression.
bootstrap (boolean (optional)) – Whether to perform bootstrap analysis for the performance metrics. Takes a few minutes longer.
turnover_denom (str) –
Either AGB or portfolio_value, default AGB.
- See full explanation in txn.get_turnover.
factor_returns (pd.Dataframe, optional) – Returns by factor, with date as index and factors as columns
factor_loadings (pd.Dataframe, optional) – Factor loadings for all days in the date range, with date and ticker as index, and factors as columns.
pos_in_dollars (boolean, optional) – indicates whether positions is in dollars
header_rows (dict or OrderedDict, optional) – Extra rows to display at the top of the perf stats table.
set_context (boolean, optional) –
If True, set default plotting style context.
- See plotting.context().
factor_partitions (dict, optional) –
dict specifying how factors should be separated in perf attrib factor returns and risk exposures plots
- See pyfolio.create_perf_attrib_tear_sheet.

pyfolio.create_interesting_times_tear_sheet(returns, benchmark_rets=None, periods=None, legend_loc='best', return_fig=False)¶

Generate a number of returns plots around interesting points in time, like the flash crash and 9/11.

Plots: returns around the dotcom bubble burst, Lehmann Brothers’ failure, 9/11, US downgrade and EU debt crisis, Fukushima meltdown, US housing bubble burst, EZB IR, Great Recession (August 2007, March and September of 2008, Q1 & Q2 2009), flash crash, April and October 2014.

benchmark_rets must be passed, as it is meaningless to analyze performance during interesting times without some benchmark to refer to.

Parameters

returns (pd.Series) –
Daily returns of the strategy, noncumulative.
- See full explanation in pyfolio.create_full_tear_sheet.
benchmark_rets (pd.Series) –
Daily noncumulative returns of the benchmark.
- This is in the same style as returns.
periods (dict or OrderedDict, optional) – historical event dates that may have had significant impact on markets
legend_loc (plt.legend_loc, optional) – The legend’s location.
return_fig (boolean, optional) – If True, returns the figure that was plotted on.

pyfolio.create_perf_attrib_tear_sheet(returns, positions, factor_returns, factor_loadings, transactions=None, pos_in_dollars=True, factor_partitions={'sector': ['basic_materials', 'consumer_cyclical', 'financial_services', 'real_estate', 'consumer_defensive', 'health_care', 'utilities', 'communication_services', 'energy', 'industrials', 'technology'], 'style': ['momentum', 'size', 'value', 'reversal_short_term', 'volatility']}, return_fig=False)¶

Generate plots and tables for analyzing a strategy’s performance.

Parameters

returns (pd.Series) – Returns for each day in the date range.
positions (pd.DataFrame) – Daily holdings (in dollars or percentages), indexed by date. Will be converted to percentages if positions are in dollars. Short positions show up as cash in the ‘cash’ column.
factor_returns (pd.DataFrame) – Returns by factor, with date as index and factors as columns
factor_loadings (pd.DataFrame) – Factor loadings for all days in the date range, with date and ticker as index, and factors as columns.
transactions (pd.DataFrame, optional) –
Prices and amounts of executed trades. One row per trade.
- See full explanation in pyfolio.create_full_tear_sheet.
- Default is None.
pos_in_dollars (boolean, optional) – Flag indicating whether positions are in dollars or percentages If True, positions are in dollars.
factor_partitions (dict) –
dict specifying how factors should be separated in factor returns and risk exposures plots
- Example:
```
{'style': ['momentum', 'size', 'value', ...],
'sector': ['technology', 'materials', ... ]}
```
return_fig (boolean, optional) – If True, returns the figure that was plotted on.

pyfolio.create_position_tear_sheet(returns, positions, show_and_plot_top_pos=2, hide_positions=False, sector_mappings=None, transactions=None, estimate_intraday='infer', return_fig=False)¶

Generate a number of plots for analyzing a strategy’s positions and holdings.

Plots: gross leverage, exposures, top positions, and holdings.
Will also print the top positions held.

Parameters

returns (pd.Series) –
Daily returns of the strategy, noncumulative.
- See full explanation in pyfolio.create_full_tear_sheet.
positions (pd.DataFrame) –
Daily net position values.
- See full explanation in pyfolio.create_full_tear_sheet.
show_and_plot_top_pos (int, optional) – By default, this is 2, and both prints and plots the top 10 positions. If this is 0, it will only plot; if 1, it will only print.
hide_positions (bool, optional) – If True, will not output any symbol names. Overrides show_and_plot_top_pos to 0 to suppress text output.
sector_mappings (dict or pd.Series, optional) – Security identifier to sector mapping. Security ids as keys, sectors as values.
transactions (pd.DataFrame, optional) –
Prices and amounts of executed trades. One row per trade.
- See full explanation in pyfolio.create_full_tear_sheet.
estimate_intraday (boolean or str, optional) – Approximate returns for intraday strategies. See description in pyfolio.create_full_tear_sheet.
return_fig (boolean, optional) – If True, returns the figure that was plotted on.

pyfolio.create_returns_tear_sheet(returns, positions=None, transactions=None, live_start_date=None, cone_std=1.0, 1.5, 2.0, benchmark_rets=None, bootstrap=False, turnover_denom='AGB', header_rows=None, return_fig=False)¶

Generate a number of plots for analyzing a strategy’s returns.

Fetches benchmarks, then creates the plots on a single figure.
Plots: rolling returns (with cone), rolling beta, rolling sharpe, rolling Fama-French risk factors, drawdowns, underwater plot, monthly and annual return plots, daily similarity plots, and return quantile box plot.
Will also print the start and end dates of the strategy, performance statistics, drawdown periods, and the return range.

Parameters

returns (pd.Series) –
Daily returns of the strategy, noncumulative.
- See full explanation in pyfolio.create_full_tear_sheet.
positions (pd.DataFrame, optional) –
Daily net position values.
- See full explanation in pyfolio.create_full_tear_sheet.
transactions (pd.DataFrame, optional) –
Executed trade volumes and fill prices.
- See full explanation in pyfolio.create_full_tear_sheet.
live_start_date (datetime, optional) – The point in time when the strategy began live trading, after its backtest period.
cone_std (float, or tuple, optional) –
If float, The standard deviation to use for the cone plots. If tuple, Tuple of standard deviation values to use for the cone plots
- The cone is a normal distribution with this standard deviation centered around a linear regression.
benchmark_rets (pd.Series, optional) –
Daily noncumulative returns of the benchmark.
- This is in the same style as returns.
bootstrap (boolean, optional) – Whether to perform bootstrap analysis for the performance metrics. Takes a few minutes longer.
turnover_denom (str, optional) –
Either AGB or portfolio_value, default AGB.
- See full explanation in txn.get_turnover.
header_rows (dict or OrderedDict, optional) – Extra rows to display at the top of the perf stats table.
return_fig (boolean, optional) – If True, returns the figure that was plotted on.

pyfolio.create_round_trip_tear_sheet(returns, positions, transactions, sector_mappings=None, estimate_intraday='infer', return_fig=False)¶

Generate a number of figures and plots describing the duration, frequency, and profitability of trade “round trips.” A round trip is started when a new long or short position is opened and is only completed when the number of shares in that position returns to or crosses zero.

Parameters

returns (pd.Series) –
Daily returns of the strategy, noncumulative.
- See full explanation in pyfolio.create_full_tear_sheet.
positions (pd.DataFrame) –
Daily net position values.
- See full explanation in pyfolio.create_full_tear_sheet.
transactions (pd.DataFrame) –
Prices and amounts of executed trades. One row per trade.
- See full explanation in pyfolio.create_full_tear_sheet.
sector_mappings (dict or pd.Series, optional) – Security identifier to sector mapping. Security ids as keys, sectors as values.
estimate_intraday (boolean or str, optional) – Approximate returns for intraday strategies. See description in pyfolio.create_full_tear_sheet.
return_fig (boolean, optional) – If True, returns the figure that was plotted on.

pyfolio.create_simple_tear_sheet(returns, positions=None, transactions=None, benchmark_rets=None, slippage=None, estimate_intraday='infer', live_start_date=None, turnover_denom='AGB', header_rows=None)¶

Simpler version of pyfolio.create_full_tear_sheet; generates summary performance statistics and important plots as a single image.

Plots: cumulative returns, rolling beta, rolling Sharpe, underwater, exposure, top 10 holdings, total holdings, long/short holdings, daily turnover, transaction time distribution.
Never accept market_data input (market_data = None)
Never accept sector_mappings input (sector_mappings = None)
Never perform bootstrap analysis (bootstrap = False)
Never hide posistions on top 10 holdings plot (hide_positions = False)
Always use default cone_std (cone_std = (1.0, 1.5, 2.0))

Parameters

returns (pd.Series) –

Daily returns of the strategy, noncumulative.

Time series with decimal returns.

Example:

2015-07-16    -0.012143
2015-07-17    0.045350
2015-07-20    0.030957
2015-07-21    0.004902

positions (pd.DataFrame, optional) –

Daily net position values.

Time series of dollar amount invested in each position and cash.
Days where stocks are not held can be represented by 0 or NaN.
Non-working capital is labelled ‘cash’

Example:

index         'AAPL'         'MSFT'          cash
2004-01-09    13939.3800     -14012.9930     711.5585
2004-01-12    14492.6300     -14624.8700     27.1821
2004-01-13    -13853.2800    13653.6400      -43.6375

transactions (pd.DataFrame, optional) –

Executed trade volumes and fill prices.

One row per trade.
Trades on different names that occur at the same time will have identical indicies.

Example:

index                  amount   price    symbol
2004-01-09 12:18:01    483      324.12   'AAPL'
2004-01-09 12:18:01    122      83.10    'MSFT'
2004-01-13 14:12:23    -75      340.43   'AAPL'

benchmark_rets (pd.Series, optional) – Daily returns of the benchmark, noncumulative.
slippage (int/float, optional) –
Basis points of slippage to apply to returns before generating tearsheet stats and plots. If a value is provided, slippage parameter sweep plots will be generated from the unadjusted returns. Transactions and positions must also be passed.
- See txn.adjust_returns_for_slippage for more details.
live_start_date (datetime, optional) – The point in time when the strategy began live trading, after its backtest period. This datetime should be normalized.
turnover_denom (str, optional) –
Either AGB or portfolio_value, default AGB.
- See full explanation in txn.get_turnover.
header_rows (dict or OrderedDict, optional) – Extra rows to display at the top of the perf stats table.
set_context (boolean, optional) – If True, set default plotting style context.

pyfolio.create_txn_tear_sheet(returns, positions, transactions, turnover_denom='AGB', unadjusted_returns=None, estimate_intraday='infer', return_fig=False)¶

Generate a number of plots for analyzing a strategy’s transactions.

Plots: turnover, daily volume, and a histogram of daily volume.

Parameters

returns (pd.Series) –
Daily returns of the strategy, noncumulative.
- See full explanation in pyfolio.create_full_tear_sheet.
positions (pd.DataFrame) –
Daily net position values.
- See full explanation in pyfolio.create_full_tear_sheet.
transactions (pd.DataFrame) –
Prices and amounts of executed trades. One row per trade.
- See full explanation in pyfolio.create_full_tear_sheet.
turnover_denom (str, optional) –
Either AGB or portfolio_value, default AGB.
- See full explanation in txn.get_turnover.
unadjusted_returns (pd.Series, optional) –
Daily unadjusted returns of the strategy, noncumulative. Will plot additional swippage sweep analysis.
- See pyfolio.plotting.plot_swippage_sleep and pyfolio.plotting.plot_slippage_sensitivity
estimate_intraday (boolean or str, optional) – Approximate returns for intraday strategies. See description in pyfolio.create_full_tear_sheet.
return_fig (boolean, optional) – If True, returns the figure that was plotted on.

quantrocket.get_prices

quantrocket.get_prices(codes, start_date=None, end_date=None, universes=None, sids=None, exclude_universes=None, exclude_sids=None, times=None, fields=None, timezone=None, infer_timezone=None, cont_fut=None)

Query one or more history databases, real-time aggregate databases, and/or Zipline bundles and load prices into a DataFrame.

For bar sizes smaller than 1-day, the resulting DataFrame will have a MultiIndex with levels (Field, Date, Time). For bar sizes of 1-day or larger, the MultiIndex will have levels (Field, Date).

Parameters

codes (str or list of str, required) – the code(s) of one or more databases to query. If multiple databases are specified, they must have the same bar size. List databses in order of priority (highest priority first). If multiple databases provide the same field for the same sid on the same datetime, the first database’s value will be used.
start_date (str (YYYY-MM-DD), optional) – limit to data on or after this date
end_date (str (YYYY-MM-DD), optional) – limit to data on or before this date
universes (list of str, optional) – limit to these universes (default is to return all securities in database)
sids (list of str, optional) – limit to these sids
exclude_universes (list of str, optional) – exclude these universes
exclude_sids (list of str, optional) – exclude these sids
times (list of str (HH:MM:SS), optional) – limit to these times, specified in the timezone of the relevant exchange. See additional information in the Notes section regarding the timezone to use.
fields (list of str, optional) – only return these fields. (If querying multiple databases that have different fields, provide the complete list of desired fields; only the supported fields for each database will be queried.)
timezone (str, optional) – convert timestamps to this timezone, for example America/New_York (see pytz.all_timezones for choices); ignored for non-intraday bar sizes
infer_timezone (bool) – infer the timezone from the securities master Timezone field; defaults to True if using intraday bars and no timezone specified; ignored for non-intraday bars, or if timezone is passed
cont_fut (str) – stitch futures into continuous contracts using this method (default is not to stitch together). Only applicable to history databases. Possible choices: concat

Returns

a MultiIndex

Return type

DataFrame

Notes

The times parameter, if provided, is applied differently for history databases and Zipline bundles vs real-time aggregate databases. For history databases and Zipline bundles, the parameter is applied when querying the database. For real-time aggregate databases, the parameter is not applied when querying the database; rather, all available times are retrieved and the times filter is applied to the resulting DataFrame after casting it to the appropriate timezone (as inferred from the securities master Timezone field or as explicitly specified with the timezone parameter). The rationale for this behavior is that history databases and Zipline bundles store intraday data in the timezone of the relevant exchange whereas real-time aggregate databases store data in UTC. By applying the times filter as described, users can specify the times in the timezone of the relevant exchange for both types of databases.

Examples

Load intraday prices:

>>> prices = get_prices('stk-sample-5min', fields=["Close", "Volume"])
>>> prices.head()
                            Sid             FIBBG1  FIBBG2
Field       Date            Time
Close       2017-07-26      09:30:00        153.62  2715.0
                            09:35:00        153.46  2730.0
                            09:40:00        153.21  2725.0
                            09:45:00        153.28  2725.0
                            09:50:00        153.18  2725.0

Isolate the closes:

>>> closes = prices.loc["Close"]
>>> closes.head()
            Sid             FIBBG1  FIBBG2
Date        Time
2017-07-26  09:30:00        153.62  2715.0
            09:35:00        153.46  2730.0
            09:40:00        153.21  2725.0
            09:45:00        153.28  2725.0
            09:50:00        153.18  2725.0

Isolate the 15:45:00 prices:

>>> session_closes = closes.xs("15:45:00", level="Time")
>>> session_closes.head()
    Sid     FIBBG1  FIBBG2
Date
2017-07-26  153.29  2700.00
2017-07-27  150.10  2660.00
2017-07-28  149.43  2650.02
2017-07-31  148.99  2650.34
2017-08-01  149.72  2675.50

quantrocket_trading_calendars

Trading calendars for QuantRocket-supported exchanges. This is a wrapper around the trading_calendars package from Quantopian. See also the usage guide.

quantrocket_trading_calendars.get_calendar(name)¶

Retrieves an instance of an TradingCalendar whose name is given.

Parameters: name (str) – The name of the TradingCalendar to be retrieved.
Returns: calendar – The desired calendar.
Return type: calendars.TradingCalendar

class trading_calendars.TradingCalendar(start=Timestamp('1990-01-01 00:00:00+0000', tz='UTC'), end=Timestamp('2021-10-05 15:18:48.365888+0000', tz='UTC'))¶

An TradingCalendar represents the timing information of a single market exchange.

The timing information is made up of two parts: sessions, and opens/closes.

A session represents a contiguous set of minutes, and has a label that is midnight UTC. It is important to note that a session label should not be considered a specific point in time, and that midnight UTC is just being used for convenience.

For each session, we store the open and close time in UTC time.

abstract property open_times¶: Returns a list of tuples of (start_date, open_time). If the open time is constant throughout the calendar, use None for the start_date.

abstract property close_times¶: Returns a list of tuples of (start_date, close_time). If the close time is constant throughout the calendar, use None for the start_date.

property weekmask¶

String indicating the days of the week on which the market is open.

Default is ‘1111100’ (i.e., Monday-Friday).

See also

numpy.busdaycalendar

minutes_count_for_sessions_in_range(start_session, end_session)¶

Parameters

start_session (pd.Timestamp) – The first session.
end_session (pd.Timestamp) – The last session.

Returns

int – between start_session and end_session, inclusive.

Return type

The total number of minutes for the contiguous chunk of sessions.

property regular_holidays¶: returns: * pd.AbstractHolidayCalendar (a calendar containing the regular holidays) * for this calendar

property adhoc_holidays¶: returns: list :rtype: A list of timestamps representing unplanned closes.

property special_opens¶

A list of special open times and corresponding HolidayCalendars.

Returns: list
Return type: List of (time, AbstractHolidayCalendar) tuples

property special_opens_adhoc¶: returns: list – closes that cannot be codified into rules. :rtype: List of (time, DatetimeIndex) tuples that represent special

property special_closes¶

A list of special close times and corresponding HolidayCalendars.

Returns: list
Return type: List of (time, AbstractHolidayCalendar) tuples

property special_closes_adhoc¶: returns: list – closes that cannot be codified into rules. :rtype: List of (time, DatetimeIndex) tuples that represent special

is_session(dt)¶

Given a dt, returns whether it’s a valid session label.

Parameters: dt (pd.Timestamp) – The dt that is being tested.
Returns: Whether the given dt is a valid session label.
Return type: bool

is_open_on_minute(dt)¶

Given a dt, return whether this exchange is open at the given dt.

Parameters: dt (pd.Timestamp) – The dt for which to check if this exchange is open.
Returns: Whether the exchange is open on this dt.
Return type: bool

next_open(dt)¶

Given a dt, returns the next open.

If the given dt happens to be a session open, the next session’s open will be returned.

Parameters: dt (pd.Timestamp) – The dt for which to get the next open.
Returns: The UTC timestamp of the next open.
Return type: pd.Timestamp

next_close(dt)¶

Given a dt, returns the next close.

Parameters: dt (pd.Timestamp) – The dt for which to get the next close.
Returns: The UTC timestamp of the next close.
Return type: pd.Timestamp

previous_open(dt)¶

Given a dt, returns the previous open.

Parameters: dt (pd.Timestamp) – The dt for which to get the previous open.
Returns: The UTC imestamp of the previous open.
Return type: pd.Timestamp

previous_close(dt)¶

Given a dt, returns the previous close.

Parameters: dt (pd.Timestamp) – The dt for which to get the previous close.
Returns: The UTC timestamp of the previous close.
Return type: pd.Timestamp

next_minute(dt)¶

Given a dt, return the next exchange minute. If the given dt is not an exchange minute, returns the next exchange open.

Parameters: dt (pd.Timestamp) – The dt for which to get the next exchange minute.
Returns: The next exchange minute.
Return type: pd.Timestamp

previous_minute(dt)¶

Given a dt, return the previous exchange minute.

Raises KeyError if the given timestamp is not an exchange minute.

Parameters: dt (pd.Timestamp) – The dt for which to get the previous exchange minute.
Returns: The previous exchange minute.
Return type: pd.Timestamp

next_session_label(session_label)¶

Given a session label, returns the label of the next session.

Parameters: session_label (pd.Timestamp) – A session whose next session is desired.
Returns: The next session label (midnight UTC).
Return type: pd.Timestamp

Notes

Raises ValueError if the given session is the last session in this calendar.

previous_session_label(session_label)¶

Given a session label, returns the label of the previous session.

Parameters: session_label (pd.Timestamp) – A session whose previous session is desired.
Returns: The previous session label (midnight UTC).
Return type: pd.Timestamp

Notes

Raises ValueError if the given session is the first session in this calendar.

minutes_for_session(session_label)¶

Given a session label, return the minutes for that session.

Parameters: session_label (pd.Timestamp (midnight UTC)) – A session label whose session’s minutes are desired.
Returns: All the minutes for the given session.
Return type: pd.DateTimeIndex

execution_minutes_for_session(session_label)¶

Given a session label, return the execution minutes for that session.

Parameters: session_label (pd.Timestamp (midnight UTC)) – A session label whose session’s minutes are desired.
Returns: All the execution minutes for the given session.
Return type: pd.DateTimeIndex

sessions_in_range(start_session_label, end_session_label)¶

Given start and end session labels, return all the sessions in that range, inclusive.

Parameters

start_session_label (pd.Timestamp (midnight UTC)) – The label representing the first session of the desired range.
end_session_label (pd.Timestamp (midnight UTC)) – The label representing the last session of the desired range.

Returns

The desired sessions.

Return type

pd.DatetimeIndex

sessions_window(session_label, count)¶

Given a session label and a window size, returns a list of sessions of size count + 1, that either starts with the given session (if count is positive) or ends with the given session (if count is negative).

Parameters

session_label (pd.Timestamp) – The label of the initial session.
count (int) – Defines the length and the direction of the window.

Returns

The desired sessions.

Return type

pd.DatetimeIndex

session_distance(start_session_label, end_session_label)¶

Given a start and end session label, returns the distance between them. For example, for three consecutive sessions Mon., Tues., and Wed, session_distance(Mon, Wed) returns 3. If start_session is after end_session, the value will be negated.

Parameters

start_session_label (pd.Timestamp) – The label of the start session.
end_session_label (pd.Timestamp) – The label of the ending session inclusive.

Returns

The distance between the two sessions.

Return type

int

minutes_in_range(start_minute, end_minute)¶

Given start and end minutes, return all the calendar minutes in that range, inclusive.

Given minutes don’t need to be calendar minutes.

Parameters

start_minute (pd.Timestamp) – The minute representing the start of the desired range.
end_minute (pd.Timestamp) – The minute representing the end of the desired range.

Returns

The minutes in the desired range.

Return type

pd.DatetimeIndex

minutes_for_sessions_in_range(start_session_label, end_session_label)¶

Returns all the minutes for all the sessions from the given start session label to the given end session label, inclusive.

Parameters

start_session_label (pd.Timestamp) – The label of the first session in the range.
end_session_label (pd.Timestamp) – The label of the last session in the range.

Returns

The minutes in the desired range.

Return type

pd.DatetimeIndex

open_and_close_for_session(session_label)¶

Returns a tuple of timestamps of the open and close of the session represented by the given label.

Parameters: session_label (pd.Timestamp) – The session whose open and close are desired.
Returns: The open and close for the given session.
Return type: (Timestamp, Timestamp)

minute_to_session_label(dt, direction='next')¶

Given a minute, get the label of its containing session.

Parameters

dt (pd.Timestamp or nanosecond offset) – The dt for which to get the containing session.
direction (str) –
“next” (default) means that if the given dt is not part of a session, return the label of the next session.

”previous” means that if the given dt is not part of a session, return the label of the previous session.

”none” means that a KeyError will be raised if the given dt is not part of a session.

Returns

The label of the containing session.

Return type

pd.Timestamp (midnight UTC)

minute_index_to_session_labels(index)¶

Given a sorted DatetimeIndex of market minutes, return a DatetimeIndex of the corresponding session labels.

Parameters: index (pd.DatetimeIndex or pd.Series) – The ordered list of market minutes we want session labels for.
Returns: The list of session labels corresponding to the given minutes.
Return type: pd.DatetimeIndex (UTC)

zipline

This API is for writing Zipline strategies. For backtesting and live trading of Zipline strategies, as well as managing data bundles, see the quantrocket.zipline API.

Contents

Research API ¶

These functions are available outside the context of a running algorithm, including in research notebooks.

Data Object in Research ¶

zipline.research.get_data(dt, bundle=None, data_frequency=None)¶

Return a zipline.protocol.BarData object for the specified bundle (or default bundle) as of the specified datetime. This is the same object that is passed as the data parameter to handle_data and other backtest functions.

Parameters

dt (str (YYYY-MM-DD[ HH:MM:SS]), required) – The datetime (for minute data) or date (for daily data) which the data object should be anchored to.
bundle (str, optional) – the bundle code. If omitted, the default bundle will be used (and must be set).
data_frequency (str, optional) – the data frequency. Possible choices: daily, minute. The default is “daily” for daily bundles and “minute” for minute bundles. Minute bundles also support “daily”.

Returns

data

Return type

zipline.protocol.BarData

Examples

Get the data object for July 7, 2020 at 11 AM for the usstock minute bundle:

>>> data = get_data('2020-07-07 11:00:00', bundle="usstock-1min")

Get the data object for July 7, 2020 for a daily bundle:

>>> data = get_data('2020-07-07', bundle="xjpx-1d-bundle")

Pipeline in Research ¶

zipline.research.run_pipeline(pipeline, start_date, end_date=None, bundle=None)¶

Compute values for pipeline from start_date to end_date, using the specified bundle or the default bundle.

Parameters

pipeline (Pipeline, required) – The pipeline to run.
start_date (str (YYYY-MM-DD), required) – First date on which the pipeline should run. If start_date is not a trading day, the pipeline will start on the first trading day after start_date.
end_date (str (YYYY-MM-DD), optional) – Last date on which the pipeline should run. If end_date is not a trading day, the pipeline will end on the first trading day after end_date. Defaults to today.
bundle (str, optional) – the bundle code. If omitted, the default bundle will be used (and must be set).

Returns

result – A frame of computed results. The result columns correspond to the entries of pipeline.columns, which should be a dictionary mapping strings to instances of zipline.pipeline.term.Term. For each date between start_date and end_date, result will contain a row for each asset that passed pipeline.screen. A screen of None indicates that a row should be returned for each asset that existed each day.

Return type

pd.DataFrame

Examples

Get a pipeline of 1-year returns:

>>> from zipline.pipeline.factors import Returns
>>> pipeline = Pipeline(
        columns={
            '1Y': Returns(window_length=252),
        })
>>> factor = run_pipeline(pipeline, '2018-01-01', '2019-02-01', bundle="usstock-1min")

zipline.research.get_forward_returns(factor, periods=None, bundle=None)¶

Get forward returns for the dates and assets in factor, calculated over the given periods.

Parameters

factor (pd.Series) – The factor whose dates and assets to use. The Series should have a MultiIndex of (date, asset), as returned by run_pipeline.
periods (int or list of int) – The periods over which to calculate the forward returns. Example: [1, 5, 10]. Defaults to [1].
bundle (str, optional) – the bundle code. If omitted, the default bundle will be used (and must be set).

Returns

result – A dataframe of computed forward returns containing one column per requested period. It is indexed first by date, then by asset.

Return type

pd.DataFrame

Examples

Run a pipeline, then get forward returns for the factor:

>>> factor = run_pipeline(pipeline, '2018-01-01', '2019-02-01', bundle="usstock-1min")
>>> forward_returns = get_forward_returns(factor, bundle="usstock-1min")

Assets in Research ¶

zipline.research.sid(sid, bundle=None)¶

Return an Asset object for the specified sid in the specified bundle (or default bundle).

Parameters

sid (str, required) – The sid to retrieve.
bundle (str, optional) – the bundle code. If omitted, the default bundle will be used (and must be set).

Returns

asset

Return type

zipline.assets.Asset

Notes

Each asset is specific to the bundle from which it came. An Asset object for AAPL from bundle A cannot be used to retrieve AAPL data from bundle B, even if AAPL data is present in bundle B.

Examples

Get the asset object for AAPL:

>>> aapl = sid("FIBBG000B9XRY4", bundle="usstock-1min")

Algorithm API ¶

These functions are available inside a running algorithm, including in the initialize, handle_data, and before_trading_start functions.

In all listed functions, the self argument is implicitly the currently-executing TradingAlgorithm instance.

Data Object ¶

class zipline.protocol.BarData¶

Provides methods for accessing minutely and daily price/volume data from Algorithm API functions.

Also provides utility methods to determine if an asset is alive, and if it has recent trade data.

An instance of this object is passed as data to handle_data() and before_trading_start().

can_trade(assets)¶

For the given asset or iterable of assets, returns True if all of the following are true:

The asset is alive for the session of the current simulation time (if current simulation time is not a market minute, we use the next session).
The asset’s exchange is open at the current simulation time or at the simulation calendar’s next market minute.
There is a known last price for the asset.

Parameters: assets (zipline.assets.Asset or iterable of zipline.assets.Asset) – Asset(s) for which tradability should be determined.

Notes

The second condition above warrants some further explanation:

If the asset’s exchange calendar is identical to the simulation calendar, then this condition always returns True.
If there are market minutes in the simulation calendar outside of this asset’s exchange’s trading hours (for example, if the simulation is running on the CMES calendar but the asset is MSFT, which trades on the NYSE), during those minutes, this condition will return False (for example, 3:15 am Eastern on a weekday, during which the CMES is open but the NYSE is closed).

Returns: can_trade – Bool or series of bools indicating whether the requested asset(s) can be traded in the current minute.
Return type: bool or pd.Series[bool]

current(assets, fields)¶

Returns the “current” value of the given fields for the given assets at the current simulation time.

Parameters

assets (zipline.assets.Asset or iterable of zipline.assets.Asset) – The asset(s) for which data is requested.
fields (str or iterable[str]) – Requested data field(s). Valid field names are: “price”, “last_traded”, “open”, “high”, “low”, “close”, and “volume”.

Returns

current_value – See notes below.

Return type

Scalar, pandas Series, or pandas DataFrame.

Notes

The return type of this function depends on the types of its inputs:

If a single asset and a single field are requested, the returned value is a scalar (either a float or a pd.Timestamp depending on the field).
If a single asset and a list of fields are requested, the returned value is a pd.Series whose indices are the requested fields.
If a list of assets and a single field are requested, the returned value is a pd.Series whose indices are the assets.
If a list of assets and a list of fields are requested, the returned value is a pd.DataFrame. The columns of the returned frame will be the requested fields, and the index of the frame will be the requested assets.

The values produced for fields are as follows:

Requesting “price” produces the last known close price for the asset, forward-filled from an earlier minute if there is no trade this minute. If there is no last known value (either because the asset has never traded, or because it has delisted) NaN is returned. If a value is found, and we had to cross an adjustment boundary (split, dividend, etc) to get it, the value is adjusted to the current simulation time before being returned.
Requesting “open”, “high”, “low”, or “close” produces the open, high, low, or close for the current minute. If no trades occurred this minute, NaN is returned.
Requesting “volume” produces the trade volume for the current minute. If no trades occurred this minute, 0 is returned.
Requesting “last_traded” produces the datetime of the last minute in which the asset traded, even if the asset has stopped trading. If there is no last known value, pd.NaT is returned.

If the current simulation time is not a valid market time for an asset, we use the most recent market close instead.

Examples

Get the latest price for AAPL (returns a scalar):

>>> aapl = algo.sid("FIBBG000B9XRY4")
>>> current_price = data.current(aapl, "price")

history(assets, fields, bar_count, frequency)¶

Returns a trailing window of length bar_count containing data for the given assets, fields, and frequency.

Returned data is adjusted for splits, dividends, and mergers as of the current simulation time.

The semantics for missing data are identical to the ones described in the notes for current().

Parameters

assets (zipline.assets.Asset or iterable of zipline.assets.Asset) – The asset(s) for which data is requested.
fields (string or iterable of string.) – Requested data field(s). Valid field names are: “price”, “last_traded”, “open”, “high”, “low”, “close”, and “volume”.
bar_count (int) – Number of data observations requested.
frequency (str) – String indicating whether to load daily or minutely data observations. Pass ‘1m’ for minutely data, ‘1d’ for daily data.

Returns

history – See notes below.

Return type

pd.Series or pd.DataFrame or pd.Panel

Notes

The return type of this function depends on the types of assets and fields:

If a single asset and a single field are requested, the returned value is a pd.Series of length bar_count whose index is pd.DatetimeIndex.
If a single asset and multiple fields are requested, the returned value is a pd.DataFrame with shape (bar_count, len(fields)). The frame’s index will be a pd.DatetimeIndex, and its columns will be fields.
If multiple assets and a single field are requested, the returned value is a pd.DataFrame with shape (bar_count, len(assets)). The frame’s index will be a pd.DatetimeIndex, and its columns will be assets.
If multiple assets and multiple fields are requested, the returned value is a pd.Panel with shape (len(fields), bar_count, len(assets)). The axes of the returned panel will be:
- panel.items : fields
- panel.major_axis : pd.DatetimeIndex of length bar_count
- panel.minor_axis : assets

If the current simulation time is not a valid market time, we use the last market close instead.

Examples

Get prices for the past 30 minutes for multiple assets (returns a DataFrame):

>>> minute_closes = data.history(assets, "close", 30, "1m")

Get the previous session’s closing price for a single asset:

>>> spy = algo.sid("FIBBG000BDTBL9")
>>> spy_prior_close = data.history(spy, "close", 2, "1d").iloc[0]

is_stale(assets)¶

For the given asset or iterable of assets, returns True if the asset is alive and there is no trade data for the current simulation time.

If the asset has never traded, returns False.

If the current simulation time is not a valid market time, we use the current time to check if the asset is alive, but we use the last market minute/day for the trade data check.

Parameters: assets (zipline.assets.Asset or iterable of zipline.assets.Asset) – Asset(s) for which staleness should be determined.
Returns: is_stale – Bool or series of bools indicating whether the requested asset(s) are stale.
Return type: bool or pd.Series[bool]

Scheduling Functions ¶

zipline.api.schedule_function(self, func, date_rule=None, time_rule=None, half_days=True, calendar=None)¶

Schedule a function to be called repeatedly in the future.

Parameters

func (callable) – The function to execute when the rule is triggered. func should have the same signature as handle_data.
date_rule (zipline.utils.events.EventRule, optional) – Rule for the dates on which to execute func. If not passed, the function will run every trading day.
time_rule (zipline.utils.events.EventRule, optional) – Rule for the time at which to execute func. If not passed, the function will execute at the end of the first market minute of the day.
half_days (bool, optional) – Should this rule fire on half days? Default is True.
calendar (Sentinel, optional) – Calendar used to compute rules that depend on the trading calendar.

Examples

Schedule a function called rebalance to run every trading day 30 minutes after the open:

>>> import zipline.api as algo
>>> algo.schedule_function(
        rebalance,
        algo.date_rules.every_day(),
        algo.time_rules.market_open(minutes=30))

class zipline.api.date_rules¶

Factories for date-based schedule_function() rules.

See also

schedule_function()

static every_day()¶

Create a rule that triggers every day.

Returns: rule
Return type: zipline.utils.events.EventRule

static month_start(days_offset=0)¶

Create a rule that triggers a fixed number of trading days after the start of each month.

Parameters: days_offset (int, optional) – Number of trading days to wait before triggering each month. Default is 0, i.e., trigger on the first trading day of the month.
Returns: rule
Return type: zipline.utils.events.EventRule

static month_end(days_offset=0)¶

Create a rule that triggers a fixed number of trading days before the end of each month.

Parameters: days_offset (int, optional) – Number of trading days prior to month end to trigger. Default is 0, i.e., trigger on the last day of the month.
Returns: rule
Return type: zipline.utils.events.EventRule

static week_start(days_offset=0)¶

Create a rule that triggers a fixed number of trading days after the start of each week.

Parameters: days_offset (int, optional) – Number of trading days to wait before triggering each week. Default is 0, i.e., trigger on the first trading day of the week.

static week_end(days_offset=0)¶

Create a rule that triggers a fixed number of trading days before the end of each week.

Parameters: days_offset (int, optional) – Number of trading days prior to week end to trigger. Default is 0, i.e., trigger on the last trading day of the week.

class zipline.api.time_rules¶

Factories for time-based schedule_function() rules.

See also

schedule_function()

static market_open(offset=None, hours=None, minutes=None)¶

Create a rule that triggers at a fixed offset from market open.

The offset can be specified either as a datetime.timedelta, or as a number of hours and minutes.

Parameters

offset (datetime.timedelta, optional) – If passed, the offset from market open at which to trigger. Must be at least 1 minute.
hours (int, optional) – If passed, number of hours to wait after market open.
minutes (int, optional) – If passed, number of minutes to wait after market open.

Returns

rule

Return type

zipline.utils.events.EventRule

Notes

If no arguments are passed, the default offset is one minute after market open.

If offset is passed, hours and minutes must not be passed. Conversely, if either hours or minutes are passed, offset must not be passed.

static market_close(offset=None, hours=None, minutes=None)¶

Create a rule that triggers at a fixed offset from market close.

The offset can be specified either as a datetime.timedelta, or as a number of hours and minutes.

Parameters

offset (datetime.timedelta, optional) – If passed, the offset from market close at which to trigger. Must be at least 1 minute.
hours (int, optional) – If passed, number of hours to wait before market close.
minutes (int, optional) – If passed, number of minutes to wait before market close.

Returns

rule

Return type

zipline.utils.events.EventRule

Notes

If no arguments are passed, the default offset is one minute before market close.

If offset is passed, hours and minutes must not be passed. Conversely, if either hours or minutes are passed, offset must not be passed.

every_minute¶: alias of Always

Simulation Date ¶

zipline.api.get_datetime(self, tz=None)¶

Returns the current simulation datetime.

Parameters: tz (tzinfo or str, optional) – The timezone to return the datetime in. This defaults to utc.
Returns: dt – The current simulation datetime converted to tz.
Return type: datetime

Orders and Execution Styles ¶

Ordering ¶

zipline.api.order(self, asset, amount, limit_price=None, stop_price=None, style=None)¶

Place an order for a fixed number of shares.

Parameters

asset (Asset) – The asset to be ordered.
amount (int) – The amount of shares to order. If amount is positive, this is the number of shares to buy or cover. If amount is negative, this is the number of shares to sell or short.
limit_price (float, optional) – The limit price for the order.
stop_price (float, optional) – The stop price for the order.
style (ExecutionStyle, optional) – The execution style for the order.

Returns

order_id – The unique identifier for this order, or None if no order was placed.

Return type

str or None

Notes

The limit_price and stop_price arguments provide shorthands for passing common execution styles. Passing limit_price=N is equivalent to style=LimitOrder(N). Similarly, passing stop_price=M is equivalent to style=StopOrder(M), and passing limit_price=N and stop_price=M is equivalent to style=StopLimitOrder(N, M). It is an error to pass both a style and limit_price or stop_price.

See also

zipline.finance.execution.ExecutionStyle, zipline.api.order_value(), zipline.api.order_percent()

zipline.api.order_value(self, asset, value, limit_price=None, stop_price=None, style=None)¶

Place an order for a fixed amount of money.

Equivalent to order(asset, value / data.current(asset, 'price')).

Parameters

asset (Asset) – The asset to be ordered.
value (float) – Amount of value of asset to be transacted. The number of shares bought or sold will be equal to value / current_price.
limit_price (float, optional) – Limit price for the order.
stop_price (float, optional) – Stop price for the order.
style (ExecutionStyle) – The execution style for the order.

Returns

order_id – The unique identifier for this order.

Return type

str

Notes

See zipline.api.order() for more information about limit_price, stop_price, and style

See also

zipline.finance.execution.ExecutionStyle, zipline.api.order(), zipline.api.order_percent()

zipline.api.order_percent(self, asset, percent, limit_price=None, stop_price=None, style=None)¶

Place an order in the specified asset corresponding to the given percent of the current portfolio value.

Parameters

asset (Asset) – The asset that this order is for.
percent (float) – The percentage of the portfolio value to allocate to asset. This is specified as a decimal, for example: 0.50 means 50%.
limit_price (float, optional) – The limit price for the order.
stop_price (float, optional) – The stop price for the order.
style (ExecutionStyle) – The execution style for the order.

Returns

order_id – The unique identifier for this order.

Return type

str

Notes

See zipline.api.order() for more information about limit_price, stop_price, and style

See also

zipline.finance.execution.ExecutionStyle, zipline.api.order(), zipline.api.order_value()

zipline.api.order_target(self, asset, target, limit_price=None, stop_price=None, style=None)¶

Place an order to adjust a position to a target number of shares. If the position doesn’t already exist, this is equivalent to placing a new order. If the position does exist, this is equivalent to placing an order for the difference between the target number of shares and the current number of shares.

Parameters

asset (Asset) – The asset that this order is for.
target (int) – The desired number of shares of asset.
limit_price (float, optional) – The limit price for the order.
stop_price (float, optional) – The stop price for the order.
style (ExecutionStyle) – The execution style for the order.

Returns

order_id – The unique identifier for this order.

Return type

str

Notes

order_target does not take into account any open orders. For example:

order_target(asset, 10)
order_target(asset, 10)

This code will result in 20 shares of asset because the first call to order_target will not have been filled when the second order_target call is made.

See zipline.api.order() for more information about limit_price, stop_price, and style

See also

zipline.finance.execution.ExecutionStyle, zipline.api.order(), zipline.api.order_target_percent(), zipline.api.order_target_value()

zipline.api.order_target_value(self, asset, target, limit_price=None, stop_price=None, style=None)¶

Place an order to adjust a position to a target value. If the position doesn’t already exist, this is equivalent to placing a new order. If the position does exist, this is equivalent to placing an order for the difference between the target value and the current value. If the Asset being ordered is a Future, the ‘target value’ calculated is actually the target exposure, as Futures have no ‘value’.

Parameters

asset (Asset) – The asset that this order is for.
target (float) – The desired total value of asset.
limit_price (float, optional) – The limit price for the order.
stop_price (float, optional) – The stop price for the order.
style (ExecutionStyle) – The execution style for the order.

Returns

order_id – The unique identifier for this order.

Return type

str

Notes

order_target_value does not take into account any open orders. For example:

order_target_value(asset, 10)
order_target_value(asset, 10)

This code will result in 20 dollars of asset because the first call to order_target_value will not have been filled when the second order_target_value call is made.

See zipline.api.order() for more information about limit_price, stop_price, and style

See also

zipline.finance.execution.ExecutionStyle, zipline.api.order(), zipline.api.order_target(), zipline.api.order_target_percent()

zipline.api.order_target_percent(self, asset, target, limit_price=None, stop_price=None, style=None)¶

Place an order to adjust a position to a target percent of the current portfolio value. If the position doesn’t already exist, this is equivalent to placing a new order. If the position does exist, this is equivalent to placing an order for the difference between the target percent and the current percent.

Parameters

asset (Asset) – The asset that this order is for.
target (float) – The desired percentage of the portfolio value to allocate to asset. This is specified as a decimal, for example: 0.50 means 50%.
limit_price (float, optional) – The limit price for the order.
stop_price (float, optional) – The stop price for the order.
style (ExecutionStyle) – The execution style for the order.

Returns

order_id – The unique identifier for this order.

Return type

str

Notes

order_target_value does not take into account any open orders. For example:

order_target_percent(asset, 10)
order_target_percent(asset, 10)

This code will result in 20% of the portfolio being allocated to asset because the first call to order_target_percent will not have been filled when the second order_target_percent call is made.

See zipline.api.order() for more information about limit_price, stop_price, and style

See also

zipline.finance.execution.ExecutionStyle, zipline.api.order(), zipline.api.order_target(), zipline.api.order_target_value()

Execution Styles ¶

class zipline.finance.execution.MarketOrder(exchange=None, order_params=None)¶

Execution style for orders to be filled at current market price.

This is the default for orders placed with order().

Parameters

exchange (str, optional) – The exchange to route the order to. Only applicable to live trading and to certain brokers.
order_params (dict, optional) – Additional broker-specific order parameters to use in live trading. Ignored in backtests.

Examples

Place a SMART-routed market order using the Adaptive algorithm (Interactive Brokers):

>>> style = MarketOrder(exchange="SMART", order_params={"AlgoStrategy": "Adaptive"})
>>> algo.order(asset, 100, style=style)

class zipline.finance.execution.LimitOrder(limit_price, asset=None, exchange=None, order_params=None)¶

Execution style for orders to be filled at a price equal to or better than a specified limit price.

Parameters

limit_price (float) – Maximum price for buys, or minimum price for sells, at which the order should be filled.
exchange (str, optional) – The exchange to route the order to. Only applicable to live trading and to certain brokers.
order_params (dict, optional) – Additional broker-specific order parameters to use in live trading. Ignored in backtests.

class zipline.finance.execution.StopOrder(stop_price, asset=None, exchange=None, order_params=None)¶

Execution style representing a market order to be placed if market price reaches a threshold.

Parameters

stop_price (float) – Price threshold at which the order should be placed. For sells, the order will be placed if market price falls below this value. For buys, the order will be placed if market price rises above this value.
exchange (str, optional) – The exchange to route the order to. Only applicable to live trading and to certain brokers.
order_params (dict, optional) – Additional broker-specific order parameters to use in live trading. Ignored in backtests.

class zipline.finance.execution.StopLimitOrder(limit_price, stop_price, asset=None, exchange=None, order_params=None)¶

Execution style representing a limit order to be placed if market price reaches a threshold.

Parameters

limit_price (float) – Maximum price for buys, or minimum price for sells, at which the order should be filled, if placed.
stop_price (float) – Price threshold at which the order should be placed. For sells, the order will be placed if market price falls below this value. For buys, the order will be placed if market price rises above this value.
exchange (str, optional) – The exchange to route the order to. Only applicable to live trading and to certain brokers.
order_params (dict, optional) – Additional broker-specific order parameters to use in live trading. Ignored in backtests.

Order Management ¶

zipline.api.get_order(self, order_id)¶

Lookup an order based on the order id returned from one of the order functions.

Parameters: order_id (str) – The unique identifier for the order.
Returns: order – The order object.
Return type: zipline.finance.order.Order

zipline.api.get_open_orders(self, asset=None)¶

Retrieve all of the current open orders.

Parameters: asset (Asset) – If passed and not None, return only the open orders for the given asset instead of all open orders.
Returns: open_orders – If no asset is passed this will return a dict mapping Assets to a list containing all the open orders for the asset. If an asset is passed then this will return a list of the open orders for this asset.
Return type: dict[list[Order]] or list[Order]

zipline.api.cancel_order(self, order_param)¶

Cancel an open order.

Parameters: order_param (str or Order) – The order_id or order object to cancel.

class zipline.finance.order.Order(dt, asset, amount, stop=None, limit=None, filled=0, commission=0, id=None)¶

__init__(dt, asset, amount, stop=None, limit=None, filled=0, commission=0, id=None)¶

An order placed by an algorithm.

dt¶

datetime that the order was placed

Type: pd.Timestamp

asset¶

asset for the order.

Type: zipline.assets.Asset

amount¶

the number of shares to buy/sell. A positive sign indicates a buy, and a negative sign indicates a sell.

Type: int

filled¶

how many shares of the order have been filled so far

Type: int

status¶

the status of the order. To check for a certain status, compare the status to zipline.finance.order.ORDER_STATUS. Possible choices: ORDER_STATUS.OPEN, ORDER_STATUS.FILLED, ORDER_STATUS.CANCELLED, ORDER_STATUS.REJECTED, ORDER_STATUS.HELD.

Type: int

open¶

whether the order is currently open

Type: bool

Portfolio and Account ¶

class zipline.protocol.Portfolio(start_date=None, capital_base=0.0)¶

Object providing read-only access to current portfolio state. Available in algorithms via context.portfolio.

Parameters

start_date (pd.Timestamp) – The start date for the period being recorded.
capital_base (float) – The starting value for the portfolio. This will be used as the starting cash, current cash, and portfolio value.

positions¶

Dict-like object where the keys are assets and the values contain information about the currently-held position for that asset.

Type: dict-like of zipline.assets.Asset to zipline.protocol.Position

cash¶

Amount of cash currently held in portfolio.

Type: float

portfolio_value¶

Current liquidation value of the portfolio’s holdings. This is equal to cash + sum(shares * price)

Type: float

starting_cash¶

Amount of cash in the portfolio at the start of the backtest.

Type: float

class zipline.protocol.Position(underlying_position)¶

A position held by an algorithm.

asset¶

The held asset.

Type: zipline.assets.Asset

amount¶

Number of shares held. Short positions are represented with negative values.

Type: int

cost_basis¶

Average price at which currently-held shares were acquired.

Type: float

last_sale_price¶

Most recent price for the position.

Type: float

last_sale_date¶

Datetime at which last_sale_price was last updated.

Type: pd.Timestamp

class zipline.protocol.Account¶

The account object tracks information about the trading account. The values are updated as the algorithm runs and its keys remain unchanged. These values are calculated by Zipline based on the algorithm’s capital base and order activity and do not reflect the actual values of the broker.

Available in algorithms via context.account.

settled_cash¶

Type: float

accrued_interest¶

Type: float

buying_power¶

Type: float

equity_with_loan¶

Type: float

total_positions_value¶

Type: float

total_positions_exposure¶

Type: float

regt_equity¶

Type: float

regt_margin¶

Type: float

initial_margin_requirement¶

Type: float

maintenance_margin_requirement¶

Type: float

available_funds¶

Type: float

excess_liquidity¶

Type: float

cushion¶

Type: float

day_trades_remaining¶

Type: float

leverage¶

Type: float

net_leverage¶

Type: float

net_liquidation¶

Type: float

Assets ¶

zipline.api.sid(self, sid)¶

Lookup an Asset by its unique asset identifier.

Parameters: sid (str or int) – The unique asset identifier. If a string is passed, it is assumed to be the QuantRocket sid; if an integer is passed, it is assumed to be the internal Zipline sid.
Returns: asset – The asset with the given sid.
Return type: zipline.assets.Asset
Raises: SidsNotFound – When a requested sid does not map to any asset.

zipline.api.continuous_future(self, root_symbol_str, offset=0, roll='volume', adjustment='mul')¶

Create a specifier for a continuous contract.

Parameters

root_symbol_str (str) – The root symbol for the future chain.
offset (int, optional) – The distance from the primary contract. Default is 0.
roll (str, optional) – How rolls are determined. Possible choices: ‘volume’, ‘calendar’. Default is ‘volume’.
adjustment (str, optional) – Method for adjusting lookback prices between rolls. Possible choices: ‘mul’, ‘add’, None. Default is ‘mul’.

Returns

continuous_future – The continuous future specifier.

Return type

zipline.assets.ContinuousFuture

Examples

Create a continuous future for ES, rolling on volume:

>>> import zipline.api as algo
>>> algo.continuous_future("ES", roll="volume")

class zipline.assets.Asset¶

Base class for entities that can be owned by a trading algorithm.

sid¶

Internal Zipline sid. Persistent unique identifier assigned to the asset.

Type: int

zipline_sid¶

Internal Zipline sid (alias for Asset.sid).

Type: int

real_sid¶

The QuantRocket sid.

Type: str

symbol¶

Most recent ticker under which the asset traded. This field can change without warning if the asset changes tickers. Use real_sid if you need a persistent identifier.

Type: str

asset_name¶

Full name of the asset.

Type: str

exchange¶

Canonical short name of the exchange on which the asset trades (e.g., ‘NYSE’).

Type: str

exchange_full¶

Full name of the exchange on which the asset trades (e.g., ‘NEW YORK STOCK EXCHANGE’).

Type: str

country_code¶

Two character code indicating the country in which the asset trades.

Type: str

currency¶

ISO currency of asset.

Type: str

start_date¶

Date on which the asset first traded.

Type: pd.Timestamp

end_date¶

Last date on which the asset traded. This value is set to the current (real time) date for assets that are still trading.

Type: pd.Timestamp

tick_size¶

Minimum amount that the price can change for this asset.

Type: float

multiplier¶

The contract multiplier

Type: float

price_magnifier¶

The price magnifier by which to divide prices when prices are quoted in a smaller unit than the asset’s currency.

Type: float

auto_close_date¶

Date on which positions in this asset will be automatically liquidated to cash during a simulation. By default, this is three days after end_date.

Type: pd.Timestamp

class zipline.assets.Equity¶: Asset subclass representing partial ownership of a company, trust, or partnership.

class zipline.assets.Future¶: Asset subclass representing ownership of a futures contract.

See also

zipline.api.continuous_future

Trading Controls ¶

Zipline provides trading controls to help ensure that the algorithm is performing as expected. The functions help protect the algorithm from certian bugs that could cause undesirable behavior when trading with real money.

zipline.api.set_do_not_order_list(self, restricted_list, on_error='fail')¶

Set a restriction on which assets can be ordered.

Parameters: restricted_list (container[Asset], SecurityList) – The assets that cannot be ordered.

zipline.api.set_long_only(self, on_error='fail')¶: Set a rule specifying that this algorithm cannot take short positions.

zipline.api.set_max_leverage(self, max_leverage)¶

Set a limit on the maximum leverage of the algorithm.

Parameters: max_leverage (float) – The maximum leverage for the algorithm. If not provided there will be no maximum.

zipline.api.set_max_order_count(self, max_count, on_error='fail')¶

Set a limit on the number of orders that can be placed in a single day.

Parameters: max_count (int) – The maximum number of orders that can be placed on any single day.

zipline.api.set_max_order_size(self, asset=None, max_shares=None, max_notional=None, on_error='fail')¶

Set a limit on the number of shares and/or dollar value of any single order placed for sid. Limits are treated as absolute values and are enforced at the time that the algo attempts to place an order for sid.

If an algorithm attempts to place an order that would result in exceeding one of these limits, raise a TradingControlException.

Parameters

asset (Asset, optional) – If provided, this sets the guard only on positions in the given asset.
max_shares (int, optional) – The maximum number of shares that can be ordered at one time.
max_notional (float, optional) – The maximum value that can be ordered at one time.

zipline.api.set_max_position_size(self, asset=None, max_shares=None, max_notional=None, on_error='fail')¶

Set a limit on the number of shares and/or dollar value held for the given sid. Limits are treated as absolute values and are enforced at the time that the algo attempts to place an order for sid. This means that it’s possible to end up with more than the max number of shares due to splits/dividends, and more than the max notional due to price improvement.

If an algorithm attempts to place an order that would result in increasing the absolute value of shares/dollar value exceeding one of these limits, raise a TradingControlException.

Parameters

asset (Asset, optional) – If provided, this sets the guard only on positions in the given asset.
max_shares (int, optional) – The maximum number of shares to hold for an asset.
max_notional (float, optional) – The maximum value to hold for an asset.

Benchmarks ¶

zipline.api.set_benchmark(self, benchmark)¶

Set the benchmark asset.

Parameters: benchmark (zipline.assets.Asset) – The asset to set as the new benchmark.

Examples

Set the benchmark to SPY:

>>> import zipline.api as algo
>>> spy = algo.sid("FIBBG000BDTBL9")
>>> algo.set_benchmark(spy)

Notes

Any dividends payed out for that new benchmark asset will be automatically reinvested.

Commissions and Slippage ¶

Commissions and slippage are disabled by default. Use the following API to model commissions and slippage according to your needs.

Commission Models ¶

zipline.api.set_commission(self, us_equities=None, us_futures=None)¶

Sets the commission models for the simulation.

Parameters

us_equities (EquityCommissionModel) – The commission model to use for trading US equities.
us_futures (FutureCommissionModel) – The commission model to use for trading US futures.

Notes

This function can only be called during initialize().

Examples

Set the equities commission to 0.001 per share:

>>> import zipline.api as algo
>>> from zipline.finance import commission
>>> algo.set_commission(commission.PerShare(cost=0.001))

class zipline.finance.commission.CommissionModel¶

Abstract base class for commission models.

Commission models are responsible for accepting order/transaction pairs and calculating how much commission should be charged to an algorithm’s account on each transaction.

To implement a new commission model, create a subclass of CommissionModel and implement calculate().

abstract calculate(order, transaction)¶

Calculate the amount of commission to charge on order as a result of transaction.

Parameters

order (zipline.finance.order.Order) –
The order being processed.

The commission field of order is a float indicating the amount of commission already charged on this order.
transaction (zipline.finance.transaction.Transaction) – The transaction being processed. A single order may generate multiple transactions if there isn’t enough volume in a given bar to fill the full amount requested in the order.

Returns

amount_charged – The additional commission, in dollars, that we should attribute to this order.

Return type

float

class zipline.finance.commission.PerShare(cost=0.001, min_trade_cost=0.0)¶

Calculates a commission for a transaction based on a per share cost with an optional minimum cost per trade.

Parameters

cost (float, optional) – The amount of commissions paid per share traded. Default is one tenth of a cent per share.
min_trade_cost (float, optional) – The minimum amount of commissions paid per trade. Default is no minimum.

Notes

This is zipline’s default commission model for equities.

class zipline.finance.commission.PerTrade(cost=0.0)¶

Calculates a commission for a transaction based on a per trade cost.

For orders that require multiple fills, the full commission is charged to the first fill.

Parameters: cost (float, optional) – The flat amount of commissions paid per equity trade.

class zipline.finance.commission.PerDollar(cost=0.0015)¶

Model commissions by applying a fixed cost per dollar transacted.

Parameters: cost (float, optional) – The flat amount of commissions paid per dollar of equities traded. Default is a commission of $0.0015 per dollar transacted.

class zipline.finance.commission.PerContract(cost, exchange_fee, min_trade_cost=0.0)¶

Calculates a commission for a transaction based on a per contract cost with an optional minimum cost per trade.

Parameters

cost (float or dict) – The amount of commissions paid per contract traded. If given a float, the commission for all futures contracts is the same. If given a dictionary, it must map root symbols to the commission cost for contracts of that symbol.
exchange_fee (float or dict) – A flat-rate fee charged by the exchange per trade. This value is a constant, one-time charge no matter how many contracts are being traded. If given a float, the fee for all contracts is the same. If given a dictionary, it must map root symbols to the fee for contracts of that symbol.
min_trade_cost (float, optional) – The minimum amount of commissions paid per trade.

class zipline.finance.commission.PerFutureTrade(cost=0.0)¶

Calculates a commission for a transaction based on a per trade cost.

Parameters: cost (float or dict) – The flat amount of commissions paid per trade, regardless of the number of contracts being traded. If given a float, the commission for all futures contracts is the same. If given a dictionary, it must map root symbols to the commission cost for trading contracts of that symbol.

Slippage Models ¶

zipline.api.set_slippage(self, us_equities=None, us_futures=None)¶

Set the slippage models for the simulation.

Parameters

us_equities (EquitySlippageModel) – The slippage model to use for trading US equities.
us_futures (FutureSlippageModel) – The slippage model to use for trading US futures.

Examples

Set the equities slippage to 5 basis points:

>>> import zipline.api as algo
>>> from zipline.finance import slippage
>>> algo.set_slippage(slippage.FixedBasisPointsSlippage(basis_points=5.0))

Notes

This function can only be called during initialize().

class zipline.finance.slippage.SlippageModel¶

Abstract base class for slippage models.

Slippage models are responsible for the rates and prices at which orders fill during a simulation.

To implement a new slippage model, create a subclass of SlippageModel and implement process_order().

volume_for_bar¶

Number of shares that have already been filled for the currently-filling asset in the current minute. This attribute is maintained automatically by the base class. It can be used by subclasses to keep track of the total amount filled if there are multiple open orders for a single asset.

Type: int

Notes

Subclasses that define their own constructors should call super(<subclass name>, self).__init__() before performing other initialization.

abstract process_order(data, order)¶

Compute the number of shares and price to fill for order in the current minute.

Parameters

data (zipline.protocol.BarData) – The data for the given bar.
order (zipline.finance.order.Order) – The order to simulate.

Returns

execution_price (float) – The price of the fill.
execution_volume (int) – The number of shares that should be filled. Must be between 0 and order.amount - order.filled. If the amount filled is less than the amount remaining, order will remain open and will be passed again to this method in the next minute.

Raises

zipline.finance.slippage.LiquidityExceeded – May be raised if no more orders should be processed for the current asset during the current bar.

Notes

Before this method is called, volume_for_bar will be set to the number of shares that have already been filled for order.asset in the current minute.

process_order() is not called by the base class on bars for which there was no historical volume.

class zipline.finance.slippage.FixedSlippage(spread=0.0)¶

Simple model assuming a fixed-size spread for all assets.

Parameters: spread (float, optional) – Size of the assumed spread for all assets. Orders to buy will be filled at close + (spread / 2). Orders to sell will be filled at close - (spread / 2).

Notes

This model does not impose limits on the size of fills. An order for an asset will always be filled as soon as any trading activity occurs in the order’s asset, even if the size of the order is greater than the historical volume.

class zipline.finance.slippage.FixedBasisPointsSlippage(basis_points=5.0, volume_limit=0.1)¶

Model slippage as a fixed percentage difference from historical minutely close price, limiting the size of fills to a fixed percentage of historical minutely volume.

Orders to buy are filled at:

historical_price * (1 + (basis_points * 0.0001))

Orders to sell are filled at:

historical_price * (1 - (basis_points * 0.0001))

Fill sizes are capped at:

historical_volume * volume_limit

Parameters

basis_points (float, optional) – Number of basis points of slippage to apply for each fill. Default is 5 basis points.
volume_limit (float, optional) – Fraction of trading volume that can be filled each minute. Default is 10% of trading volume.

Notes

A basis point is one one-hundredth of a percent.
This class, default-constructed, is zipline’s default slippage model for equities.

class zipline.finance.slippage.VolumeShareSlippage(volume_limit=0.025, price_impact=0.1)¶

Model slippage as a quadratic function of percentage of historical volume.

Orders to buy will be filled at:

price * (1 + price_impact * (volume_share ** 2))

Orders to sell will be filled at:

price * (1 - price_impact * (volume_share ** 2))

where price is the close price for the bar, and volume_share is the percentage of minutely volume filled, up to a max of volume_limit.

Parameters

volume_limit (float, optional) – Maximum percent of historical volume that can fill in each bar. 0.5 means 50% of historical volume. 1.0 means 100%. Default is 0.025 (i.e., 2.5%).
price_impact (float, optional) – Scaling coefficient for price impact. Larger values will result in more simulated price impact. Smaller values will result in less simulated price impact. Default is 0.1.

class zipline.finance.slippage.VolatilityVolumeShare(volume_limit, eta={'AD': 0.049018143225019836, 'AI': 0.049018143225019836, 'BD': 0.050346811117733474, 'BO': 0.0549309950700463, 'BP': 0.04784154423871634, 'CD': 0.05112442064025072, 'CL': 0.04852544628414196, 'CM': 0.052683478163348625, 'CN': 0.05349971839003781, 'DJ': 0.02313009072076987, 'EC': 0.04885131067661861, 'ED': 0.09418429709024576, 'EE': 0.048713151357687556, 'EI': 0.03171270843969266, 'EL': 0.04420742201820936, 'ER': 0.04593056773771131, 'ES': 0.0473044183219935, 'ET': 0.049018143225019836, 'EU': 0.049750396084029064, 'FC': 0.058728734202178494, 'FF': 0.04897059152762404, 'FI': 0.03347717673817077, 'FS': 0.034557788010453824, 'FV': 0.04654442771605696, 'GC': 0.04893331354612521, 'HG': 0.0522384175249878, 'HO': 0.04506131841215606, 'HU': 0.017154313062463938, 'JE': 0.013948949613401812, 'JY': 0.049018143225019836, 'LB': 0.06146586386903994, 'LC': 0.05585380186285862, 'LH': 0.05755700463021978, 'MB': 0.049018143225019836, 'MD': 0.049018143225019836, 'ME': 0.030383767727818548, 'MG': 0.029579261656151684, 'MI': 0.041026288873007355, 'MS': 0.049018143225019836, 'MW': 0.052579919663880245, 'ND': 0.049018143225019836, 'NG': 0.047897809233755716, 'NK': 0.04455543505479143, 'NQ': 0.044772425085977945, 'NZ': 0.04917041807387204, 'OA': 0.05697326723277552, 'PA': 0.049018143225019836, 'PB': 0.049018143225019836, 'PL': 0.05457937966564749, 'QG': 0.049018143225019836, 'QM': 0.049018143225019836, 'RM': 0.037425041244579654, 'RR': 0.049018143225019836, 'SB': 0.057388160345668134, 'SF': 0.047784825569615726, 'SM': 0.04855286055984422, 'SP': 0.049018143225019836, 'SV': 0.05269143503993111, 'SY': 0.05204170365728161, 'TB': 0.049018143225019836, 'TN': 0.0333634653652625, 'TS': 0.03290887845506915, 'TU': 0.0638676460638408, 'TY': 0.050586988554700826, 'UB': 0.049018143225019836, 'US': 0.04798417987359072, 'VX': 0.049018143225019836, 'WC': 0.05263654211932924, 'XB': 0.044444916388854484, 'XG': 0.049018143225019836, 'YM': 0.049018143225019836, 'YS': 0.049018143225019836})¶

Model slippage for futures contracts according to the following formula:

new_price = price + (price * MI / 10000),

where ‘MI’ is market impact, which is defined as:

MI = eta * sigma * sqrt(psi)

eta is a constant which varies by root symbol.
sigma is 20-day annualized volatility.
psi is the volume traded in the given bar divided by 20-day ADV.

Parameters

volume_limit (float) – Maximum percentage (as a decimal) of a bar’s total volume that can be traded.
eta (float or dict) – Constant used in the market impact formula. If given a float, the eta for all futures contracts is the same. If given a dictionary, it must map root symbols to the eta for contracts of that symbol.

Pipeline ¶

For more information, see Pipeline API

zipline.api.attach_pipeline(self, pipeline, name, chunks=None, eager=True)¶

Parameters

pipeline (Pipeline) – The pipeline to have computed.
name (str) – The name of the pipeline.
chunks (int or iterator, optional) – The number of days to compute pipeline results for. Increasing this number will make it longer to get the first results but may improve the total runtime of the simulation. If an iterator is passed, we will run in chunks based on values of the iterator.
eager (bool, optional) – Whether or not to compute this pipeline prior to before_trading_start.

Returns

pipeline – Returns the pipeline that was attached unchanged.

Return type

Pipeline

See also

zipline.api.pipeline_output()

zipline.api.pipeline_output(self, name)¶

Get results of the pipeline attached by with name name.

Parameters: name (str) – Name of the pipeline from which to fetch results.
Returns: results – DataFrame containing the results of the requested pipeline for the current simulation date.
Return type: pd.DataFrame
Raises: NoSuchPipeline – Raised when no pipeline with the name name has been registered.

See also

zipline.api.attach_pipeline(), zipline.pipeline.engine.PipelineEngine.run_pipeline()

Recording Variables ¶

zipline.api.record(self, *args, **kwargs)¶

Track and record values each day.

Parameters: **kwargs – The names and values to record.

Notes

These values will appear in the results CSV returned in backtests.

Zipline Live Trading ¶

Real-time Data Configuration ¶

zipline.api.set_realtime_db(self, code, fields={})¶

Sets the realtime database to use for querying up-to-date minute bars in live trading.

Parameters

code (str, required) – the realtime database code. Must be an aggregate database with 1-minute bars.
fields (dict, optional) – dict mapping expected Zipline field names (‘close’, ‘high’, ‘low’, ‘open’, ‘volume’) to realtime database field names

Returns

Return type

None

Examples

Set the realtime database and map fields:

>>> algo.set_realtime_db(
        "us-stk-tick-1min",
        fields={
            "close": "LastPriceClose",
            "open": "LastPriceOpen",
            "high": "LastPriceHigh",
            "low": "LastPriceLow",
            "volume": "LastSizeSum"})

Simulation Environment ¶

zipline.api.get_environment(self, field='platform')¶

Query the execution environment.

Parameters

field ({'platform', 'arena', 'data_frequency', 'start', 'end', 'capital_base', 'platform', '*'}) –

The field to query. The options have the following meanings:

arenastr: The arena from the simulation parameters. 'backtest' or 'trade'.
data_frequency{‘daily’, ‘minute’}: data_frequency tells the algorithm if it is running with daily data or minute data.
startdatetime: The start date for the simulation.
enddatetime: The end date for the simulation.
capital_basefloat: The starting capital for the simulation.
platformstr: The platform that the code is running on. By default this will be the string ‘zipline’. This can allow algorithms to know if they are running on the Quantopian platform instead.

: dict[str -> any]
Returns all of the fields in a dictionary.

Returns

val – The value for the field queried. See above for more information.

Return type

any

Raises

ValueError – Raised when field is not a valid option.

Examples

Only perform a certain action in live trading:

>>> import zipline.api as algo
>>> if algo.get_environment("arena") == "trade":
>>>     ...

Pipeline API ¶

class zipline.pipeline.Pipeline(columns=None, screen=None, domain=GENERIC)¶

A Pipeline object represents a collection of named expressions to be compiled and executed by a PipelineEngine.

A Pipeline has two important attributes: ‘columns’, a dictionary of named Term instances, and ‘screen’, a Filter representing criteria for including an asset in the results of a Pipeline.

To compute a pipeline in the context of a TradingAlgorithm, users must call attach_pipeline in their initialize function to register that the pipeline should be computed each trading day. The most recent outputs of an attached pipeline can be retrieved by calling pipeline_output from handle_data, before_trading_start, or a scheduled function.

Parameters

columns (dict, optional) – Initial columns.
screen (zipline.pipeline.Filter, optional) – Initial screen.

add(term, name, overwrite=False)¶

Add a column.

The results of computing term will show up as a column in the DataFrame produced by running this pipeline.

Parameters

column (zipline.pipeline.Term) – A Filter, Factor, or Classifier to add to the pipeline.
name (str) – Name of the column to add.
overwrite (bool) – Whether to overwrite the existing entry if we already have a column named name.

domain(default)¶

Get the domain for this pipeline.

If an explicit domain was provided at construction time, use it.
Otherwise, infer a domain from the registered columns.
If no domain can be inferred, return default.

Parameters

default (zipline.pipeline.domain.Domain) – Domain to use if no domain can be inferred from this pipeline by itself.

Returns

domain – The domain for the pipeline.

Return type

zipline.pipeline.domain.Domain

Raises

AmbiguousDomain –
ValueError – If the terms in self conflict with self._domain.

remove(name)¶

Remove a column.

Parameters: name (str) – The name of the column to remove.
Raises: KeyError – If name is not in self.columns.
Returns: removed – The removed term.
Return type: zipline.pipeline.Term

set_screen(screen, overwrite=False)¶

Set a screen on this Pipeline.

Parameters

filter (zipline.pipeline.Filter) – The filter to apply as a screen.
overwrite (bool) – Whether to overwrite any existing screen. If overwrite is False and self.screen is not None, we raise an error.

show_graph(format='svg')¶

Render this Pipeline as a DAG.

Parameters: format ({'svg', 'png', 'jpeg'}) – Image format to render with. Default is ‘svg’.

to_execution_plan(domain, default_screen, start_date, end_date)¶

Compile into an ExecutionPlan.

Parameters

domain (zipline.pipeline.domain.Domain) – Domain on which the pipeline will be executed.
default_screen (zipline.pipeline.Term) – Term to use as a screen if self.screen is None.
all_dates (pd.DatetimeIndex) – A calendar of dates to use to calculate starts and ends for each term.
start_date (pd.Timestamp) – The first date of requested output.
end_date (pd.Timestamp) – The last date of requested output.

Returns

graph – Graph encoding term dependencies, including metadata about extra row requirements.

Return type

zipline.pipeline.graph.ExecutionPlan

to_simple_graph(default_screen)¶

Compile into a simple TermGraph with no extra row metadata.

Parameters: default_screen (zipline.pipeline.Term) – Term to use as a screen if self.screen is None.
Returns: graph – Graph encoding term dependencies.
Return type: zipline.pipeline.graph.TermGraph

property columns¶

The output columns of this pipeline.

Returns: columns – Map from column name to expression computing that column’s output.
Return type: dict[str, zipline.pipeline.ComputableTerm]

property screen¶

The screen of this pipeline.

Returns: screen – Term defining the screen for this pipeline. If screen is a filter, rows that do not pass the filter (i.e., rows for which the filter computed False) will be dropped from the output of this pipeline before returning results.
Return type: zipline.pipeline.Filter or None

Notes

Setting a screen on a Pipeline does not change the values produced for any rows: it only affects whether a given row is returned. Computing a pipeline with a screen is logically equivalent to computing the pipeline without the screen and then, as a post-processing-step, filtering out any rows for which the screen computed False.

class zipline.pipeline.CustomFactor(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Base class for user-defined Factors.

Parameters

inputs (iterable, optional) – An iterable of BoundColumn instances (e.g. USEquityPricing.close), describing the data to load and pass to self.compute. If this argument is not passed to the CustomFactor constructor, we look for a class-level attribute named inputs.
outputs (iterable[str], optional) – An iterable of strings which represent the names of each output this factor should compute and return. If this argument is not passed to the CustomFactor constructor, we look for a class-level attribute named outputs.
window_length (int, optional) – Number of rows to pass for each input. If this argument is not passed to the CustomFactor constructor, we look for a class-level attribute named window_length.
mask (zipline.pipeline.Filter, optional) – A Filter describing the assets on which we should compute each day. Each call to CustomFactor.compute will only receive assets for which mask produced True on the day for which compute is being called.

Notes

Users implementing their own Factors should subclass CustomFactor and implement a method named compute with the following signature:

def compute(self, today, assets, out, *inputs):
   ...

On each simulation date, compute will be called with the current date, an array of sids, an output array, and an input array for each expression passed as inputs to the CustomFactor constructor.

The specific types of the values passed to compute are as follows:

today : np.datetime64[ns]
    Row label for the last row of all arrays passed as `inputs`.
assets : np.array[int64, ndim=1]
    Column labels for `out` and`inputs`.
out : np.array[self.dtype, ndim=1]
    Output array of the same shape as `assets`.  `compute` should write
    its desired return values into `out`. If multiple outputs are
    specified, `compute` should write its desired return values into
    `out.<output_name>` for each output name in `self.outputs`.
*inputs : tuple of np.array
    Raw data arrays corresponding to the values of `self.inputs`.

compute functions should expect to be passed NaN values for dates on which no data was available for an asset. This may include dates on which an asset did not yet exist.

For example, if a CustomFactor requires 10 rows of close price data, and asset A started trading on Monday June 2nd, 2014, then on Tuesday, June 3rd, 2014, the column of input data for asset A will have 9 leading NaNs for the preceding days on which data was not yet available.

Examples

A CustomFactor with pre-declared defaults:

class TenDayRange(CustomFactor):
    """
    Computes the difference between the highest high in the last 10
    days and the lowest low.

    Pre-declares high and low as default inputs and `window_length` as
    10.
    """

    inputs = [USEquityPricing.high, USEquityPricing.low]
    window_length = 10

    def compute(self, today, assets, out, highs, lows):
        from numpy import nanmin, nanmax

        highest_highs = nanmax(highs, axis=0)
        lowest_lows = nanmin(lows, axis=0)
        out[:] = highest_highs - lowest_lows

# Doesn't require passing inputs or window_length because they're
# pre-declared as defaults for the TenDayRange class.
ten_day_range = TenDayRange()

A CustomFactor without defaults:

class MedianValue(CustomFactor):
    """
    Computes the median value of an arbitrary single input over an
    arbitrary window..

    Does not declare any defaults, so values for `window_length` and
    `inputs` must be passed explicitly on every construction.
    """

    def compute(self, today, assets, out, data):
        from numpy import nanmedian
        out[:] = data.nanmedian(data, axis=0)

# Values for `inputs` and `window_length` must be passed explicitly to
# MedianValue.
median_close10 = MedianValue([USEquityPricing.close], window_length=10)
median_low15 = MedianValue([USEquityPricing.low], window_length=15)

A CustomFactor with multiple outputs:

class MultipleOutputs(CustomFactor):
    inputs = [USEquityPricing.close]
    outputs = ['alpha', 'beta']
    window_length = N

    def compute(self, today, assets, out, close):
        computed_alpha, computed_beta = some_function(close)
        out.alpha[:] = computed_alpha
        out.beta[:] = computed_beta

# Each output is returned as its own Factor upon instantiation.
alpha, beta = MultipleOutputs()

# Equivalently, we can create a single factor instance and access each
# output as an attribute of that instance.
multiple_outputs = MultipleOutputs()
alpha = multiple_outputs.alpha
beta = multiple_outputs.beta

Note: If a CustomFactor has multiple outputs, all outputs must have the same dtype. For instance, in the example above, if alpha is a float then beta must also be a float.

class zipline.pipeline.Filter(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), domain=sentinel('NotSpecified'), *args, **kwargs)¶

Pipeline expression computing a boolean output.

Filters are most commonly useful for describing sets of assets to include or exclude for some particular purpose. Many Pipeline API functions accept a mask argument, which can be supplied a Filter indicating that only values passing the Filter should be considered when performing the requested computation. For example, zipline.pipeline.Factor.top() accepts a mask indicating that ranks should be computed only on assets that passed the specified Filter.

The most common way to construct a Filter is via one of the comparison operators (<, <=, !=, eq, >, >=) of Factor. For example, a natural way to construct a Filter for stocks with a 10-day VWAP less than $20.0 is to first construct a Factor computing 10-day VWAP and compare it to the scalar value 20.0:

>>> from zipline.pipeline.factors import VWAP
>>> vwap_10 = VWAP(window_length=10)
>>> vwaps_under_20 = (vwap_10 <= 20)

Filters can also be constructed via comparisons between two Factors. For example, to construct a Filter producing True for asset/date pairs where the asset’s 10-day VWAP was greater than it’s 30-day VWAP:

>>> short_vwap = VWAP(window_length=10)
>>> long_vwap = VWAP(window_length=30)
>>> higher_short_vwap = (short_vwap > long_vwap)

Filters can be combined via the & (and) and | (or) operators.

&-ing together two filters produces a new Filter that produces True if both of the inputs produced True.

|-ing together two filters produces a new Filter that produces True if either of its inputs produced True.

The ~ operator can be used to invert a Filter, swapping all True values with Falses and vice-versa.

Filters may be set as the screen attribute of a Pipeline, indicating asset/date pairs for which the filter produces False should be excluded from the Pipeline’s output. This is useful both for reducing noise in the output of a Pipeline and for reducing memory consumption of Pipeline results.

__and__(other)¶: Binary Operator: ‘&’

__or__(other)¶: Binary Operator: ‘|’

class zipline.pipeline.Factor(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), domain=sentinel('NotSpecified'), *args, **kwargs)¶

Pipeline API expression producing a numerical or date-valued output.

Factors are the most commonly-used Pipeline term, representing the result of any computation producing a numerical result.

Factors can be combined, both with other Factors and with scalar values, via any of the builtin mathematical operators (+, -, *, etc).

This makes it easy to write complex expressions that combine multiple Factors. For example, constructing a Factor that computes the average of two other Factors is simply:

>>> f1 = SomeFactor(...)  
>>> f2 = SomeOtherFactor(...)  
>>> average = (f1 + f2) / 2.0  

Factors can also be converted into zipline.pipeline.Filter objects via comparison operators: (<, <=, !=, eq, >, >=).

There are many natural operators defined on Factors besides the basic numerical operators. These include methods for identifying missing or extreme-valued outputs (isnull(), notnull(), isnan(), notnan()), methods for normalizing outputs (rank(), demean(), zscore()), and methods for constructing Filters based on rank-order properties of results (top(), bottom(), percentile_between()).

eq(other)¶

Construct a Filter computing self == other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: filter – Filter computing self == other with the outputs of self and other.
Return type: zipline.pipeline.Filter

demean(mask=sentinel('NotSpecified'), groupby=sentinel('NotSpecified'))¶

Construct a Factor that computes self and subtracts the mean from row of the result.

If mask is supplied, ignore values where mask returns False when computing row means, and output NaN anywhere the mask is False.

If groupby is supplied, compute by partitioning each row based on the values produced by groupby, de-meaning the partitioned arrays, and stitching the sub-results back together.

Parameters

mask (zipline.pipeline.Filter, optional) – A Filter defining values to ignore when computing means.
groupby (zipline.pipeline.Classifier, optional) – A classifier defining partitions over which to compute means.

Examples

Let f be a Factor which would produce the following output:

             AAPL   MSFT    MCD     BK
2017-03-13    1.0    2.0    3.0    4.0
2017-03-14    1.5    2.5    3.5    1.0
2017-03-15    2.0    3.0    4.0    1.5
2017-03-16    2.5    3.5    1.0    2.0

Let c be a Classifier producing the following output:

             AAPL   MSFT    MCD     BK
2017-03-13      1      1      2      2
2017-03-14      1      1      2      2
2017-03-15      1      1      2      2
2017-03-16      1      1      2      2

Let m be a Filter producing the following output:

             AAPL   MSFT    MCD     BK
2017-03-13  False   True   True   True
2017-03-14   True  False   True   True
2017-03-15   True   True  False   True
2017-03-16   True   True   True  False

Then f.demean() will subtract the mean from each row produced by f.

             AAPL   MSFT    MCD     BK
2017-03-13 -1.500 -0.500  0.500  1.500
2017-03-14 -0.625  0.375  1.375 -1.125
2017-03-15 -0.625  0.375  1.375 -1.125
2017-03-16  0.250  1.250 -1.250 -0.250

f.demean(mask=m) will subtract the mean from each row, but means will be calculated ignoring values on the diagonal, and NaNs will written to the diagonal in the output. Diagonal values are ignored because they are the locations where the mask m produced False.

             AAPL   MSFT    MCD     BK
2017-03-13    NaN -1.000  0.000  1.000
2017-03-14 -0.500    NaN  1.500 -1.000
2017-03-15 -0.166  0.833    NaN -0.666
2017-03-16  0.166  1.166 -1.333    NaN

f.demean(groupby=c) will subtract the group-mean of AAPL/MSFT and MCD/BK from their respective entries. The AAPL/MSFT are grouped together because both assets always produce 1 in the output of the classifier c. Similarly, MCD/BK are grouped together because they always produce 2.

             AAPL   MSFT    MCD     BK
2017-03-13 -0.500  0.500 -0.500  0.500
2017-03-14 -0.500  0.500  1.250 -1.250
2017-03-15 -0.500  0.500  1.250 -1.250
2017-03-16 -0.500  0.500 -0.500  0.500

f.demean(mask=m, groupby=c) will also subtract the group-mean of AAPL/MSFT and MCD/BK, but means will be calculated ignoring values on the diagonal , and NaNs will be written to the diagonal in the output.

             AAPL   MSFT    MCD     BK
2017-03-13    NaN  0.000 -0.500  0.500
2017-03-14  0.000    NaN  1.250 -1.250
2017-03-15 -0.500  0.500    NaN  0.000
2017-03-16 -0.500  0.500  0.000    NaN

Notes

Mean is sensitive to the magnitudes of outliers. When working with factor that can potentially produce large outliers, it is often useful to use the mask parameter to discard values at the extremes of the distribution:

>>> base = MyFactor(...)  
>>> normalized = base.demean(
...     mask=base.percentile_between(1, 99),
... )  

demean() is only supported on Factors of dtype float64.

See also

pandas.DataFrame.groupby()

zscore(mask=sentinel('NotSpecified'), groupby=sentinel('NotSpecified'))¶

Construct a Factor that Z-Scores each day’s results.

The Z-Score of a row is defined as:

(row - row.mean()) / row.stddev()

If mask is supplied, ignore values where mask returns False when computing row means and standard deviations, and output NaN anywhere the mask is False.

If groupby is supplied, compute by partitioning each row based on the values produced by groupby, z-scoring the partitioned arrays, and stitching the sub-results back together.

Parameters

mask (zipline.pipeline.Filter, optional) – A Filter defining values to ignore when Z-Scoring.
groupby (zipline.pipeline.Classifier, optional) – A classifier defining partitions over which to compute Z-Scores.

Returns

zscored – A Factor producing that z-scores the output of self.

Return type

zipline.pipeline.Factor

Notes

Mean and standard deviation are sensitive to the magnitudes of outliers. When working with factor that can potentially produce large outliers, it is often useful to use the mask parameter to discard values at the extremes of the distribution:

>>> base = MyFactor(...)  
>>> normalized = base.zscore(
...    mask=base.percentile_between(1, 99),
... )  

zscore() is only supported on Factors of dtype float64.

Examples

See demean() for an in-depth example of the semantics for mask and groupby.

See also

pandas.DataFrame.groupby()

rank(method='ordinal', ascending=True, mask=sentinel('NotSpecified'), groupby=sentinel('NotSpecified'))¶

Construct a new Factor representing the sorted rank of each column within each row.

Parameters

method (str, {'ordinal', 'min', 'max', 'dense', 'average'}) – The method used to assign ranks to tied elements. See scipy.stats.rankdata for a full description of the semantics for each ranking method. Default is ‘ordinal’.
ascending (bool, optional) – Whether to return sorted rank in ascending or descending order. Default is True.
mask (zipline.pipeline.Filter, optional) – A Filter representing assets to consider when computing ranks. If mask is supplied, ranks are computed ignoring any asset/date pairs for which mask produces a value of False.
groupby (zipline.pipeline.Classifier, optional) – A classifier defining partitions over which to perform ranking.

Returns

ranks – A new factor that will compute the ranking of the data produced by self.

Return type

zipline.pipeline.Factor

Notes

The default value for method is different from the default for scipy.stats.rankdata. See that function’s documentation for a full description of the valid inputs to method.

Missing or non-existent data on a given day will cause an asset to be given a rank of NaN for that day.

See also

scipy.stats.rankdata()

pearsonr(target, correlation_length, mask=sentinel('NotSpecified'))¶

Construct a new Factor that computes rolling pearson correlation coefficients between target and the columns of self.

Parameters

target (zipline.pipeline.Term) – The term used to compute correlations against each column of data produced by self. This may be a Factor, a BoundColumn or a Slice. If target is two-dimensional, correlations are computed asset-wise.
correlation_length (int) – Length of the lookback window over which to compute each correlation coefficient.
mask (zipline.pipeline.Filter, optional) – A Filter describing which assets should have their correlation with the target slice computed each day.

Returns

correlations – A new Factor that will compute correlations between target and the columns of self.

Return type

zipline.pipeline.Factor

Notes

This method can only be called on expressions which are deemed safe for use as inputs to windowed Factor objects. Examples of such expressions include This includes BoundColumn Returns and any factors created from rank() or zscore().

Examples

Suppose we want to create a factor that computes the correlation between AAPL’s 10-day returns and the 10-day returns of all other assets, computing each correlation over 30 days. This can be achieved by doing the following:

returns = Returns(window_length=10)
returns_slice = returns[sid(24)]
aapl_correlations = returns.pearsonr(
    target=returns_slice, correlation_length=30,
)

This is equivalent to doing:

aapl_correlations = RollingPearsonOfReturns(
    target=sid(24), returns_length=10, correlation_length=30,
)

spearmanr(target, correlation_length, mask=sentinel('NotSpecified'))¶

Construct a new Factor that computes rolling spearman rank correlation coefficients between target and the columns of self.

Parameters

target (zipline.pipeline.Term) – The term used to compute correlations against each column of data produced by self. This may be a Factor, a BoundColumn or a Slice. If target is two-dimensional, correlations are computed asset-wise.
correlation_length (int) – Length of the lookback window over which to compute each correlation coefficient.
mask (zipline.pipeline.Filter, optional) – A Filter describing which assets should have their correlation with the target slice computed each day.

Returns

correlations – A new Factor that will compute correlations between target and the columns of self.

Return type

zipline.pipeline.Factor

Notes

Examples

returns = Returns(window_length=10)
returns_slice = returns[sid(24)]
aapl_correlations = returns.spearmanr(
    target=returns_slice, correlation_length=30,
)

This is equivalent to doing:

aapl_correlations = RollingSpearmanOfReturns(
    target=sid(24), returns_length=10, correlation_length=30,
)

See also

scipy.stats.spearmanr(), Factor.pearsonr()

linear_regression(target, regression_length, mask=sentinel('NotSpecified'))¶

Construct a new Factor that performs an ordinary least-squares regression predicting the columns of self from target.

Parameters

target (zipline.pipeline.Term) – The term to use as the predictor/independent variable in each regression. This may be a Factor, a BoundColumn or a Slice. If target is two-dimensional, regressions are computed asset-wise.
regression_length (int) – Length of the lookback window over which to compute each regression.
mask (zipline.pipeline.Filter, optional) – A Filter describing which assets should be regressed with the target slice each day.

Returns

regressions – A new Factor that will compute linear regressions of target against the columns of self.

Return type

zipline.pipeline.Factor

Notes

Examples

Suppose we want to create a factor that regresses AAPL’s 10-day returns against the 10-day returns of all other assets, computing each regression over 30 days. This can be achieved by doing the following:

returns = Returns(window_length=10)
returns_slice = returns[sid(24)]
aapl_regressions = returns.linear_regression(
    target=returns_slice, regression_length=30,
)

This is equivalent to doing:

aapl_regressions = RollingLinearRegressionOfReturns(
    target=sid(24), returns_length=10, regression_length=30,
)

See also

scipy.stats.linregress()

winsorize(min_percentile, max_percentile, mask=sentinel('NotSpecified'), groupby=sentinel('NotSpecified'))¶

Construct a new factor that winsorizes the result of this factor.

Winsorizing changes values ranked less than the minimum percentile to the value at the minimum percentile. Similarly, values ranking above the maximum percentile are changed to the value at the maximum percentile.

Winsorizing is useful for limiting the impact of extreme data points without completely removing those points.

If mask is supplied, ignore values where mask returns False when computing percentile cutoffs, and output NaN anywhere the mask is False.

If groupby is supplied, winsorization is applied separately separately to each group defined by groupby.

Parameters

min_percentile (float, int) – Entries with values at or below this percentile will be replaced with the (len(input) * min_percentile)th lowest value. If low values should not be clipped, use 0.
max_percentile (float, int) – Entries with values at or above this percentile will be replaced with the (len(input) * max_percentile)th lowest value. If high values should not be clipped, use 1.
mask (zipline.pipeline.Filter, optional) – A Filter defining values to ignore when winsorizing.
groupby (zipline.pipeline.Classifier, optional) – A classifier defining partitions over which to winsorize.

Returns

winsorized – A Factor producing a winsorized version of self.

Return type

zipline.pipeline.Factor

Examples

price = USEquityPricing.close.latest
columns={
    'PRICE': price,
    'WINSOR_1: price.winsorize(
        min_percentile=0.25, max_percentile=0.75
    ),
    'WINSOR_2': price.winsorize(
        min_percentile=0.50, max_percentile=1.0
    ),
    'WINSOR_3': price.winsorize(
        min_percentile=0.0, max_percentile=0.5
    ),

}

Given a pipeline with columns, defined above, the result for a given day could look like:

        'PRICE' 'WINSOR_1' 'WINSOR_2' 'WINSOR_3'
Asset_1    1        2          4          3
Asset_2    2        2          4          3
Asset_3    3        3          4          3
Asset_4    4        4          4          4
Asset_5    5        5          5          4
Asset_6    6        5          5          4

See also

scipy.stats.mstats.winsorize(), pandas.DataFrame.groupby()

quantiles(bins, mask=sentinel('NotSpecified'))¶

Construct a Classifier computing quantiles of the output of self.

Every non-NaN data point the output is labelled with an integer value from 0 to (bins - 1). NaNs are labelled with -1.

If mask is supplied, ignore data points in locations for which mask produces False, and emit a label of -1 at those locations.

Parameters

bins (int) – Number of bins labels to compute.
mask (zipline.pipeline.Filter, optional) – Mask of values to ignore when computing quantiles.

Returns

quantiles – A classifier producing integer labels ranging from 0 to (bins - 1).

Return type

zipline.pipeline.Classifier

quartiles(mask=sentinel('NotSpecified'))¶

Construct a Classifier computing quartiles over the output of self.

Every non-NaN data point the output is labelled with a value of either 0, 1, 2, or 3, corresponding to the first, second, third, or fourth quartile over each row. NaN data points are labelled with -1.

If mask is supplied, ignore data points in locations for which mask produces False, and emit a label of -1 at those locations.

Parameters: mask (zipline.pipeline.Filter, optional) – Mask of values to ignore when computing quartiles.
Returns: quartiles – A classifier producing integer labels ranging from 0 to 3.
Return type: zipline.pipeline.Classifier

quintiles(mask=sentinel('NotSpecified'))¶

Construct a Classifier computing quintile labels on self.

Every non-NaN data point the output is labelled with a value of either 0, 1, 2, or 3, 4, corresonding to quintiles over each row. NaN data points are labelled with -1.

If mask is supplied, ignore data points in locations for which mask produces False, and emit a label of -1 at those locations.

Parameters: mask (zipline.pipeline.Filter, optional) – Mask of values to ignore when computing quintiles.
Returns: quintiles – A classifier producing integer labels ranging from 0 to 4.
Return type: zipline.pipeline.Classifier

deciles(mask=sentinel('NotSpecified'))¶

Construct a Classifier computing decile labels on self.

Every non-NaN data point the output is labelled with a value from 0 to 9 corresonding to deciles over each row. NaN data points are labelled with -1.

If mask is supplied, ignore data points in locations for which mask produces False, and emit a label of -1 at those locations.

Parameters: mask (zipline.pipeline.Filter, optional) – Mask of values to ignore when computing deciles.
Returns: deciles – A classifier producing integer labels ranging from 0 to 9.
Return type: zipline.pipeline.Classifier

top(N, mask=sentinel('NotSpecified'), groupby=sentinel('NotSpecified'))¶

Construct a Filter matching the top N asset values of self each day.

If groupby is supplied, returns a Filter matching the top N asset values for each group.

Parameters

N (int) – Number of assets passing the returned filter each day.
mask (zipline.pipeline.Filter, optional) – A Filter representing assets to consider when computing ranks. If mask is supplied, top values are computed ignoring any asset/date pairs for which mask produces a value of False.
groupby (zipline.pipeline.Classifier, optional) – A classifier defining partitions over which to perform ranking.

Returns

filter

Return type

zipline.pipeline.Filter

bottom(N, mask=sentinel('NotSpecified'), groupby=sentinel('NotSpecified'))¶

Construct a Filter matching the bottom N asset values of self each day.

If groupby is supplied, returns a Filter matching the bottom N asset values for each group defined by groupby.

Parameters

N (int) – Number of assets passing the returned filter each day.
mask (zipline.pipeline.Filter, optional) – A Filter representing assets to consider when computing ranks. If mask is supplied, bottom values are computed ignoring any asset/date pairs for which mask produces a value of False.
groupby (zipline.pipeline.Classifier, optional) – A classifier defining partitions over which to perform ranking.

Returns

filter

Return type

zipline.pipeline.Filter

percentile_between(min_percentile, max_percentile, mask=sentinel('NotSpecified'))¶

Construct a Filter matching values of self that fall within the range defined by min_percentile and max_percentile.

Parameters

min_percentile (float [0.0, 100.0]) – Return True for assets falling above this percentile in the data.
max_percentile (float [0.0, 100.0]) – Return True for assets falling below this percentile in the data.
mask (zipline.pipeline.Filter, optional) – A Filter representing assets to consider when percentile calculating thresholds. If mask is supplied, percentile cutoffs are computed each day using only assets for which mask returns True. Assets for which mask produces False will produce False in the output of this Factor as well.

Returns

out – A new filter that will compute the specified percentile-range mask.

Return type

zipline.pipeline.Filter

isnan()¶

A Filter producing True for all values where this Factor is NaN.

Returns: nanfilter
Return type: zipline.pipeline.Filter

notnan()¶

A Filter producing True for values where this Factor is not NaN.

Returns: nanfilter
Return type: zipline.pipeline.Filter

isfinite()¶: A Filter producing True for values where this Factor is anything but NaN, inf, or -inf.

__add__(other)¶

Construct a Factor computing self + other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: factor – Factor computing self + other with outputs of self and other.
Return type: zipline.pipeline.Factor

__sub__(other)¶

Construct a Factor computing self - other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: factor – Factor computing self - other with outputs of self and other.
Return type: zipline.pipeline.Factor

__mul__(other)¶

Construct a Factor computing self * other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: factor – Factor computing self * other with outputs of self and other.
Return type: zipline.pipeline.Factor

__div__(other)¶

Construct a Factor computing self / other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: factor – Factor computing self / other with outputs of self and other.
Return type: zipline.pipeline.Factor

__mod__(other)¶

Construct a Factor computing self % other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: factor – Factor computing self % other with outputs of self and other.
Return type: zipline.pipeline.Factor

__pow__(other)¶

Construct a Factor computing self ** other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: factor – Factor computing self ** other with outputs of self and other.
Return type: zipline.pipeline.Factor

__lt__(other)¶

Construct a Filter computing self < other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: filter – Filter computing self < other with the outputs of self and other.
Return type: zipline.pipeline.Filter

__le__(other)¶

Construct a Filter computing self <= other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: filter – Filter computing self <= other with the outputs of self and other.
Return type: zipline.pipeline.Filter

__ne__(other)¶

Construct a Filter computing self != other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: filter – Filter computing self != other with the outputs of self and other.
Return type: zipline.pipeline.Filter

__ge__(other)¶

Construct a Filter computing self >= other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: filter – Filter computing self >= other with the outputs of self and other.
Return type: zipline.pipeline.Filter

__gt__(other)¶

Construct a Filter computing self > other.

Parameters: other (zipline.pipeline.Factor, float) – Right-hand side of the expression.
Returns: filter – Filter computing self > other with the outputs of self and other.
Return type: zipline.pipeline.Filter

class zipline.pipeline.Term(domain=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), window_safe=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), *args, **kwargs)¶

Base class for objects that can appear in the compute graph of a zipline.pipeline.Pipeline.

Notes

Most Pipeline API users only interact with Term via subclasses:

BoundColumn
Factor
Filter
Classifier

Instances of Term are memoized. If you call a Term’s constructor with the same arguments twice, the same object will be returned from both calls:

Example:

>>> from zipline.pipeline.data import EquityPricing
>>> from zipline.pipeline.factors import SimpleMovingAverage
>>> x = SimpleMovingAverage(inputs=[EquityPricing.close], window_length=5)
>>> y = SimpleMovingAverage(inputs=[EquityPricing.close], window_length=5)
>>> x is y
True

Warning

Memoization of terms means that it’s generally unsafe to modify attributes of a term after construction.

graph_repr()¶: A short repr to use when rendering GraphViz graphs.

recursive_repr()¶: A short repr to use when recursively rendering terms with inputs.

Pipeline Data ¶

Equity Pricing ¶

class zipline.pipeline.data.EquityPricing¶

DataSet containing daily trading prices and volumes.

open = EquityPricing.open::float64¶

high = EquityPricing.high::float64¶

low = EquityPricing.low::float64¶

close = EquityPricing.close::float64¶

volume = EquityPricing.volume::float64¶

Securities Master ¶

class zipline.pipeline.data.master.SecuritiesMaster¶

Dataset representing the securities master file.

Sid¶

Type: str

Symbol¶

Type: str

Exchange¶

Type: str

Currency¶

Type: str

SecType¶

Type: str

Etf¶

Type: bool

Timezone¶

Type: str

Name¶

Type: str

PriceMagnifier¶

Type: float

Multiplier¶

Type: float

Delisted¶

Type: bool

DateDelisted¶

Type: datetime64D

LastTradeDate¶

Type: datetime64D

RolloverDate¶

Type: datetime64D

alpaca_AssetId¶

Asset ID

Type: str

alpaca_AssetClass¶

“us_equity”

Type: str

alpaca_Exchange¶

AMEX, ARCA, BATS, NYSE, NASDAQ or NYSEARCA

Type: str

alpaca_Symbol¶

Type: str

alpaca_Name¶

Type: str

alpaca_Status¶

active or inactive

Type: str

alpaca_Tradable¶

Asset is tradable on Alpaca or not.

Type: float

alpaca_Marginable¶

Asset is marginable or not.

Type: float

alpaca_Shortable¶

Asset is shortable or not.

Type: float

alpaca_EasyToBorrow¶

Asset is easy-to-borrow or not (filtering for easy_to_borrow = True is the best way to check whether the name is currently available to short at Alpaca).

Type: float

edi_SecId¶

Unique global level Security ID (can be used to link all multiple listings together)

Type: float

edi_Currency¶

Type: str

edi_PrimaryMic¶

MIC code for the primary listing (empty if unknown)

Type: str

edi_Mic¶

ISO standard Market Identification Code

Type: str

edi_MicSegment¶

ISO standard Market Identification Code

Type: str

edi_MicTimezone¶

Type: str

edi_IsPrimaryListing¶

1 if PrimaryMic = Mic

Type: float

edi_LocalSymbol¶

Local code unique at Market level - a ticker or number

Type: str

edi_IssuerId¶

Unique global level Issuer ID (can be used to link all securities of a company togther)

Type: float

edi_IssuerName¶

Type: str

edi_IsoCountryInc¶

ISO Country of Incorporation of Issuer

Type: str

edi_CountryInc¶

Type: str

edi_IsoCountryListed¶

Country of Exchange where listed

Type: str

edi_CountryListed¶

Type: str

edi_SicCode¶

Standard Industrial Classification Code

Type: int

edi_Sic¶

Type: str

edi_SicIndustryGroup¶

Type: str

edi_SicMajorGroup¶

Type: str

edi_SicDivision¶

Type: str

edi_Cik¶

Central Index Key

Type: str

edi_Industry¶

Type: str

edi_SecTypeCode¶

Type of Equity Instrument

Type: str

edi_SecTypeDesc¶

Type of Equity Instrument (lookup SECTYPE with SectyCD)

Type: str

edi_SecurityDesc¶

Type: str

edi_PreferredName¶

for ETFs, the SecurityDesc, else the IssuerName

Type: str

edi_GlobalListingStatus¶

Inactive at the global level else security is active. Not to be confused with delisted which is inactive at the exchange level (lookup SECSTATUS)

Type: str

edi_ExchangeListingStatus¶

Indicates whether a security is Listed on an Exchange or Unlisted Indicates Exchange Listing Status (lookup LISTSTAT)

Type: str

edi_DateDelisted¶

Type: datetime64D

edi_StructureCode¶

Type: str

edi_StructureDesc¶

Type: str

edi_RecordModified¶

Date event updated, format is yyyy/mm/dd hh:mm:ss

Type: str

edi_RecordCreated¶

Date event first entered

Type: str

edi_FirstPriceDate¶

first date a price is available

Type: datetime64D

edi_LastPriceDate¶

latest date a price is available

Type: datetime64D

ibkr_ConId¶

Type: float

ibkr_Symbol¶

Type: str

ibkr_SecType¶

Type: str

ibkr_Etf¶

Type: bool

ibkr_PrimaryExchange¶

Type: str

ibkr_Currency¶

Type: str

ibkr_LocalSymbol¶

Type: str

ibkr_TradingClass¶

Type: str

ibkr_MarketName¶

Type: str

ibkr_LongName¶

Type: str

ibkr_Timezone¶

Type: str

ibkr_ValidExchanges¶

Type: str

ibkr_AggGroup¶

Type: float

ibkr_Sector¶

Type: str

ibkr_Industry¶

Type: str

ibkr_Category¶

Type: str

ibkr_MinTick¶

Type: float

ibkr_PriceMagnifier¶

Type: float

ibkr_MdSizeMultiplier¶

Type: float

ibkr_LastTradeDate¶

Type: datetime64D

ibkr_ContractMonth¶

Type: float

ibkr_RealExpirationDate¶

Type: datetime64D

ibkr_Multiplier¶

Type: float

ibkr_UnderConId¶

Type: float

ibkr_UnderSymbol¶

Type: str

ibkr_UnderSecType¶

Type: str

ibkr_MarketRuleIds¶

Type: str

ibkr_Strike¶

Type: float

ibkr_Right¶

Type: str

ibkr_Isin¶

Type: str

ibkr_Cusip¶

Type: str

ibkr_EvRule¶

Type: str

ibkr_EvMultiplier¶

Type: float

ibkr_Delisted¶

Type: bool

ibkr_DateDelisted¶

Type: datetime64D

sharadar_Permaticker¶

Permanent Ticker Symbol - The permaticker is a unique and unchanging identifier for an issuer in the dataset which is issued by Sharadar.

Type: float

sharadar_Ticker¶

Ticker Symbol - The ticker is a unique identifer for an issuer in the database. Where a ticker contains a “.” or a “-” this is removed from the ticker. For example BRK.B is BRKB. We include the BRK.B ticker in the Related Tickers field. Where a company is delisted and the ticker is recycled; we use that ticker for the currently active company and append a number to the ticker of the delisted company. eg GM is the current actively traded entity; & GM1 is the entity that filed for bankruptcy in 2009.

Type: str

sharadar_Name¶

Issuer Name - The name of the security issuer.

Type: str

sharadar_Exchange¶

Stock Exchange - The exchange on which the security trades. Examples are: “NASDAQ”;”NYSE”;”NYSEARCA”;”BATS”;”OTC” and “NYSEMKT” (previously the American Stock exchange).

Type: str

sharadar_Delisted¶

Is Delisted? - Is the security delisted?

Type: bool

sharadar_DateDelisted¶

Type: datetime64D

sharadar_Category¶

Issuer Category - The category of the issuer: “Domestic”; “Canadian” or “ADR”.

Type: str

sharadar_Cusips¶

CUSIPs - A security identifier. Space delimited in the event of multiple identifiers.

Type: str

sharadar_SicCode¶

Standard Industrial Classification (SIC) Code - The Standard Industrial Classification (SIC) is a system for classifying industries by a four-digit code; as sourced from SEC filings. More on the SIC system here: https://en.wikipedia.org/wiki/Standard_Industrial_Classification

Type: int

sharadar_SicSector¶

SIC Sector - The SIC sector is based on the SIC code and the division tabled here: https://en.wikipedia.org/wiki/Standard_Industrial_Classification

Type: str

sharadar_SicIndustry¶

SIC Industry - The SIC industry is based on the SIC code and the industry tabled here: https://www.sec.gov/info/edgar/siccodes.htm

Type: str

sharadar_FamaSector¶

Fama Sector - Not currently active - coming in a future update.

Type: str

sharadar_FamaIndustry¶

Fama Industry - Industry classifications based on the SIC code and classifications by Fama and French here: http://mba.tuck.dartmouth.edu /pages/faculty/ken.french/Data_Library/det_48_ind_port.html

Type: str

sharadar_Sector¶

Sector - Sharadar’s sector classification based on SIC codes in a format which approximates to GICS.

Type: str

sharadar_Industry¶

Industry - Sharadar’s industry classification based on SIC codes in a format which approximates to GICS.

Type: str

sharadar_ScaleMarketCap¶

Company Scale - Market Cap - This field is experimental and subject to change. It categorises the company according to it’s maximum observed market cap as follows: 1 - Nano <$50m; 2 - Micro < $300m; 3 - Small < $2bn; 4 - Mid <$10bn; 5 - Large < $200bn; 6 - Mega >= $200bn

Type: str

sharadar_ScaleRevenue¶

Company Scale - Revenue - This field is experimental and subject to change. It categorises the company according to it’s maximum observed annual revenue as follows: 1 - Nano <$50m; 2 - Micro < $300m; 3 - Small < $2bn; 4 - Mid <$10bn; 5 - Large < $200bn; 6 - Mega >= $200bn

Type: str

sharadar_RelatedTickers¶

Related Tickers - Where related tickers have been identified this field is populated. Related tickers can include the prior ticker before a ticker change; and it tickers for alternative share classes.

Type: str

sharadar_Currency¶

Currency - The company functional reporting currency for the SF1 Fundamentals table or the currency for EOD prices in SEP and SFP.

Type: str

sharadar_Location¶

Location - The company location as registered with the Securities and Exchange Commission.

Type: str

sharadar_CountryListed¶

ISO country code where security is listed

Type: str

sharadar_LastUpdated¶

Last Updated Date - Last Updated represents the last date that this database entry was updated; which is useful to users when updating their local records.

Type: datetime64D

sharadar_FirstAdded¶

First Added Date - The date that the ticker was first added to coverage in the dataset.

Type: datetime64D

sharadar_FirstPriceDate¶

First Price Date - The date of the first price observation for a given ticker. Can be used as a proxy for IPO date. Minimum value of 1986-01-01 for IPO’s that occurred prior to this date. Note: this does not necessarily represent the first price date available in our datasets since our end of day price history currently starts in December 1998.

Type: datetime64D

sharadar_LastPriceDate¶

Last Price Date - The most recent price observation available.

Type: datetime64D

sharadar_FirstQuarter¶

First Quarter - The first financial quarter available in the dataset.

Type: datetime64D

sharadar_LastQuarter¶

Last Quarter - The last financial quarter available in the dataset.

Type: datetime64D

sharadar_SecFilings¶

SEC Filings URL - The URL pointing to the SEC filings which also contains the Central Index Key (CIK).

Type: str

sharadar_CompanySite¶

Company Website URL - The URL pointing to the company website.

Type: str

usstock_Mic¶

Type: str

usstock_Symbol¶

Type: str

usstock_Name¶

Type: str

usstock_SicCode¶

Type: str

usstock_Sic¶

Type: str

usstock_SicIndustryGroup¶

Type: str

usstock_SicMajorGroup¶

Type: str

usstock_SicDivision¶

Type: str

usstock_SecurityType¶

Type: str

usstock_SecurityType2¶

Type: str

usstock_DateDelisted¶

Type: datetime64D

usstock_FirstPriceDate¶

Type: datetime64D

usstock_LastPriceDate¶

Type: datetime64D

figi_Figi¶

e.g. BBG000BBBRC7

Type: str

figi_Name¶

e.g. AFLAC INC

Type: str

figi_Ticker¶

e.g. AFL

Type: str

figi_CompositeFigi¶

e.g. BBG000BBBNC6

Type: str

figi_ExchCode¶

e.g. UN

Type: str

figi_UniqueId¶

e.g. EQ0010001500001000

Type: str

figi_SecurityType¶

e.g. Common Stock

Type: str

figi_MarketSector¶

e.g. Equity

Type: str

figi_ShareClassFigi¶

e.g. BBG001S5NGJ4

Type: str

figi_UniqueIdFutOpt¶

Type: str

figi_SecurityType2¶

e.g. Common Stock

Type: str

figi_SecurityDescription¶

e.g. AFL

Type: str

figi_IsComposite¶

whether the Figi column contains a composite FIGI

Type: bool

Examples

Filter ETFs:

>>> are_etfs = SecuritiesMaster.Etf.latest

Filter NYSE stocks:

>>> are_nyse_stocks = SecuritiesMaster.Exchange.latest.eq("XNYS")

Alpaca ¶

class zipline.pipeline.data.alpaca.ETB¶

Dataset representing whether securities are easy-to-borrow through Alpaca.

etb¶

whether the security is easy-to-borrow

Type: bool

Examples

>>> are_etb = alpaca.ETB.etb.latest

Interactive Brokers ¶

class zipline.pipeline.data.ibkr.ShortableShares¶

DataSetFamily representing IBKR shortable shares. In order to use the data in a pipeline, it must first be sliced to generate a regular pipeline DataSet.

ShortableShares can be sliced along one dimension:

time : the time of day (in the bundle timezone) as of which shortable shares should be returned, formatted as HH:MM:SS, for example 08:45:00.

shares¶

number of shortable shares

Type: float

Examples

Get shortable shares as of 8:45 AM:

>>> shares = ibkr.ShortableShares.slice(time="08:45:00").shares.latest

Sharadar ¶

class zipline.pipeline.data.sharadar.SP500¶

Dataset representing membership in the S&P 500.

in_sp500¶

whether the security is a member of S&P 500

Type: bool

Examples

>>> in_sp500 = sharadar.SP500.in_sp500.latest

zipline.pipeline.data.sharadar.SharadarSP500¶: alias of zipline.pipeline.data.sharadar.SP500

class zipline.pipeline.data.sharadar.Fundamentals¶

DataSetFamily representing Sharadar fundamentals. In order to use the data in a pipeline, it must first be sliced to generate a regular pipeline DataSet.

Fundamentals can be sliced along two dimensions:

dimension : the choices are ARQ, ARY, ART, MRQ, MRY, MRT, where AR=As Reported, MR=Most Recent Reported, Q=Quarterly, Y=Annual, and T=Trailing Twelve Month.
period_offset : must be set to 0. In the future this dimension will allow requesting data from earlier periods.

REVENUE¶

Revenues - [Income Statement] Amount of Revenue recognized from goods sold; services rendered; insurance premiums; or other activities that constitute an earning process. Interest income for financial institutions is reported net of interest expense and provision for credit losses.

Type: float

COR¶

Cost of Revenue - [Income Statement] The aggregate cost of goods produced and sold and services rendered during the reporting period.

Type: float

SGNA¶

Selling General and Administrative Expense - [Income Statement] A component of [OpEx] representing the aggregate total costs related to selling a firm’s product and services; as well as all other general and administrative expenses. Direct selling expenses (for example; credit; warranty; and advertising) are expenses that can be directly linked to the sale of specific products. Indirect selling expenses are expenses that cannot be directly linked to the sale of specific products; for example telephone expenses; Internet; and postal charges. General and administrative expenses include salaries of non- sales personnel; rent; utilities; communication; etc.

Type: float

RND¶

Research and Development Expense - [Income Statement] A component of [OpEx] representing the aggregate costs incurred in a planned search or critical investigation aimed at discovery of new knowledge with the hope that such knowledge will be useful in developing a new product or service.

Type: float

OPEX¶

Operating Expenses - [Income Statement] Operating expenses represents the total expenditure on [SGnA]; [RnD] and other operating expense items; it excludes [CoR].

Type: float

INTEXP¶

Interest Expense - [Income Statement] Amount of the cost of borrowed funds accounted for as interest expense.

Type: float

TAXEXP¶

Income Tax Expense - [Income Statement] Amount of current income tax expense (benefit) and deferred income tax expense (benefit) pertaining to continuing operations.

Type: float

NETINCDIS¶

Net Loss Income from Discontinued Operations - [Income Statement] Amount of loss (income) from a disposal group; net of income tax; reported as a separate component of income.

Type: float

CONSOLINC¶

Consolidated Income - [Income Statement] The portion of profit or loss for the period; net of income taxes; which is attributable to the consolidated entity; before the deduction of [NetIncNCI].

Type: float

NETINCNCI¶

Net Income to Non-Controlling Interests - [Income Statement] The portion of income which is attributable to non-controlling interest shareholders; subtracted from [ConsolInc] in order to obtain [NetInc].

Type: float

NETINC¶

Net Income - [Income Statement] The portion of profit or loss for the period; net of income taxes; which is attributable to the parent after the deduction of [NetIncNCI] from [ConsolInc]; and before the deduction of [PrefDivIS].

Type: float

PREFDIVIS¶

Preferred Dividends Income Statement Impact - [Income Statement] Income statement item reflecting dividend payments to preferred stockholders. Subtracted from Net Income to Parent [NetInc] to obtain Net Income to Common Stockholders [NetIncCmn].

Type: float

NETINCCMN¶

Net Income Common Stock - [Income Statement] The amount of net income (loss) for the period due to common shareholders. Typically differs from [NetInc] to the parent entity due to the deduction of [PrefDivIS].

Type: float

EPS¶

Earnings per Basic Share - [Income Statement] Earnings per share as calculated and reported by the company. Approximates to the amount of [NetIncCmn] for the period per each [SharesWA] after adjusting for [ShareFactor].

Type: float

EPSDIL¶

Earnings per Diluted Share - [Income Statement] Earnings per diluted share as calculated and reported by the company. Approximates to the amount of [NetIncCmn] for the period per each [SharesWADil] after adjusting for [ShareFactor]..

Type: float

SHARESWA¶

Weighted Average Shares - [Income Statement] The weighted average number of shares or units issued and outstanding that are used by the company to calculate [EPS]; determined based on the timing of issuance of shares or units in the period.

Type: float

SHARESWADIL¶

Weighted Average Shares Diluted - [Income Statement] The weighted average number of shares or units issued and outstanding that are used by the company to calculate [EPSDil]; determined based on the timing of issuance of shares or units in the period.

Type: float

CAPEX¶

Capital Expenditure - [Cash Flow Statement] A component of [NCFI] representing the net cash inflow (outflow) associated with the acquisition & disposal of long-lived; physical & intangible assets that are used in the normal conduct of business to produce goods and services and are not intended for resale. Includes cash inflows/outflows to pay for construction of self-constructed assets & software.

Type: float

NCFBUS¶

Net Cash Flow - Business Acquisitions and Disposals - [Cash Flow Statement] A component of [NCFI] representing the net cash inflow (outflow) associated with the acquisition & disposal of businesses; joint-ventures; affiliates; and other named investments.

Type: float

NCFINV¶

Net Cash Flow - Investment Acquisitions and Disposals - [Cash Flow Statement] A component of [NCFI] representing the net cash inflow (outflow) associated with the acquisition & disposal of investments; including marketable securities and loan originations.

Type: float

NCFF¶

Net Cash Flow from Financing - [Cash Flow Statement] A component of [NCF] representing the amount of cash inflow (outflow) from financing activities; from continuing and discontinued operations. Principal components of financing cash flow are: issuance (purchase) of equity shares; issuance (repayment) of debt securities; and payment of dividends & other cash distributions.

Type: float

NCFDEBT¶

Issuance (Repayment) of Debt Securities - [Cash Flow Statement] A component of [NCFF] representing the net cash inflow (outflow) from issuance (repayment) of debt securities.

Type: float

NCFCOMMON¶

Issuance (Purchase) of Equity Shares - [Cash Flow Statement] A component of [NCFF] representing the net cash inflow (outflow) from common equity changes. Includes additional capital contributions from share issuances and exercise of stock options; and outflow from share repurchases.

Type: float

NCFDIV¶

Payment of Dividends & Other Cash Distributions - [Cash Flow Statement] A component of [NCFF] representing dividends and dividend equivalents paid on common stock and restricted stock units.

Type: float

NCFI¶

Net Cash Flow from Investing - [Cash Flow Statement] A component of [NCF] representing the amount of cash inflow (outflow) from investing activities; from continuing and discontinued operations. Principal components of investing cash flow are: capital (expenditure) disposal of equipment [CapEx]; business (acquisitions) disposition [NCFBus] and investment (acquisition) disposal [NCFInv].

Type: float

NCFO¶

Net Cash Flow from Operations - [Cash Flow Statement] A component of [NCF] representing the amount of cash inflow (outflow) from operating activities; from continuing and discontinued operations.

Type: float

NCFX¶

Effect of Exchange Rate Changes on Cash - [Cash Flow Statement] A component of Net Cash Flow [NCF] representing the amount of increase (decrease) from the effect of exchange rate changes on cash and cash equivalent balances held in foreign currencies.

Type: float

NCF¶

Net Cash Flow / Change in Cash & Cash Equivalents - [Cash Flow Statement] Principal component of the cash flow statement representing the amount of increase (decrease) in cash and cash equivalents. Includes [NCFO]; investing [NCFI] and financing [NCFF] for continuing and discontinued operations; and the effect of exchange rate changes on cash [NCFX].

Type: float

SBCOMP¶

Share Based Compensation - [Cash Flow Statement] A component of [NCFO] representing the total amount of noncash; equity-based employee remuneration. This may include the value of stock or unit options; amortization of restricted stock or units; and adjustment for officers’ compensation. As noncash; this element is an add back when calculating net cash generated by operating activities using the indirect method.

Type: float

DEPAMOR¶

Depreciation Amortization & Accretion - [Cash Flow Statement] A component of operating cash flow representing the aggregate net amount of depreciation; amortization; and accretion recognized during an accounting period. As a non-cash item; the net amount is added back to net income when calculating cash provided by or used in operations using the indirect method.

Type: float

ASSETS¶

Total Assets - [Balance Sheet] Sum of the carrying amounts as of the balance sheet date of all assets that are recognized. Major components are [CashnEq]; [Investments];[Intangibles]; [PPNENet];[TaxAssets] and [Receivables].

Type: float

CASHNEQ¶

Cash and Equivalents - [Balance Sheet] A component of [Assets] representing the amount of currency on hand as well as demand deposits with banks or financial institutions.

Type: float

INVESTMENTS¶

Investments - [Balance Sheet] A component of [Assets] representing the total amount of marketable and non-marketable securties; loans receivable and other invested assets.

Type: float

INVESTMENTSC¶

Investments Current - [Balance Sheet] The current portion of [Investments]; reported if the company operates a classified balance sheet that segments current and non-current assets.

Type: float

INVESTMENTSNC¶

Investments Non-Current - [Balance Sheet] The non-current portion of [Investments]; reported if the company operates a classified balance sheet that segments current and non-current assets.

Type: float

DEFERREDREV¶

Deferred Revenue - [Balance Sheet] A component of [Liabilities] representing the carrying amount of consideration received or receivable on potential earnings that were not recognized as revenue; including sales; license fees; and royalties; but excluding interest income.

Type: float

DEPOSITS¶

Deposit Liabilities - [Balance Sheet] A component of [Liabilities] representing the total of all deposit liabilities held; including foreign and domestic; interest and noninterest bearing. May include demand deposits; saving deposits; Negotiable Order of Withdrawal and time deposits among others.

Type: float

PPNENET¶

Property Plant & Equipment Net - [Balance Sheet] A component of [Assets] representing the amount after accumulated depreciation; depletion and amortization of physical assets used in the normal conduct of business to produce goods and services and not intended for resale.

Type: float

INVENTORY¶

Inventory - [Balance Sheet] A component of [Assets] representing the amount after valuation and reserves of inventory expected to be sold; or consumed within one year or operating cycle; if longer.

Type: float

TAXASSETS¶

Tax Assets - [Balance Sheet] A component of [Assets] representing tax assets and receivables.

Type: float

RECEIVABLES¶

Trade and Non-Trade Receivables - [Balance Sheet] A component of [Assets] representing trade and non-trade receivables.

Type: float

PAYABLES¶

Trade and Non-Trade Payables - [Balance Sheet] A component of [Liabilities] representing trade and non-trade payables.

Type: float

INTANGIBLES¶

Goodwill and Intangible Assets - [Balance Sheet] A component of [Assets] representing the carrying amounts of all intangible assets and goodwill as of the balance sheet date; net of accumulated amortization and impairment charges.

Type: float

LIABILITIES¶

Total Liabilities - [Balance Sheet] Sum of the carrying amounts as of the balance sheet date of all liabilities that are recognized. Principal components are [Debt]; [DeferredRev]; [Payables];[Deposits]; and [TaxLiabilities].

Type: float

EQUITY¶

Shareholders Equity - [Balance Sheet] A principal component of the balance sheet; in addition to [Liabilities] and [Assets]; that represents the total of all stockholders’ equity (deficit) items; net of receivables from officers; directors; owners; and affiliates of the entity which are attributable to the parent.

Type: float

RETEARN¶

Accumulated Retained Earnings (Deficit) - [Balance Sheet] A component of [Equity] representing the cumulative amount of the entities undistributed earnings or deficit. May only be reported annually by certain companies; rather than quarterly.

Type: float

ACCOCI¶

Accumulated Other Comprehensive Income - [Balance Sheet] A component of [Equity] representing the accumulated change in equity from transactions and other events and circumstances from non-owner sources; net of tax effect; at period end. Includes foreign currency translation items; certain pension adjustments; unrealized gains and losses on certain investments in debt and equity securities.

Type: float

ASSETSC¶

Current Assets - [Balance Sheet] The current portion of [Assets]; reported if a company operates a classified balance sheet that segments current and non-current assets.

Type: float

ASSETSNC¶

Assets Non-Current - [Balance Sheet] Amount of non-current assets; for companies that operate a classified balance sheet. Calculated as the different between Total Assets [Assets] and Current Assets [AssetsC].

Type: float

LIABILITIESC¶

Current Liabilities - [Balance Sheet] The current portion of [Liabilities]; reported if the company operates a classified balance sheet that segments current and non-current liabilities.

Type: float

LIABILITIESNC¶

Liabilities Non-Current - [Balance Sheet] The non-current portion of [Liabilities]; reported if the company operates a classified balance sheet that segments current and non-current liabilities.

Type: float

TAXLIABILITIES¶

Tax Liabilities - [Balance Sheet] A component of [Liabilities] representing outstanding tax liabilities.

Type: float

DEBT¶

Total Debt - [Balance Sheet] A component of [Liabilities] representing the total amount of current and non-current debt owed. Includes secured and unsecured bonds issued; commercial paper; notes payable; credit facilities; lines of credit; capital lease obligations; and convertible notes.

Type: float

DEBTC¶

Debt Current - [Balance Sheet] The current portion of [Debt]; reported if the company operates a classified balance sheet that segments current and non-current liabilities.

Type: float

DEBTNC¶

Debt Non-Current - [Balance Sheet] The non-current portion of [Debt] reported if the company operates a classified balance sheet that segments current and non-current liabilities.

Type: float

EBT¶

Earnings before Tax - [Metrics] Earnings Before Tax is calculated by adding [TaxExp] back to [NetInc].

Type: float

EBIT¶

Earning Before Interest & Taxes (EBIT) - [Income Statement] Earnings Before Interest and Tax is calculated by adding [TaxExp] and [IntExp] back to [NetInc].

Type: float

EBITDA¶

Earnings Before Interest Taxes & Depreciation Amortization (EBITDA) - [Metrics] EBITDA is a non-GAAP accounting metric that is widely used when assessing the performance of companies; calculated by adding [DepAmor] back to [EBIT].

Type: float

FXUSD¶

Foreign Currency to USD Exchange Rate - [Metrics] The exchange rate used for the conversion of foreign currency to USD for non-US companies that do not report in USD.

Type: float

EQUITYUSD¶

Shareholders Equity (USD) - [Balance Sheet] [Equity] in USD; converted by [FXUSD].

Type: float

EPSUSD¶

Earnings per Basic Share (USD) - [Income Statement] [EPS] in USD; converted by [FXUSD].

Type: float

REVENUEUSD¶

Revenues (USD) - [Income Statement] [Revenue] in USD; converted by [FXUSD].

Type: float

NETINCCMNUSD¶

Net Income Common Stock (USD) - [Income Statement] [NetIncCmn] in USD; converted by [FXUSD].

Type: float

CASHNEQUSD¶

Cash and Equivalents (USD) - [Balance Sheet] [CashnEq] in USD; converted by [FXUSD].

Type: float

DEBTUSD¶

Total Debt (USD) - [Balance Sheet] [Debt] in USD; converted by [FXUSD].

Type: float

EBITUSD¶

Earning Before Interest & Taxes (USD) - [Income Statement] [EBIT] in USD; converted by [FXUSD].

Type: float

EBITDAUSD¶

Earnings Before Interest Taxes & Depreciation Amortization (USD) - [Metrics] [EBITDA] in USD; converted by [FXUSD].

Type: float

SHARESBAS¶

Shares (Basic) - [Entity] The number of shares or other units outstanding of the entity’s capital or common stock or other ownership interests; as stated on the cover of related periodic report (10-K/10-Q); after adjustment for stock splits.

Type: float

DPS¶

Dividends per Basic Common Share - [Income Statement] Aggregate dividends declared during the period for each split-adjusted share of common stock outstanding. Includes spinoffs where identified.

Type: float

SHAREFACTOR¶

Share Factor - [Entity] Share factor is a multiplicant in the calculation of [MarketCap] and is used to adjust for: American Depository Receipts (ADRs) that represent more or less than 1 underlying share; and; companies which have different earnings share for different share classes (eg Berkshire Hathaway - BRKB).

Type: float

MARKETCAP¶

Market Capitalization - [Metrics] Represents the product of [SharesBas]; [Price] and [ShareFactor].

Type: float

EV¶

Enterprise Value - [Metrics] Enterprise value is a measure of the value of a business as a whole; calculated as [MarketCap] plus [DebtUSD] minus [CashnEqUSD].

Type: float

INVCAP¶

Invested Capital - [Metrics] Invested capital is an input into the calculation of [ROIC]; and is calculated as: [Debt] plus [Assets] minus [Intangibles] minus [CashnEq] minus [LiabilitiesC]. Please note this calculation method is subject to change.

Type: float

EQUITYAVG¶

Average Equity - [Metrics] Average equity value for the period used in calculation of [ROE]; derived from [Equity].

Type: float

ASSETSAVG¶

Average Assets - [Metrics] Average asset value for the period used in calculation of [ROE] and [ROA]; derived from [Assets].

Type: float

INVCAPAVG¶

Invested Capital Average - [Metrics] Average invested capital value for the period used in the calculation of [ROIC]; and derived from [InvCap]. Invested capital is an input into the calculation of [ROIC]; and is calculated as: [Debt] plus [Assets] minus [Intangibles] minus [CashnEq] minus [LiabilitiesC]. Please note this calculation method is subject to change.

Type: float

TANGIBLES¶

Tangible Asset Value - [Metrics] The value of tangibles assets calculated as the difference between [Assets] and [Intangibles].

Type: float

ROE¶

Return on Average Equity - [Metrics] Return on equity measures a corporation’s profitability by calculating the amount of [NetIncCmn] returned as a percentage of [EquityAvg].

Type: float

ROA¶

Return on Average Assets - [Metrics] Return on assets measures how profitable a company is [NetIncCmn] relative to its total assets [AssetsAvg].

Type: float

FCF¶

Free Cash Flow - [Metrics] Free Cash Flow is a measure of financial performance calculated as [NCFO] minus [CapEx].

Type: float

ROIC¶

Return on Invested Capital - [Metrics] Return on Invested Capital is ratio estimated by dividing [EBIT] by [InvCapAvg]. [InvCap] is calculated as: [Debt] plus [Assets] minus [Intangibles] minus [CashnEq] minus [LiabilitiesC]. Please note this calculation method is subject to change.

Type: float

GP¶

Gross Profit - [Income Statement] Aggregate revenue [Revenue] less cost of revenue [CoR] directly attributable to the revenue generation activity.

Type: float

OPINC¶

Operating Income - [Income Statement] Operating income is a measure of financial performance before the deduction of [IntExp]; [TaxExp] and other Non-Operating items. It is calculated as [GP] minus [OpEx].

Type: float

GROSSMARGIN¶

Gross Margin - [Metrics] Gross Margin measures the ratio between a company’s [GP] and [Revenue].

Type: float

NETMARGIN¶

Profit Margin - [Metrics] Measures the ratio between a company’s [NetIncCmn] and [Revenue].

Type: float

EBITDAMARGIN¶

EBITDA Margin - [Metrics] Measures the ratio between a company’s [EBITDA] and [Revenue].

Type: float

ROS¶

Return on Sales - [Metrics] Return on Sales is a ratio to evaluate a company’s operational efficiency; calculated by dividing [EBIT] by [Revenue]. ROS is often a component of DuPont ROE analysis.

Type: float

ASSETTURNOVER¶

Asset Turnover - [Metrics] Asset turnover is a measure of a firms operating efficiency; calculated by dividing [Revenue] by [AssetsAVG]. Often a component of DuPont ROE analysis.

Type: float

PAYOUTRATIO¶

Payout Ratio - [Metrics] The percentage of earnings paid as dividends to common stockholders. Calculated by dividing [DPS] by [EPSUSD].

Type: float

EVEBITDA¶

Enterprise Value over EBITDA - [Metrics] Measures the ratio between [EV] and [EBITDAUSD].

Type: float

EVEBIT¶

Enterprise Value over EBIT - [Metrics] Measures the ratio between [EV] and [EBITUSD].

Type: float

PE¶

Price Earnings (Damodaran Method) - [Metrics] Measures the ratio between [MarketCap] and [NetIncCmnUSD]

Type: float

PE1¶

Price to Earnings Ratio - [Metrics] An alternative to [PE] representing the ratio between [Price] and [EPSUSD].

Type: float

SPS¶

Sales per Share - [Metrics] Sales per Share measures the ratio between [RevenueUSD] and [SharesWA] as adjusted by [ShareFactor].

Type: float

PS1¶

Price to Sales Ratio - [Metrics] An alternative calculation method to [PS]; that measures the ratio between a company’s [Price] and it’s [SPS].

Type: float

PS¶

Price Sales (Damodaran Method) - [Metrics] Measures the ratio between [MarketCap] and [RevenueUSD].

Type: float

PB¶

Price to Book Value - [Metrics] Measures the ratio between [MarketCap] and [EquityUSD].

Type: float

DE¶

Debt to Equity Ratio - [Metrics] Measures the ratio between [Liabilities] and [Equity].

Type: float

DIVYIELD¶

Dividend Yield - [Metrics] Dividend Yield measures the ratio between a company’s [DPS] and its [Price].

Type: float

CURRENTRATIO¶

Current Ratio - [Metrics] The ratio between [AssetsC] and [LiabilitiesC]; for companies that operate a classified balance sheet.

Type: float

WORKINGCAPITAL¶

Working Capital - [Metrics] Working capital measures the difference between [AssetsC] and [LiabilitiesC].

Type: float

FCFPS¶

Free Cash Flow per Share - [Metrics] Free Cash Flow per Share is a valuation metric calculated by dividing [FCF] by [SharesWA] and [ShareFactor].

Type: float

BVPS¶

Book Value per Share - [Metrics] Measures the ratio between [Equity] and [SharesWA] as adjusted by [ShareFactor].

Type: float

TBVPS¶

Tangible Assets Book Value per Share - [Metrics] Measures the ratio between [Tangibles] and [SharesWA] as adjusted by [ShareFactor].

Type: float

PRICE¶

Share Price (Adjusted Close) - [Entity] The price per common share adjusted for stock splits but not adjusted for dividends; used in the computation of [PE1]; [PS1]; [DivYield] and [SPS].

Type: float

Examples

Select stocks with low enterprise multiples using quarterly fundamentals:

>>> have_low_enterprise_multiples = sharadar.Fundamentals.slice(dimension='ARQ', period_offset=0).EVEBITDA.latest.percentile_between(0, 20)

class zipline.pipeline.data.sharadar.Institutions¶

DataSetFamily representing Sharadar institutional ownership. In order to use the data in a pipeline, it must first be sliced to generate a regular pipeline DataSet.

Institutions can be sliced along one dimension:

period_offset : must be set to 0. In the future this dimension will allow requesting data from earlier quarters.

SHRHOLDERS¶

Number of Shareholders (Institutional) - The number of shareholders.

Type: float

CLLHOLDERS¶

Number of Call holders (Institutional) - The number of call holders.

Type: float

PUTHOLDERS¶

Number of Put holders (institutional) - The number of put holders.

Type: float

WNTHOLDERS¶

Number of Warrant holders (institutional) - The number of warrant holders.

Type: float

DBTHOLDERS¶

Number of Debt holders (institutional) - The number of debt holders.

Type: float

PRFHOLDERS¶

Number of Preferred Stock holders (institutional) - The number of preferred stock holders.

Type: float

FNDHOLDERS¶

Number of Fund holders (institutional) - The number of fund holders.

Type: float

UNDHOLDERS¶

Number of Unidentified Security type holders (institutional) - The number of unidentified security type holders.

Type: float

SHRUNITS¶

Number of Share Units held (institutional) - The total number of share units held.

Type: float

CLLUNITS¶

Number of Call Units held (institutional) - The total number of call units held.

Type: float

PUTUNITS¶

Number of Put Units held (institutional) - The total number of put units held.

Type: float

WNTUNITS¶

Number of Warrant Units held (institutional) - The total number of warrant units held.

Type: float

DBTUNITS¶

Number of Debt Units held (institutional) - The total number of debt units held.

Type: float

PRFUNITS¶

Number of Preferred Stock units held (institutional) - The total number of preferred stock units held.

Type: float

FNDUNITS¶

Number of Fund units held (institutional) - The total number of fund units held.

Type: float

UNDUNITS¶

Number of Unidentified Security type units held (institutional) - The total number of unidentified security type units held.

Type: float

SHRVALUE¶

Value of Share units held (institutional) - The total value of share units held.

Type: float

CLLVALUE¶

Value of Call units held (institutional) - The total value of call units held.

Type: float

PUTVALUE¶

Value of Put units held (institutional) - The total value of put units held.

Type: float

WNTVALUE¶

Value of Warrant units held (institutional) - The total value of warrant units held.

Type: float

DBTVALUE¶

Value of Debt units held (institutional) - The total value of debt units held.

Type: float

PRFVALUE¶

Value of Preferred Stock units held (institutional) - The total value of preferred stock units held.

Type: float

FNDVALUE¶

Value of Fund units held (institutional) - The total value of fund units held.

Type: float

UNDVALUE¶

Value of Unidentified Security type units held (institutional) - The total value of unidentified security type units held.

Type: float

TOTALVALUE¶

Total Value of all Security types held (institutional) - The total value of all security types held.

Type: float

PERCENTOFTOTAL¶

Percentage of Total Institutional Holdings for the Quarter - The percentage that the [TotalValue] of this line item constitutes of all institutional holdings for this quarter.

Type: float

Examples

Select stocks with large institutional ownership:

>>> have_inst_own = sharadar.Institutions.slice(period_offset=0).TOTALVALUE.latest.percentile_between(80, 100)

Reuters ¶

class zipline.pipeline.data.reuters.Financials¶

DataSetFamily representing Reuters financials. In order to use the data in a pipeline, it must first be sliced to generate a regular pipeline DataSet.

Financials can be sliced along two dimensions:

interim : True for interim financials and False for annual financials.
period_offset : must be set to 0. In the future this dimension will allow requesting data from earlier periods.

AACR¶

Accounts Receivable - Trade, Net

Type: float

ACAE¶

Cash & Equivalents

Type: float

ACSH¶

Cash

Type: float

ADEP¶

Accumulated Depreciation, Total

Type: float

AGWI¶

Goodwill, Net

Type: float

AINT¶

Intangibles, Net

Type: float

AITL¶

Total Inventory

Type: float

ALTR¶

Note Receivable - Long Term

Type: float

APPN¶

Property/Plant/Equipment, Total - Net

Type: float

APPY¶

Prepaid Expenses

Type: float

APTC¶

Property/Plant/Equipment, Total - Gross

Type: float

ASTI¶

Short Term Investments

Type: float

ATCA¶

Total Current Assets

Type: float

ATOT¶

Total Assets

Type: float

ATRC¶

Total Receivables, Net

Type: float

CEIA¶

Equity In Affiliates

Type: float

CGAP¶

U.S. GAAP Adjustment

Type: float

CIAC¶

Income Available to Com Excl ExtraOrd

Type: float

CMIN¶

Minority Interest

Type: float

DDPS1¶

DPS - Common Stock Primary Issue

Type: float

EIBT¶

Net Income Before Taxes

Type: float

ERAD¶

Research & Development

Type: float

ETOE¶

Total Operating Expense

Type: float

FCDP¶

Total Cash Dividends Paid

Type: float

FPRD¶

Issuance (Retirement) of Debt, Net

Type: float

FPSS¶

Issuance (Retirement) of Stock, Net

Type: float

FTLF¶

Cash from Financing Activities

Type: float

ITLI¶

Cash from Investing Activities

Type: float

LAEX¶

Accrued Expenses

Type: float

LAPB¶

Accounts Payable

Type: float

LCLD¶

Current Port. of LT Debt/Capital Leases

Type: float

LCLO¶

Capital Lease Obligations

Type: float

LLTD¶

Long Term Debt

Type: float

LMIN¶

Minority Interest

Type: float

LPBA¶

Payable/Accrued

Type: float

LSTD¶

Notes Payable/Short Term Debt

Type: float

LTCL¶

Total Current Liabilities

Type: float

LTLL¶

Total Liabilities

Type: float

LTTD¶

Total Long Term Debt

Type: float

NGLA¶

Gain (Loss) on Sale of Assets

Type: float

NIBX¶

Net Income Before Extra. Items

Type: float

NINC¶

Net Income

Type: float

OBDT¶

Deferred Taxes

Type: float

ONET¶

Net Income/Starting Line

Type: float

OTLO¶

Cash from Operating Activities

Type: float

QEDG¶

ESOP Debt Guarantee

Type: float

QPIC¶

Additional Paid-In Capital

Type: float

QRED¶

Retained Earnings (Accumulated Deficit)

Type: float

QTCO¶

Total Common Shares Outstanding

Type: float

QTEL¶

Total Liabilities & Shareholders’ Equity

Type: float

QTLE¶

Total Equity

Type: float

QTPO¶

Total Preferred Shares Outstanding

Type: float

QTSC¶

Treasury Stock - Common

Type: float

QUGL¶

Unrealized Gain (Loss)

Type: float

RTLR¶

Total Revenue

Type: float

SAMT¶

Amortization

Type: float

SANI¶

Total Adjustments to Net Income

Type: float

SBDT¶

Deferred Income Tax

Type: float

SCEX¶

Capital Expenditures

Type: float

SCIP¶

Cash Interest Paid

Type: float

SCMS¶

Common Stock, Total

Type: float

SCOR¶

Cost of Revenue, Total

Type: float

SCSI¶

Cash and Short Term Investments

Type: float

SCTP¶

Cash Taxes Paid

Type: float

SDAJ¶

Dilution Adjustment

Type: float

SDBF¶

Diluted EPS Excluding ExtraOrd Items

Type: float

SDED¶

Depreciation/Depletion

Type: float

SDNI¶

Diluted Net Income

Type: float

SDPR¶

Depreciation/Amortization

Type: float

SDWS¶

Diluted Weighted Average Shares

Type: float

SFCF¶

Financing Cash Flow Items

Type: float

SFEE¶

Foreign Exchange Effects

Type: float

SGRP¶

Gross Profit

Type: float

SICF¶

Other Investing Cash Flow Items, Total

Type: float

SINN¶

Interest Exp.(Inc.),Net-Operating, Total

Type: float

SINV¶

Long Term Investments

Type: float

SLTL¶

Other Liabilities, Total

Type: float

SNCC¶

Net Change in Cash

Type: float

SNCI¶

Non-Cash Items

Type: float

SNIN¶

Interest Inc.(Exp.),Net-Non-Op., Total

Type: float

SOCA¶

Other Current Assets, Total

Type: float

SOCF¶

Changes in Working Capital

Type: float

SOCL¶

Other Current liabilities, Total

Type: float

SOLA¶

Other Long Term Assets, Total

Type: float

SONT¶

Other, Net

Type: float

SOOE¶

Other Operating Expenses, Total

Type: float

SOPI¶

Operating Income

Type: float

SORE¶

Other Revenue, Total

Type: float

SOTE¶

Other Equity, Total

Type: float

SPRS¶

Preferred Stock - Non Redeemable, Net

Type: float

SREV¶

Revenue

Type: float

SRPR¶

Redeemable Preferred Stock, Total

Type: float

SSGA¶

Selling/General/Admin. Expenses, Total

Type: float

STBP¶

Tangible Book Value per Share, Common Eq

Type: float

STLD¶

Total Debt

Type: float

STXI¶

Total Extraordinary Items

Type: float

SUIE¶

Unusual Expense (Income)

Type: float

TIAT¶

Net Income After Taxes

Type: float

TTAX¶

Provision for Income Taxes

Type: float

VDES¶

Diluted Normalized EPS

Type: float

XNIC¶

Income Available to Com Incl ExtraOrd

Type: float

Examples

Create a CustomFactor for PB ratio, using annual financials:

>>> annual_financials = reuters.Financials.slice(interim=False, period_offset=0)
>>> class PriceBookRatio(CustomFactor):
        inputs = [
            EquityPricing.close,
            annual_financials.ATOT,  # total assets
            annual_financials.LTLL,  # total liabilities
            annual_financials.QTCO  # common shares outstanding
        ]
        window_length = 1
        def compute(self, today, assets, out, closes, tot_assets, tot_liabilities, shares_out):
            book_values_per_share = (tot_assets - tot_liabilities)/shares_out
            pb_ratios = closes/book_values_per_share
            out[:] = pb_ratios

class zipline.pipeline.data.reuters.Estimates¶

DataSetFamily representing Reuters estimates and actuals. In order to use the data in a pipeline, it must first be sliced to generate a regular pipeline DataSet.

Estimates can be sliced along three dimensions:

period_type : the choices are ‘Q’ for quarterly or ‘A’ for annual or ‘S’ for semi-annual.
field : the choices are ‘Actual’, ‘Mean’, ‘High’, ‘Low’, ‘Median’, ‘NumOfEst’, or ‘StdDev’. All fields except Actual refer to estimates.
period_offset : must be set to 0. In the future this dimension will allow requesting data from earlier periods.

BVPS¶

Book Value Per Share

Type: float

CAPEX¶

Capital Expenditure

Type: float

CPS¶

Cash Flow Per Share

Type: float

DPS¶

Dividend Per Share

Type: float

EBIT¶

Earnings Before Interest and Tax

Type: float

EBITDA¶

Earnings Before Interest, Taxes, Depreciation and Amortization

Type: float

EPS¶

Earnings Per Share Excluding Exceptional Items

Type: float

EPSEBG¶

Earnings Per Share Before Goodwill

Type: float

EPSREP¶

Earnings Per Share Reported

Type: float

FFO¶

Funds From Operations Per Share

Type: float

NAV¶

Net Asset Value Per Share

Type: float

NDEBT¶

Net Debt

Type: float

NPROFIT¶

Net Profit Excluding Exceptional Items

Type: float

NPROFITEBG¶

Net Profit Before Goodwill

Type: float

NPROFITREP¶

Net Profit Reported

Type: float

OPROFIT¶

Operating Profit

Type: float

PPROFIT¶

Pre-Tax Profit Excluding Exceptional Items

Type: float

PPROFITEBG¶

Pre-Tax Profit Before Goodwill

Type: float

PPROFITREP¶

Pre-Tax Profit Reported

Type: float

REVENUE¶

Revenue

Type: float

ROA¶

Return On Assets

Type: float

ROE¶

Return On Equity

Type: float

Examples

Select stocks with high book values, using quarterly actuals:

>>> have_high_bvps = reuters.Estimates.slice(period_type="Q", field="Actual", period_offset=0).BVPS.latest.percentile_between(80, 100)

Built-in Factors ¶

class zipline.pipeline.factors.AverageDollarVolume(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Average Daily Dollar Volume

Default Inputs: [EquityPricing.close, EquityPricing.volume]

Default Window Length: None

compute(today, assets, out, close, volume)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.factors.BollingerBands(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Bollinger Bands technical indicator. https://en.wikipedia.org/wiki/Bollinger_Bands

Default Inputs: zipline.pipeline.data.EquityPricing.close

Parameters

inputs (length-1 iterable[BoundColumn]) – The expression over which to compute bollinger bands.
window_length (int > 0) – Length of the lookback window over which to compute the bollinger bands.
k (float) – The number of standard deviations to add or subtract to create the upper and lower bands.

compute(today, assets, out, close, k)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.factors.BusinessDaysSincePreviousEvent(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), domain=sentinel('NotSpecified'), *args, **kwargs)¶

Abstract class for business days since a previous event. Returns the number of business days (not trading days!) since the most recent event date for each asset.

This doesn’t use trading days for symmetry with BusinessDaysUntilNextEarnings.

Assets which announced or will announce the event today will produce a value of 0.0. Assets that announced the event on the previous business day will produce a value of 1.0.

Assets for which the event date is NaT will produce a value of NaN.

Example

BusinessDaysSincePreviousEvent can be used to create an event-driven factor. For instance, you may want to only trade assets that have a data point with an asof_date in the last 5 business days. To do this, you can create a BusinessDaysSincePreviousEvent factor, supplying the relevant asof_date column from your dataset as input, like this:

# Factor computing number of days since most recent asof_date
# per asset.
days_since_event = BusinessDaysSincePreviousEvent(
    inputs=[MyDataset.asof_date]
)

# Filter returning True for each asset whose most recent asof_date
# was in the last 5 business days.
recency_filter = (days_since_event <= 5)

class zipline.pipeline.factors.BusinessDaysUntilNextEvent(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), domain=sentinel('NotSpecified'), *args, **kwargs)¶

Abstract class for business days since a next event. Returns the number of business days (not trading days!) until the next known event date for each asset.

This doesn’t use trading days because the trading calendar includes information that may not have been available to the algorithm at the time when compute is called.

For example, the NYSE closings September 11th 2001, would not have been known to the algorithm on September 10th.

Assets that announced or will announce the event today will produce a value of 0.0. Assets that will announce the event on the next upcoming business day will produce a value of 1.0.

Assets for which the event date is NaT will produce a value of NaN.

class zipline.pipeline.factors.DailyReturns(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Calculates daily percent change in close price.

Default Inputs: [EquityPricing.close]

class zipline.pipeline.factors.ExponentialWeightedMovingAverage(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Exponentially Weighted Moving Average

Default Inputs: None

Default Window Length: None

Parameters

inputs (length-1 list/tuple of BoundColumn) – The expression over which to compute the average.
window_length (int > 0) – Length of the lookback window over which to compute the average.
decay_rate (float, 0 < decay_rate <= 1) –
Weighting factor by which to discount past observations.

When calculating historical averages, rows are multiplied by the sequence:
```
decay_rate, decay_rate ** 2, decay_rate ** 3, ...
```

Notes

This class can also be imported under the name EWMA.

See also

pandas.DataFrame.ewm()

compute(today, assets, out, data, decay_rate)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.factors.ExponentialWeightedMovingStdDev(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Exponentially Weighted Moving Standard Deviation

Default Inputs: None

Default Window Length: None

Parameters

inputs (length-1 list/tuple of BoundColumn) – The expression over which to compute the average.
window_length (int > 0) – Length of the lookback window over which to compute the average.
decay_rate (float, 0 < decay_rate <= 1) –
Weighting factor by which to discount past observations.

When calculating historical averages, rows are multiplied by the sequence:
```
decay_rate, decay_rate ** 2, decay_rate ** 3, ...
```

Notes

This class can also be imported under the name EWMSTD.

See also

pandas.DataFrame.ewm()

compute(today, assets, out, data, decay_rate)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.factors.Latest(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Factor producing the most recently-known value of inputs[0] on each day.

The .latest attribute of DataSet columns returns an instance of this Factor.

compute(today, assets, out, data)¶: Override this method with a function that writes a value into out.

zipline.pipeline.factors.MACDSignal¶: alias of zipline.pipeline.factors.technical.MovingAverageConvergenceDivergenceSignal

class zipline.pipeline.factors.MaxDrawdown(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Max Drawdown

Default Inputs: None

Default Window Length: None

compute(today, assets, out, data)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.factors.Returns(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Calculates the percent change in close price over the given window_length.

Default Inputs: [EquityPricing.close]

compute(today, assets, out, close)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.factors.RollingLinearRegressionOfReturns(target, returns_length, regression_length, mask=sentinel('NotSpecified'))¶

Perform an ordinary least-squares regression predicting the returns of all other assets on the given asset.

Parameters

target (zipline.assets.Asset) – The asset to regress against all other assets.
returns_length (int >= 2) – Length of the lookback window over which to compute returns. Daily returns require a window length of 2.
regression_length (int >= 1) – Length of the lookback window over which to compute each regression.
mask (zipline.pipeline.Filter, optional) – A Filter describing which assets should be regressed against the target asset each day.

Notes

Computing this factor over many assets can be time consuming. It is recommended that a mask be used in order to limit the number of assets over which regressions are computed.

This factor is designed to return five outputs:

alpha, a factor that computes the intercepts of each regression.
beta, a factor that computes the slopes of each regression.
r_value, a factor that computes the correlation coefficient of each regression.
p_value, a factor that computes, for each regression, the two-sided p-value for a hypothesis test whose null hypothesis is that the slope is zero.
stderr, a factor that computes the standard error of the estimate of each regression.

For more help on factors with multiple outputs, see zipline.pipeline.CustomFactor.

Examples

Let the following be example 10-day returns for three different assets:

               SPY    MSFT     FB
2017-03-13    -.03     .03    .04
2017-03-14    -.02    -.03    .02
2017-03-15    -.01     .02    .01
2017-03-16       0    -.02    .01
2017-03-17     .01     .04   -.01
2017-03-20     .02    -.03   -.02
2017-03-21     .03     .01   -.02
2017-03-22     .04    -.02   -.02

Suppose we are interested in predicting each stock’s returns from SPY’s over rolling 5-day look back windows. We can compute rolling regression coefficients (alpha and beta) from 2017-03-17 to 2017-03-22 by doing:

regression_factor = RollingRegressionOfReturns(
    target=sid(8554),
    returns_length=10,
    regression_length=5,
)
alpha = regression_factor.alpha
beta = regression_factor.beta

The result of computing alpha from 2017-03-17 to 2017-03-22 gives:

               SPY    MSFT     FB
2017-03-17       0    .011   .003
2017-03-20       0   -.004   .004
2017-03-21       0    .007   .006
2017-03-22       0    .002   .008

And the result of computing beta from 2017-03-17 to 2017-03-22 gives:

               SPY    MSFT     FB
2017-03-17       1      .3   -1.1
2017-03-20       1      .2     -1
2017-03-21       1     -.3     -1
2017-03-22       1     -.3    -.9

Note that SPY’s column for alpha is all 0’s and for beta is all 1’s, as the regression line of SPY with itself is simply the function y = x.

To understand how each of the other values were calculated, take for example MSFT’s alpha and beta values on 2017-03-17 (.011 and .3, respectively). These values are the result of running a linear regression predicting MSFT’s returns from SPY’s returns, using values starting at 2017-03-17 and looking back 5 days. That is, the regression was run with x = [-.03, -.02, -.01, 0, .01] and y = [.03, -.03, .02, -.02, .04], and it produced a slope of .3 and an intercept of .011.

class zipline.pipeline.factors.RollingPearsonOfReturns(target, returns_length, correlation_length, mask=sentinel('NotSpecified'))¶

Calculates the Pearson product-moment correlation coefficient of the returns of the given asset with the returns of all other assets.

Pearson correlation is what most people mean when they say “correlation coefficient” or “R-value”.

Parameters

target (zipline.assets.Asset) – The asset to correlate with all other assets.
returns_length (int >= 2) – Length of the lookback window over which to compute returns. Daily returns require a window length of 2.
correlation_length (int >= 1) – Length of the lookback window over which to compute each correlation coefficient.
mask (zipline.pipeline.Filter, optional) – A Filter describing which assets should have their correlation with the target asset computed each day.

Notes

Computing this factor over many assets can be time consuming. It is recommended that a mask be used in order to limit the number of assets over which correlations are computed.

Examples

Let the following be example 10-day returns for three different assets:

               SPY    MSFT     FB
2017-03-13    -.03     .03    .04
2017-03-14    -.02    -.03    .02
2017-03-15    -.01     .02    .01
2017-03-16       0    -.02    .01
2017-03-17     .01     .04   -.01
2017-03-20     .02    -.03   -.02
2017-03-21     .03     .01   -.02
2017-03-22     .04    -.02   -.02

Suppose we are interested in SPY’s rolling returns correlation with each stock from 2017-03-17 to 2017-03-22, using a 5-day look back window (that is, we calculate each correlation coefficient over 5 days of data). We can achieve this by doing:

rolling_correlations = RollingPearsonOfReturns(
    target=sid(8554),
    returns_length=10,
    correlation_length=5,
)

The result of computing rolling_correlations from 2017-03-17 to 2017-03-22 gives:

               SPY   MSFT     FB
2017-03-17       1    .15   -.96
2017-03-20       1    .10   -.96
2017-03-21       1   -.16   -.94
2017-03-22       1   -.16   -.85

Note that the column for SPY is all 1’s, as the correlation of any data series with itself is always 1. To understand how each of the other values were calculated, take for example the .15 in MSFT’s column. This is the correlation coefficient between SPY’s returns looking back from 2017-03-17 (-.03, -.02, -.01, 0, .01) and MSFT’s returns (.03, -.03, .02, -.02, .04).

class zipline.pipeline.factors.RollingSpearmanOfReturns(target, returns_length, correlation_length, mask=sentinel('NotSpecified'))¶

Calculates the Spearman rank correlation coefficient of the returns of the given asset with the returns of all other assets.

Parameters

target (zipline.assets.Asset) – The asset to correlate with all other assets.
returns_length (int >= 2) – Length of the lookback window over which to compute returns. Daily returns require a window length of 2.
correlation_length (int >= 1) – Length of the lookback window over which to compute each correlation coefficient.
mask (zipline.pipeline.Filter, optional) – A Filter describing which assets should have their correlation with the target asset computed each day.

Notes

Computing this factor over many assets can be time consuming. It is recommended that a mask be used in order to limit the number of assets over which correlations are computed.

class zipline.pipeline.factors.SimpleBeta(target, regression_length, allowed_missing_percentage=0.25)¶

Factor producing the slope of a regression line between each asset’s daily returns to the daily returns of a single “target” asset.

Parameters

target (zipline.Asset) – Asset against which other assets should be regressed.
regression_length (int) – Number of days of daily returns to use for the regression.
allowed_missing_percentage (float, optional) – Percentage of returns observations (between 0 and 1) that are allowed to be missing when calculating betas. Assets with more than this percentage of returns observations missing will produce values of NaN. Default behavior is that 25% of inputs can be missing.

compute(today, assets, out, all_returns, target_returns, allowed_missing_count)¶: Override this method with a function that writes a value into out.

graph_repr()¶: Short repr to use when rendering Pipeline graphs.

property target¶: Get the target of the beta calculation.

class zipline.pipeline.factors.RSI(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Relative Strength Index

Default Inputs: zipline.pipeline.data.EquityPricing.close

Default Window Length: 15

compute(today, assets, out, closes)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.factors.SimpleMovingAverage(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Average Value of an arbitrary column

Default Inputs: None

Default Window Length: None

compute(today, assets, out, data)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.factors.VWAP(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Volume Weighted Average Price

Default Inputs: [EquityPricing.close, EquityPricing.volume]

Default Window Length: None

class zipline.pipeline.factors.WeightedAverageValue(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Helper for VWAP-like computations.

Default Inputs: None

Default Window Length: None

compute(today, assets, out, base, weight)¶: Override this method with a function that writes a value into out.

Built-in Filters ¶

class zipline.pipeline.filters.All(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

A Filter requiring that assets produce True for window_length consecutive days.

Default Inputs: None

Default Window Length: None

compute(today, assets, out, arg)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.filters.AllPresent(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

Pipeline filter indicating input term has data for a given window.

compute(today, assets, out, value)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.filters.Any(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

A Filter requiring that assets produce True for at least one day in the last window_length days.

Default Inputs: None

Default Window Length: None

compute(today, assets, out, arg)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.filters.AtLeastN(inputs=sentinel('NotSpecified'), outputs=sentinel('NotSpecified'), window_length=sentinel('NotSpecified'), mask=sentinel('NotSpecified'), dtype=sentinel('NotSpecified'), missing_value=sentinel('NotSpecified'), ndim=sentinel('NotSpecified'), **kwargs)¶

A Filter requiring that assets produce True for at least N days in the last window_length days.

Default Inputs: None

Default Window Length: None

compute(today, assets, out, arg, N)¶: Override this method with a function that writes a value into out.

class zipline.pipeline.filters.SingleAsset(asset)¶

A Filter that computes to True only for the given asset.

graph_repr()¶: A short repr to use when rendering GraphViz graphs.

class zipline.pipeline.filters.StaticAssets(assets)¶

A Filter that computes True for a specific set of predetermined assets.

StaticAssets is mostly useful for debugging or for interactively computing pipeline terms for a fixed set of assets that are known ahead of time.

Parameters: assets (iterable[Asset]) – An iterable of assets for which to filter.

class zipline.pipeline.filters.StaticSids(sids)¶

A Filter that computes True for a specific set of predetermined sids.

StaticSids is mostly useful for debugging or for interactively computing pipeline terms for a fixed set of sids that are known ahead of time.

Parameters: sids (iterable[int]) – An iterable of sids for which to filter.

class zipline.pipeline.filters.master.Universe(code)¶

A filter limiting to assets that are members of a universe.

Parameters: code (str, required) – the universe code

Examples

Limit to a universe of energy stocks:

>>> from zipline_extensions.pipeline.filters import Universe
>>> pipe = Pipeline(screen=Universe("energy-stk"))

compute(today, assets, out, real_sids, **params)¶: Override this method with a function that writes a value into out.

API Reference

Tip: get help directly from the CLI/Python client

quantrocket.account

subcommands¶

Sub-commands:¶

balance¶

Named Arguments¶

filtering options¶

output options¶

portfolio¶

filtering options¶

output options¶

rates¶

filtering options¶

output options¶

Resource Group ¶

Account Balances ¶

Get Account BalancesGET/account/balances.{output}{?start_date,end_date,latest,accounts,below,fields,force_refresh}

Example URI

Headers

Body

Exchange rates ¶

Get Exchange RatesGET/account/rates.{output}{?start_date,end_date,latest,base_currencies,quote_currencies}

Example URI

Headers

Body

Account Portfolio ¶

Get Account PortfolioGET/account/portfolio.{output}{?brokers,accounts,sec_types,exchanges,sids,symbols,include_zero,fields}

Example URI

Headers

quantrocket.blotter

subcommands¶

Sub-commands:¶

order¶

Named Arguments¶

cancel¶

Named Arguments¶

status¶

filtering options¶

output options¶

positions¶

filtering options¶

output options¶

close¶

filtering options¶

output options¶

executions¶

filtering options¶

output options¶

pnl¶

filtering options¶

output options¶

Resource Group ¶

Orders ¶

Place OrdersPOST/blotter/orders

Example URI

Headers

Body

Headers

Body

Headers

Body

Get Order StatusGET/blotter/orders{output}{?order_ids,sids,order_refs,accounts,open_orders,start_date,end_date,fields}

Example URI

Headers

Headers

Cancel OrdersDELETE/blotter/orders{?order_ids,sids,order_refs,accounts,cancel_all}

Example URI

Headers

Body

Positions ¶

Get PositionsGET/blotter/positions.{output}{?sids,order_refs,accounts,view,diff}

Example URI

Headers

Headers

Close PositionsDELETE/blotter/positions.{output}{?sids,order_refs,accounts,params}

Example URI

Headers

Headers

Executions ¶

Get Account Balances
GET`/account/balances.{output}{?start_date,end_date,latest,accounts,below,fields,force_refresh}`

Get Exchange Rates
GET`/account/rates.{output}{?start_date,end_date,latest,base_currencies,quote_currencies}`

Get Account Portfolio
GET`/account/portfolio.{output}{?brokers,accounts,sec_types,exchanges,sids,symbols,include_zero,fields}`

Place Orders
POST`/blotter/orders`

Get Order Status
GET`/blotter/orders{output}{?order_ids,sids,order_refs,accounts,open_orders,start_date,end_date,fields}`

Cancel Orders
DELETE`/blotter/orders{?order_ids,sids,order_refs,accounts,cancel_all}`

Get Positions
GET`/blotter/positions.{output}{?sids,order_refs,accounts,view,diff}`

Close Positions
DELETE`/blotter/positions.{output}{?sids,order_refs,accounts,params}`

Get Executions
GET`/blotter/executions.{output}{?sids,order_refs,accounts,start_date,end_date}`

Get PNL
GET`/blotter/pnl.{output}{?sids,order_refs,accounts,start_date,end_date,timezone,details}`

Clone Git Repo
POST`/repo{?repo,branch,replace,skip_existing}`

Get Crontab
GET`/{service}/crontab`

Load Crontab
PUT`/{service}/crontab`

Get Timezone
GET`/{service}/timezone`

Set Timezone
PUT`/{service}/timezone{?tz}`

List Databases
GET`/db/databases{?services,codes,detail,expand}`