API Reference

Running a Backtest

catalyst.run_algorithm(...)

Run a trading algorithm.

Parameters:

start : datetime

The start date of the backtest.

end : datetime

The end date of the backtest..

initialize : callable[context -> None]

The initialize function to use for the algorithm. This is called once at the very begining of the backtest and should be used to set up any state needed by the algorithm.

capital_base : float

The starting capital for the backtest.

handle_data : callable[(context, BarData) -> None], optional

The handle_data function to use for the algorithm. This is called every minute when data_frequency == 'minute' or every day when data_frequency == 'daily'.

before_trading_start : callable[(context, BarData) -> None], optional

The before_trading_start function for the algorithm. This is called once before each trading day (after initialize on the first day).

analyze : callable[(context, pd.DataFrame) -> None], optional

The analyze function to use for the algorithm. This function is called once at the end of the backtest and is passed the context and the performance data.

data_frequency : {‘daily’, ‘minute’}, optional

The data frequency to run the algorithm at.

data : pd.DataFrame, pd.Panel, or DataPortal, optional

The ohlcv data to run the backtest with. This argument is mutually exclusive with: bundle bundle_timestamp

bundle : str, optional

The name of the data bundle to use to load the data to run the backtest with. This defaults to ‘quantopian-quandl’. This argument is mutually exclusive with data.

bundle_timestamp : datetime, optional

The datetime to lookup the bundle data for. This defaults to the current time. This argument is mutually exclusive with data.

default_extension : bool, optional

Should the default catalyst extension be loaded. This is found at $CATALYST_ROOT/extension.py

extensions : iterable[str], optional

The names of any other extensions to load. Each element may either be a dotted module path like a.b.c or a path to a python file ending in .py like a/b/c.py.

strict_extensions : bool, optional

Should the run fail if any extensions fail to load. If this is false, a warning will be raised instead.

environ : mapping[str -> str], optional

The os environment to use. Many extensions use this to get parameters. This defaults to os.environ.

live : bool, optional

Execute algorithm in live trading mode.

Returns:

perf : pd.DataFrame

The daily performance of the algorithm.

See also

catalyst.data.bundles.bundles

The available data bundles.

Algorithm API

The following methods are available for use in the initialize, handle_data, and before_trading_start API functions.

In all listed functions, the self argument is implicitly the currently-executing TradingAlgorithm instance.

Data Object

class catalyst.protocol.BarData

Provides methods to access spot value or history windows of price data. Also provides some utility methods to determine if an asset is alive, has recent trade data, etc.

This is what is passed as data to the handle_data function.

Parameters:

data_portal : DataPortal

Provider for bar pricing data.

simulation_dt_func : callable

Function which returns the current simulation time. This is usually bound to a method of TradingSimulation.

data_frequency : {‘minute’, ‘daily’}

The frequency of the bar data; i.e. whether the data is daily or minute bars

restrictions : catalyst.finance.asset_restrictions.Restrictions

Object that combines and returns restricted list information from multiple sources

universe_func : callable, optional

Function which returns the current ‘universe’. This is for backwards compatibility with older API concepts.

can_trade()

For the given asset or iterable of assets, returns true if all of the following are true: 1) 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)

2. (if we are in minute mode) the asset’s exchange is open at the

current simulation time or at the simulation calendar’s next market minute

3. there is a known last price for the asset.

Parameters:assets: Asset or iterable of assets Returns:can_trade : bool or pd.Series[bool] indexed by asset.

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 CME 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 CME is open but the NYSE is closed).

current()

Returns the current value of the given assets for the given fields at the current simulation time. Current values are the as-traded price and are usually not adjusted for events like splits or dividends (see notes for more information).

Parameters:

assets : Asset or iterable of Assets

fields : str or iterable[str].

Valid values are: “price”, “last_traded”, “open”, “high”, “low”, “close”, “volume”, or column names in files read by fetch_csv.

Returns:

current_value : Scalar, pandas Series, or pandas DataFrame.

