diff --git a/zipline/algorithm.py b/zipline/algorithm.py index 60f572a7..c43417b2 100644 --- a/zipline/algorithm.py +++ b/zipline/algorithm.py @@ -110,73 +110,76 @@ DEFAULT_CAPITAL_BASE = float("1.0e5") class TradingAlgorithm(object): - """ - Base class for trading algorithms. Inherit and overload - initialize() and handle_data(data). - - A new algorithm could look like this: - ``` - from zipline.api import order, symbol - - def initialize(context): - context.sid = symbol('AAPL') - context.amount = 100 - - def handle_data(context, data): - sid = context.sid - amount = context.amount - order(sid, amount) - ``` - To then to run this algorithm pass these functions to - TradingAlgorithm: - - my_algo = TradingAlgorithm(initialize, handle_data) - stats = my_algo.run(data) + """A class that represents a trading strategy and parameters to execute + the strategy. + Parameters + ---------- + *args, **kwargs + Forwarded to ``initialize`` unless listed below. + initialize : callable[context -> None], optional + Function that is called at the start of the simulation to + setup the initial context. + handle_data : callable[(context, data) -> None], optional + Function called on every bar. This is where most logic should be + implemented. + before_trading_start : callable[(context, data) -> None], optional + Function that is called before any bars have been processed each + day. + analyze : callable[(context, DataFrame) -> None], optional + Function that is called at the end of the backtest. This is passed + the context and the performance results for the backtest. + script : str, optional + Algoscript that contains the definitions for the four algorithm + lifecycle functions and any supporting code. + namespace : dict, optional + The namespace to execute the algoscript in. By default this is an + empty namespace that will include only python built ins. + algo_filename : str, optional + The filename for the algoscript. This will be used in exception + tracebacks. default: ''. + data_frequency : {'daily', 'minute'}, optional + The duration of the bars. + capital_base : float, optional + How much capital to start with. default: 1.0e5 + instant_fill : bool, optional + Whether to fill orders immediately or on next bar. default: False + equities_metadata : dict or DataFrame or file-like object, optional + If dict is provided, it must have the following structure: + * keys are the identifiers + * values are dicts containing the metadata, with the metadata + field name as the key + If pandas.DataFrame is provided, it must have the + following structure: + * column names must be the metadata fields + * index must be the different asset identifiers + * array contents should be the metadata value + If an object with a ``read`` method is provided, ``read`` must + return rows containing at least one of 'sid' or 'symbol' along + with the other metadata fields. + futures_metadata : dict or DataFrame or file-like object, optional + The same layout as ``equities_metadata`` except that it is used + for futures information. + identifiers : list, optional + Any asset identifiers that are not provided in the + equities_metadata, but will be traded by this TradingAlgorithm. + get_pipeline_loader : callable[BoundColumn -> PipelineLoader], optional + The function that maps pipeline columns to their loaders. + create_event_context : callable[BarData -> context manager], optional + A function used to create a context mananger that wraps the + execution of all events that are scheduled for a bar. + This function will be passed the data for the bar and should + return the actual context manager that will be entered. + history_container_class : type, optional + The type of history container to use. default: HistoryContainer + platform : str, optional + The platform the simulation is running on. This can be queried for + in the simulation with ``get_environment``. This allows algorithms + to conditionally execute code based on platform it is running on. + default: 'zipline' """ def __init__(self, *args, **kwargs): - """Initialize sids and other state variables. - - :Arguments: - :Optional: - initialize : function - Function that is called with a single - argument at the begninning of the simulation. - handle_data : function - Function that is called with 2 arguments - (context and data) on every bar. - script : str - Algoscript that contains initialize and - handle_data function definition. - data_frequency : {'daily', 'minute'} - The duration of the bars. - capital_base : float - How much capital to start with. - instant_fill : bool - Whether to fill orders immediately or on next bar. - asset_finder : An AssetFinder object - A new AssetFinder object to be used in this TradingEnvironment - equities_metadata : can be either: - - dict - - pandas.DataFrame - - object with 'read' property - If dict is provided, it must have the following structure: - * keys are the identifiers - * values are dicts containing the metadata, with the metadata - field name as the key - If pandas.DataFrame is provided, it must have the - following structure: - * column names must be the metadata fields - * index must be the different asset identifiers - * array contents should be the metadata value - If an object with a 'read' property is provided, 'read' must - return rows containing at least one of 'sid' or 'symbol' along - with the other metadata fields. - identifiers : List - Any asset identifiers that are not provided in the - equities_metadata, but will be traded by this TradingAlgorithm - """ self.sources = [] # List of trading controls to be used to validate orders.