See notes below.

Notes

If a single asset and a single field are passed in, a scalar float value is returned.

If a single asset and a list of fields are passed in, a pandas Series is returned whose indices are the fields, and whose values are scalar values for this asset for each field.

If a list of assets and a single field are passed in, a pandas Series is returned whose indices are the assets, and whose values are scalar values for each asset for the given field.

If a list of assets and a list of fields are passed in, a pandas DataFrame is returned, indexed by asset. The columns are the requested fields, filled with the scalar values for each asset for each field.

If the current simulation time is not a valid market time, we use the last market close instead.

“price” returns the last known close price of the asset. 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 before being returned.

“last_traded” returns the date of the last trade event of the asset, even if the asset has stopped trading. If there is no last known value, pd.NaT is returned.

“volume” returns the trade volume for the current simulation time. If there is no trade this minute, 0 is returned.

“open”, “high”, “low”, and “close” return the relevant information for the current trade bar. If there is no current trade bar, NaN is returned.

history()

Returns a window of data for the given assets and fields.

This data is adjusted for splits, dividends, and mergers as of the current algorithm time.

The semantics of missing data are identical to the ones described in the notes for get_spot_value.

Parameters:

assets: Asset or iterable of Asset

fields: string or iterable of string. Valid values are “open”, “high”,

“low”, “close”, “volume”, “price”, and “last_traded”.

bar_count: integer number of bars of trade data

frequency: string. “1m” for minutely data or “1d” for daily date

Returns:

history : Series or DataFrame or Panel

Return type depends on the dimensionality of the ‘assets’ and ‘fields’ parameters.

If single asset and field are passed in, the returned Series is indexed by dt.

If multiple assets and single field are passed in, the returned DataFrame is indexed by dt, and has assets as columns.

If a single asset and multiple fields are passed in, the returned DataFrame is indexed by dt, and has fields as columns.

If multiple assets and multiple fields are passed in, the returned Panel is indexed by field, has dt as the major axis, and assets as the minor axis.

Notes

If the current simulation time is not a valid market time, we use the last market close instead.

is_stale()

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: Asset or iterable of assets Returns:boolean or Series of booleans, indexed by asset.

Scheduling Functions

catalyst.api.schedule_function(self, func, date_rule=None, time_rule=None, half_days=True, calendar=None)

Schedules a function to be called according to some timed rules.

Parameters:

func : callable[(context, data) -> None]

The function to execute when the rule is triggered.

date_rule : EventRule, optional

The rule for the dates to execute this function.

time_rule : EventRule, optional

The rule for the times to execute this function.

half_days : bool, optional

Should this rule fire on half days?

calendar : Sentinel, optional

Calendar used to reconcile date and time rules.

See also

catalyst.api.date_rules, catalyst.api.time_rules

class catalyst.api.date_rules

every_day

alias of Always

static month_end(days_offset=0)

static month_start(days_offset=0)

static week_end(days_offset=0)

static week_start(days_offset=0)

class catalyst.api.time_rules

every_minute

alias of Always

market_close

alias of BeforeClose

market_open

alias of AfterOpen

Orders

catalyst.api.order(self, asset, amount, limit_price=None, stop_price=None, style=None)

Place an order.

Parameters:

asset : Asset

The asset that this order is for.

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 : str or None

The unique identifier for this order, or None if no order was placed.

See also

catalyst.finance.execution.ExecutionStyle, catalyst.api.order_value(), catalyst.api.order_percent()

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.

catalyst.api.order_value(self, asset, value, limit_price=None, stop_price=None, style=None)

Place an order by desired value rather than desired number of shares.

Parameters:

asset : Asset

The asset that this order is for.

value : float

If the requested asset exists, the requested value is divided by its price to imply the number of shares to transact. If the Asset being ordered is a Future, the ‘value’ calculated is actually the exposure, as Futures have no ‘value’.

value > 0 :: Buy/Cover value < 0 :: Sell/Short

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 : str

The unique identifier for this order.

See also

catalyst.finance.execution.ExecutionStyle, catalyst.api.order(), catalyst.api.order_percent()

Notes

See catalyst.api.order() for more information about limit_price, stop_price, and style

catalyst.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 porfolio 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 : str

The unique identifier for this order.

See also

catalyst.finance.execution.ExecutionStyle, catalyst.api.order(), catalyst.api.order_value()

Notes

See catalyst.api.order() for more information about limit_price, stop_price, and style

catalyst.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 : str

The unique identifier for this order.

See also

catalyst.finance.execution.ExecutionStyle, catalyst.api.order(), catalyst.api.order_target_percent(), catalyst.api.order_target_value()

Notes

order_target does not take into account any open orders. For example:

order_target(sid(0), 10)
order_target(sid(0), 10)

This code will result in 20 shares of sid(0) because the first call to order_target will not have been filled when the second order_target call is made.

See catalyst.api.order() for more information about limit_price, stop_price, and style

catalyst.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 : str

The unique identifier for this order.

See also

catalyst.finance.execution.ExecutionStyle, catalyst.api.order(), catalyst.api.order_target(), catalyst.api.order_target_percent()

Notes

order_target_value does not take into account any open orders. For example:

order_target_value(sid(0), 10)
order_target_value(sid(0), 10)

This code will result in 20 dollars of sid(0) because the first call to order_target_value will not have been filled when the second order_target_value call is made.

See catalyst.api.order() for more information about limit_price, stop_price, and style

catalyst.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 porfolio 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 : str

The unique identifier for this order.

See also

catalyst.finance.execution.ExecutionStyle, catalyst.api.order(), catalyst.api.order_target(), catalyst.api.order_target_value()

Notes

order_target_value does not take into account any open orders. For example:

order_target_percent(sid(0), 10)
order_target_percent(sid(0), 10)

This code will result in 20% of the portfolio being allocated to sid(0) because the first call to order_target_percent will not have been filled when the second order_target_percent call is made.

See catalyst.api.order() for more information about limit_price, stop_price, and style

class catalyst.finance.execution.ExecutionStyle

Abstract base class representing a modification to a standard order.

exchange

The exchange to which this order should be routed.

get_limit_price(is_buy)

Get the limit price for this order. Returns either None or a numerical value >= 0.

get_stop_price(is_buy)

Get the stop price for this order. Returns either None or a numerical value >= 0.

class catalyst.finance.execution.MarketOrder(exchange=None)

Class encapsulating an order to be placed at the current market price.

class catalyst.finance.execution.LimitOrder(limit_price, exchange=None)

Execution style representing an order to be executed at a price equal to or better than a specified limit price.

class catalyst.finance.execution.StopOrder(stop_price, exchange=None)

Execution style representing an order to be placed once the market price reaches a specified stop price.

class catalyst.finance.execution.StopLimitOrder(limit_price, stop_price, exchange=None)

Execution style representing a limit order to be placed with a specified limit price once the market reaches a specified stop price.

catalyst.api.get_order(self, order_id, exchange_name)

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 : Order

The order object.

execution_price: float

The execution price per share of the order

catalyst.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 : dict[list[Order]] or list[Order]

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.

catalyst.api.cancel_order(self, order_param, exchange_name, symbol=None, params={})

Cancel an open order.

Parameters:

order_param : str or Order

The order_id or order object to cancel.

exchange_name: name of exchange from

which you want to cancel the order

symbol:

params:

Order Cancellation Policies

catalyst.api.set_cancel_policy(self, cancel_policy)

Sets the order cancellation policy for the simulation.

Parameters:

cancel_policy : CancelPolicy

The cancellation policy to use.

See also

catalyst.api.EODCancel, catalyst.api.NeverCancel

class catalyst.finance.cancel_policy.CancelPolicy

Abstract cancellation policy interface.

should_cancel(event)

Should all open orders be cancelled?

Parameters:

event : enum-value

An event type, one of:

• catalyst.gens.sim_engine.BAR
• catalyst.gens.sim_engine.DAY_START
• catalyst.gens.sim_engine.DAY_END
• catalyst.gens.sim_engine.MINUTE_END

Returns:

should_cancel : bool

Should all open orders be cancelled?

catalyst.api.EODCancel(warn_on_cancel=True)

This policy cancels open orders at the end of the day. For now, Zipline will only apply this policy to minutely simulations.

Parameters:

warn_on_cancel : bool, optional

Should a warning be raised if this causes an order to be cancelled?

catalyst.api.NeverCancel()

Orders are never automatically canceled.

Assets

catalyst.api.symbol(self, symbol_str, exchange_name=None)

Lookup an Equity by its ticker symbol.

Parameters:

symbol_str : str

The ticker symbol for the equity to lookup.

exchange_name: str

The name of the exchange containing the symbol

Returns:

equity : Equity

The equity that held the ticker symbol on the current symbol lookup date.

Raises:

SymbolNotFound

Raised when the symbols was not held on the current lookup date.

See also

catalyst.api.set_symbol_lookup_date()

catalyst.api.symbols(self, *args)

Lookup multuple Equities as a list.

Parameters:

*args : iterable[str]

The ticker symbols to lookup.

Returns:

equities : list[Equity]

The equities that held the given ticker symbols on the current symbol lookup date.

Raises:

SymbolNotFound

Raised when one of the symbols was not held on the current lookup date.

See also

catalyst.api.set_symbol_lookup_date()

catalyst.api.set_symbol_lookup_date(self, dt)

Set the date for which symbols will be resolved to their assets (symbols may map to different firms or underlying assets at different times)

Parameters:

dt : datetime

The new symbol lookup date.

catalyst.api.sid(self, sid)

Lookup an Asset by its unique asset identifier.

Parameters:

sid : int

The unique integer that identifies an asset.

Returns:

asset : Asset

The asset with the given sid.

Raises:

SidsNotFound

When a requested sid does not map to any asset.

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.

catalyst.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.

catalyst.api.set_long_only(self, on_error='fail')

Set a rule specifying that this algorithm cannot take short positions.

catalyst.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.

catalyst.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.

catalyst.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.

catalyst.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.

Simulation Parameters

catalyst.api.set_benchmark(self, benchmark)

Set the benchmark asset.

Parameters:

benchmark : Asset

The asset to set as the new benchmark.

Notes

Any dividends payed out for that new benchmark asset will be automatically reinvested.

Commission Models

catalyst.api.set_commission(self, maker=None, taker=None)

class catalyst.finance.commission.CommissionModel

Abstract commission model interface.

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.

calculate(order, transaction)

Calculate the amount of commission to charge on order as a result of transaction.

Parameters:

order : catalyst.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 : catalyst.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 : float

The additional commission, in dollars, that we should attribute to this order.

class catalyst.finance.commission.PerShare(cost=0.0075, min_trade_cost=1.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.

min_trade_cost : float, optional

The minimum amount of commissions paid per trade.

class catalyst.finance.commission.PerTrade(cost=1.0)

Calculates a commission for a transaction based on a per trade cost.

Parameters:

cost : float, optional

The flat amount of commissions paid per equity trade.

class catalyst.finance.commission.PerDollar(cost=0.0015)

Calculates a commission for a transaction based on a per dollar cost.

Parameters:

cost : float

The flat amount of commissions paid per dollar of equities traded.

Slippage Models

catalyst.api.set_slippage(self, spread=None)

class catalyst.finance.slippage.SlippageModel

Abstract interface for defining a slippage model.

process_order(data, order)

Process how orders get filled.

Parameters:

data : BarData

The data for the given bar.

order : Order

The order to simulate.

Returns:

execution_price : float

The price to execute the trade at.

execution_volume : int

The number of shares that could be filled. This may not be all the shares ordered in which case the order will be filled over multiple bars.

class catalyst.finance.slippage.FixedSlippage(spread=0.0)

Model slippage as a fixed spread.

Parameters:

spread : float, optional

spread / 2 will be added to buys and subtracted from sells.

class catalyst.finance.slippage.VolumeShareSlippage(volume_limit=0.025, price_impact=0.1)

Model slippage as a function of the volume of contracts traded.

Pipeline

Not supported yet.

Miscellaneous

catalyst.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 performance packets and the performance dataframe passed to analyze and returned from run_algorithm().

catalyst.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:

arena : str

The arena from the simulation parameters. This will normally be backtest but some systems may use this distinguish live trading from backtesting.

data_frequency : {‘daily’, ‘minute’}

data_frequency tells the algorithm if it is running with daily or minute mode.

start : datetime

The start date for the simulation.

end : datetime

The end date for the simulation.

capital_base : float

The starting capital for the simulation.

platform : str

The platform that the code is running on. By default this will be the string ‘catalyst’. 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 : any

The value for the field queried. See above for more information.

Raises:

ValueError

Raised when field is not a valid option.

catalyst.api.fetch_csv(self, url, pre_func=None, post_func=None, date_column='date', date_format=None, timezone='UTC', symbol=None, mask=True, symbol_column=None, special_params_checker=None, **kwargs)

Fetch a csv from a remote url and register the data so that it is queryable from the data object.

Parameters:

url : str

The url of the csv file to load.

pre_func : callable[pd.DataFrame -> pd.DataFrame], optional

A callback to allow preprocessing the raw data returned from fetch_csv before dates are paresed or symbols are mapped.

post_func : callable[pd.DataFrame -> pd.DataFrame], optional

A callback to allow postprocessing of the data after dates and symbols have been mapped.

date_column : str, optional

The name of the column in the preprocessed dataframe containing datetime information to map the data.

date_format : str, optional

The format of the dates in the date_column. If not provided fetch_csv will attempt to infer the format. For information about the format of this string, see pandas.read_csv().

timezone : tzinfo or str, optional

The timezone for the datetime in the date_column.

symbol : str, optional

If the data is about a new asset or index then this string will be the name used to identify the values in data. For example, one may use fetch_csv to load data for VIX, then this field could be the string 'VIX'.

mask : bool, optional

Drop any rows which cannot be symbol mapped.

symbol_column : str

If the data is attaching some new attribute to each asset then this argument is the name of the column in the preprocessed dataframe containing the symbols. This will be used along with the date information to map the sids in the asset finder.

**kwargs

Forwarded to pandas.read_csv().

Returns:

csv_data_source : catalyst.sources.requests_csv.PandasRequestsCSV

A requests source that will pull data from the url specified.

Asset Metadata

class catalyst.assets.Asset(int sid, exchange, symbol='', asset_name='', start_date=None, end_date=None, first_traded=None, auto_close_date=None, exchange_full=None, min_trade_size=None)

first_traded

first_traded: object

from_dict(type cls, dict_)

Build an Asset instance from a dict.

is_alive_for_session(self, session_label)

Returns whether the asset is alive at the given dt.

Parameters:

session_label: pd.Timestamp

The desired session label to check. (midnight UTC)

Returns:

boolean: whether the asset is alive at the given dt.

is_exchange_open(self, dt_minute)

Parameters:

dt_minute: pd.Timestamp (UTC, tz-aware)

The minute to check.

Returns:

boolean: whether the asset’s exchange is open at the given minute.

to_dict(self)

Convert to a python dict.

class catalyst.assets.AssetConvertible

ABC for types that are convertible to integer-representations of Assets.

Includes Asset, six.string_types, and Integral

Trading Calendar API

catalyst.utils.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 : catalyst.utils.calendars.TradingCalendar

The desired calendar.

class catalyst.utils.calendars.TradingCalendar(start=Timestamp('1990-01-01 00:00:00+0000', tz='UTC'), end=Timestamp('2019-03-14 06:56:52.836488+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.

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:

bool

Whether the exchange is open on this dt.

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:

bool

Whether the given dt is a valid session label.

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:

pd.DatetimeIndex (UTC)

The list of session labels corresponding to the given minutes.

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:

pd.Timestamp (midnight UTC)

The label of the containing session.

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: The total number of minutes for the contiguous chunk of sessions.

between start_session and end_session, inclusive.

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:

pd.DateTimeIndex

All the minutes for the given session.

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:

pd.DatetimeIndex

The minutes in the desired range.

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:

pd.DatetimeIndex

The minutes in the desired range.

next_close(dt)

Given a dt, returns the next close.

Parameters:

dt: pd.Timestamp

The dt for which to get the next close.

Returns:

pd.Timestamp

The UTC timestamp of the next close.

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:

pd.Timestamp

The next exchange minute.

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:

pd.Timestamp

The UTC timestamp of the next open.

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:

pd.Timestamp

The next session label (midnight UTC).

Notes

Raises ValueError if the given session is the last session in this calendar.

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:

(Timestamp, Timestamp)

The open and close for the given session.

previous_close(dt)

Given a dt, returns the previous close.

Parameters:

dt: pd.Timestamp

The dt for which to get the previous close.

Returns:

pd.Timestamp

The UTC timestamp of the previous close.

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:

pd.Timestamp

The previous exchange minute.

previous_open(dt)

Given a dt, returns the previous open.

Parameters:

dt: pd.Timestamp

The dt for which to get the previous open.

Returns:

pd.Timestamp

The UTC imestamp of the previous open.

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:

pd.Timestamp

The previous session label (midnight UTC).

Notes

Raises ValueError if the given session is the first session in this calendar.

regular_holidays

Returns:

pd.AbstractHolidayCalendar: a calendar containing the regular holidays

for this calendar

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) would return 2.

Parameters:

start_session_label: pd.Timestamp

The label of the start session.

end_session_label: pd.Timestamp

The label of the ending session.

Returns:

int

The distance between the two sessions.

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:

pd.DatetimeIndex

The desired sessions.

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:

pd.DatetimeIndex

The desired sessions.

special_closes

A list of special close times and corresponding HolidayCalendars.

Returns:list: List of (time, AbstractHolidayCalendar) tuples

special_closes_adhoc

Returns:

list: List of (time, DatetimeIndex) tuples that represent special

closes that cannot be codified into rules.

special_opens

A list of special open times and corresponding HolidayCalendars.

Returns:list: List of (time, AbstractHolidayCalendar) tuples

special_opens_adhoc

Returns:

list: List of (time, DatetimeIndex) tuples that represent special

closes that cannot be codified into rules.

catalyst.utils.calendars.register_calendar(name, calendar, force=False)

Registers a calendar for retrieval by the get_calendar method.

Parameters:

name: str

The key with which to register this calendar.

calendar: TradingCalendar

The calendar to be registered for retrieval.

force : bool, optional

If True, old calendars will be overwritten on a name collision. If False, name collisions will raise an exception. Default is False.

Raises:

CalendarNameCollision

If a calendar is already registered with the given calendar’s name.

catalyst.utils.calendars.register_calendar_type(name, calendar_type, force=False)

Registers a calendar by type.

This is useful for registering a new calendar to be lazily instantiated at some future point in time.

Parameters:

name: str

The key with which to register this calendar.

calendar_type: type

The type of the calendar to register.

force : bool, optional

If True, old calendars will be overwritten on a name collision. If False, name collisions will raise an exception. Default is False.

Raises:

CalendarNameCollision

If a calendar is already registered with the given calendar’s name.

catalyst.utils.calendars.deregister_calendar(name)

If a calendar is registered with the given name, it is de-registered.

Parameters:

cal_name : str

The name of the calendar to be deregistered.

catalyst.utils.calendars.clear_calendars()

Deregisters all current registered calendars

Data API

Utilities

Caching

class catalyst.utils.cache.CachedObject(value, expires)

A simple struct for maintaining a cached object with an expiration date.

Parameters:

value : object

The object to cache.

expires : datetime-like

Expiration date of value. The cache is considered invalid for dates strictly greater than expires.

Examples

>>> from pandas import Timestamp, Timedelta
>>> expires = Timestamp('2014', tz='UTC')
>>> obj = CachedObject(1, expires)
>>> obj.unwrap(expires - Timedelta('1 minute'))
1
>>> obj.unwrap(expires)
1
>>> obj.unwrap(expires + Timedelta('1 minute'))
... 
Traceback (most recent call last):
    ...
Expired: 2014-01-01 00:00:00+00:00

class catalyst.utils.cache.ExpiringCache(cache=None)

A cache of multiple CachedObjects, which returns the wrapped the value or raises and deletes the CachedObject if the value has expired.

Parameters:

cache : dict-like, optional

An instance of a dict-like object which needs to support at least: __del__, __getitem__, __setitem__ If None, than a dict is used as a default.

Examples

>>> from pandas import Timestamp, Timedelta
>>> expires = Timestamp('2014', tz='UTC')
>>> value = 1
>>> cache = ExpiringCache()
>>> cache.set('foo', value, expires)
>>> cache.get('foo', expires - Timedelta('1 minute'))
1
>>> cache.get('foo', expires + Timedelta('1 minute'))
Traceback (most recent call last):
    ...
KeyError: 'foo'

class catalyst.utils.cache.dataframe_cache(path=None, lock=None, clean_on_failure=True, serialization='msgpack')

A disk-backed cache for dataframes.

dataframe_cache is a mutable mapping from string names to pandas DataFrame objects. This object may be used as a context manager to delete the cache directory on exit.

Parameters:

path : str, optional

The directory path to the cache. Files will be written as path/<keyname>.

lock : Lock, optional

Thread lock for multithreaded/multiprocessed access to the cache. If not provided no locking will be used.

clean_on_failure : bool, optional

Should the directory be cleaned up if an exception is raised in the context manager.

serialize : {‘msgpack’, ‘pickle:<n>’}, optional

How should the data be serialized. If 'pickle' is passed, an optional pickle protocol can be passed like: 'pickle:3' which says to use pickle protocol 3.

Notes

The syntax cache[:] will load all key:value pairs into memory as a dictionary. The cache uses a temporary file format that is subject to change between versions of catalyst.

class catalyst.utils.cache.working_file(final_path, *args, **kwargs)

A context manager for managing a temporary file that will be moved to a non-temporary location if no exceptions are raised in the context.

Parameters:

final_path : str

The location to move the file when committing.

*args, **kwargs

Forwarded to NamedTemporaryFile.

Notes

The file is moved on __exit__ if there are no exceptions. working_file uses shutil.move() to move the actual files, meaning it has as strong of guarantees as shutil.move().

class catalyst.utils.cache.working_dir(final_path, *args, **kwargs)

A context manager for managing a temporary directory that will be moved to a non-temporary location if no exceptions are raised in the context.

Parameters:

final_path : str

The location to move the file when committing.

*args, **kwargs

Forwarded to tmp_dir.

Notes

The file is moved on __exit__ if there are no exceptions. working_dir uses dir_util.copy_tree() to move the actual files, meaning it has as strong of guarantees as dir_util.copy_tree().

Command Line

catalyst.utils.cli.maybe_show_progress(it, show_progress, empty_char=' ', fill_char='=', bar_template=' [%(bar)s] %(label)s: %(info)s', **kwargs)

Optionally show a progress bar for the given iterator.

Parameters:

it : iterable

The underlying iterator.

show_progress : bool

Should progress be shown.

**kwargs

Forwarded to the click progress bar.

Returns:

itercontext : context manager

A context manager whose enter is the actual iterator to use.

Examples

with maybe_show_progress([1, 2, 3], True) as ns:
     for n in ns:
         ...