tsa::instrument Class Reference

Class instrument represents a tradeable security such as a stock, option, futures contract, currency, etc. Class instrument combines data-access with functionality for placing orders and managing positions. More...

#include <TSAInstrument.h>

Inheritance diagram for tsa::instrument:

Public Member Functions
void	allow_null_values (bool flag)
	Determines whether any incoming stream data is allowed to have 'null' ('N/A') values. If set to true, it is up to the user to explicitly check each value before using it. To check for null, values must be accessed as variants, not via auto-series. Use the variant::defined() member do check if the value is not null. More...
bool	allow_null_values (void) const
	Returns true if 'null' values are allowed in incoming stream data. More...
const std::vector< trade_info > &	closed_trades (void) const
	Returns information on all closed out trades.
double	current_drawdown (void) const
	Returns the size of the current equity drawdown for this instrument. If the strategy trades multiple instruments then each instrument will have its own drawdown measure. More...
const std::vector< trade_leg > &	current_trade_legs (void) const
	Returns a container with the current trade's 'legs'. More...
const std::vector< transaction > &	get_bar_transactions (void) const
	Returns a reference to a vectors containing the transactions that occured during the current bar. More...
void	set_next_bar (const date_time &, double o, double h, double l, double c, double v)
	Manually sets the next bar timestamp and ohlcv prices. Useful for writing test code. More...
Public Member Functions inherited from tsa::object
	object (void)
	Constructor.
virtual	~object (void)
	Destructor.
const char *	class_name (void) const
	Returns the class name as returned by the 'Real Time Type Information' (RTTI) mechanism. More...
bool	has_same_class_as (const object &other) const
	Returns true if self has the same type as other object. More...

Constructors / Destructor
	instrument (void)
	Constructor.
	~instrument (void)
	Destructor.

Identification
size_t	id (void) const
	Returns the instrument ID. Each instrument is assigned a unique number starting at zero.
bool	is_platform_driven (void) const
	Returns true if the strategy is attached to a platform_proxy or net::socket_base derived object. More...
bool	is_live (void) const
	Strategies driven by 'live' data can be started on 'backfill' data. Once the strategy has worked through the backfill records, it calls strategy::on_live() from which point onward the strategy switches to 'live' data and instrument::is_live() returns true. More...
bool	exception_on_backfill_orders (void) const
void	name (const std::string &name)
	Sets the instrument name. More...
const std::string &	name (void) const
	Returns the instrument name. More...

Data Stream
void	as_random_walk (duration bar_duration=duration::days(1))
	Tells the instrument to generate its own random walk sequence with intervals of bar_duration. More...
void	connect (const std::string &stream_name, const std::string &database_name="default")
	Sets the given stream as the instrument's data source. More...
std::string	stream_name (void) const
	Returns the name of the data stream to which the instrument is connected. More...
std::string	data_base_name (void) const
void	connect (in_stream_adaptor &adaptor)
	Connects this instrument object to the given in-stream-adaptor.
date_time	begin ()
	Returns the timestamp of the first record in the datasource to which this object is connected. More...
date_time	end ()
	Returns the timestamp of the last record in the datasource to which this object is connected. More...
const series_core &	operator() (size_t field_pos) const
	From records streamed from the data source this member returns the series corresponding to the given field_pos. More...
const series_core &	operator() (const std::string &field_name) const
	From records streamed from the data source this member returns the series corresponding to the given field_name. More...
size_t	field_count (void) const
	Returns the number of fields in records streamed from the connected datasource. More...
date_time	record_timestamp (void) const
	Returns the timestamp of the current record. More...
bool	field_exists (const std::string &field_name) const
	Returns true if a field with the given field_name exists in records coming from the data-source. More...
size_t	field_index (const std::string &field_name) const
	Return the zero based position of the field that has the given field_name. More...
tsa::type_t	field_type (const std::string &field_name) const
	Returns the field type of the field with the given field_name. More...

Auto Series
series< double >	open
	Built in series object corresponding to record field 'open'.
series< double >	high
	Built in series object corresponding to record field 'high'.
series< double >	low
	Built in series object corresponding to record field 'low'.
series< double >	close
	Built in series object corresponding to record field 'close'.
series< double >	volume
	Built in series object corresponding to record field 'volume'.
series< double >	bid
	Built in series object corresponding to record field 'bid'.
series< double >	ask
	Built in series object corresponding to record field 'ask'.
series< double >	bidsize
	Built in series object corresponding to record field 'bidsize'.
series< double >	asksize
	Built in series object corresponding to record field 'asksize'.
series< double >	last
	Built in series object corresponding to record field 'last'.
series< double >	price
	Built in series object corresponding to record field 'price'.
series< double >	value
	Built in series object corresponding to record field 'value'.
series< double >	openint
	Built in series object corresponding to record field 'openint'.

Settings
void	negative_prices_ok (bool neg_prices_ok)
	Sets a flag which if 'true' allows negative prices in fields 'open', 'high', 'low', 'close'. More...
bool	negative_prices_ok (void) const
	Returns true if negative prices are tolerated during strategy evaluation. More...
double	big_point (void) const
	The value (in local currency) of a 1 point change in the instrument's price. This calculated as follows: big_point_value = (1.0 / min_tick) * tick_value;. More...
void	tick (double min_tick, double tick_value, bool auto_round=true)
	Sets the value of the 'minimum tick' (the smallest possible price change for a given traded security) as well as the tick's cash value. More...
double	tick_size (void) const
	Returns the value of the smallest allowed price change (min_tick) as set via the tick() member. More...
double	tick_value (void) const
	Returns the cash value of the min_tick as set by via the tick() member. More...
double	ticks (int64_t multiplier) const
	Returns the price equivalent of a price tick multiplied by the given multiplier. More...
void	limit_fill_proviso (double proviso)
	Sets the 'limit fill proviso'. This value determines by what margin market prices must exceed a limit price for a limit order to be assumed filled as part of a simulation. This value can help make simulations more realistic. More...
double	limit_fill_proviso (void) const
	Returns the 'limit fill proviso'. More...
void	slippage (double slip)
	Sets the 'per side' or 'per transaction' slippage (by default it is interpreted as 'per-side' slippage. This can be changed via the cost_allocation() member). A realistic slippage setting helps make simulations more realistic by accounting for non-optimal fills. Slippage is only counted for stop and market orders. Limit orders never have slippage regardless of the slippage setting. Slippage can be reset during strategy evaluations to account for changes in volatility. More...
double	slippage (void) const
	Returns the slippage as set via the slippage(double slip) member. More...
void	commission (double comm)
	Sets the per-side / per-unit commission. Commission is allocated on a per-unit basis (the default) or on a per-transaction basis depending on what was set via the cost_allocation() member. More...
double	commission (void) const
	Returns the value set via the instrument::commission(double) member which is zero by default. More...
void	cost_allocation (cost_alloc_type t)
	Sets the cost-allocation type that affects how commission and slippage are accounted for during simulations. Valid values are: More...
bool	costs_allocated_per_unit (void) const
	Returns true if the cost allocation is set to 'per_unit' (the default). Returns false if 'per_transaction'. More...

Order Properties
std::string	platform (void) const
	Returns the name of the excution platform / broker.
instrument &	platform (const std::string &platform_name)
	Sets the name of the excution platform / broker. Note that different instrument objects can trade via different brokers. More...
std::string	broker (void) const
	Same functionality as platform() member.
instrument &	broker (const std::string &broker_name)
	Same functionality as platform(const std::string& platform_name) member. More...
std::string	feed (void) const
	Returns the name of the data feed to which the instrument is connected. More...
std::string	interval (void) const
	Returns the interval (bar) type and duration. Valid values look like '5MIN', '1SEC', '3TICK'. More...
instrument &	define (const std::string &symbol, const std::string &exchange, const std::string &platform)
	Use this member to identify the instrument. This is required for live trading via the server. More...
instrument &	symbol (const std::string &symb)
	Sets the instrument's symbol. Use the define() member instead unless you have a special requirement. More...
const std::string &	symbol (void) const
	Returns the symbol. It would return 'ES' even if 'ES:DEC15' was passed to the define() member.
instrument &	expiry (const std::string &expiry)
	Sets the contract expiry. Use the define() member instead to pass a symbol-expiry combination like 'ES:DEC15', unless you have a special requirement. More...
const std::string &	expiry (void) const
	Returns the contract expiry like 'DEC15'. More...
const std::string &	expiry_yyyymm (void) const
	Returns the contract expiry in yyyymm format like: 201512. More...
std::string	instrument::type (void) const
	Returns the instrument type like 'STK' or 'FUT'. More...
instrument &	exchange (const std::string &exch)
	Sets the instrument's exchange. Use the define() member instead unless there is a special requirement. More...
const std::string &	exchange (void) const
	Returns the instrument's exchange. More...
instrument &	currency (const std::string &ccy)
	Sets the instrument's currency. More...
const std::string &	currency (void) const
	Returns the instrument's currency. More...

Orders Creation and Transmission
The following member functions allow the creation and management of orders to buy and sell instruments on an exchange. Orders are sent off immediately unless the function name has an '_order' suffix, in which case the function returns an order_ref instance, refering to an unsent order, on which various properties can be modified before the order is sent by calling order_ref::send() member. Note that some properties, such as the one set by the order::tag() member, can still be changed even after an order has been sent to the exchange. This is so because the order 'tag' is not relevant to the exchange or broker. All properties relevant to order execution must be set before the order is sent.
void	default_time_in_force (order::time_in_force default_tif)
	Sets the default time-in-force, which determines order lifetime. More...
order_ref	buy (quantity_t quantity)
	Creates and immediately sends an order to buy 'at market' a given quantity of securities. More...
order_ref	buy (quantity_t quantity, double fixed_fill_price)
order_ref	buy_order (quantity_t quantity)
	Creates an order, without sending it, to buy 'at market' a given quantity of securities. More...
order_ref	sell (quantity_t quantity)
	Creates and immediately sends an order to sell 'at market' a given quantity of securities. More...
order_ref	sell (quantity_t quantity, double fixed_fill_price)
order_ref	sell_order (quantity_t quantity)
	Creates, without sending, an order to sell 'at market' a given quantity of securities. More...
order_ref	buy_stop (quantity_t quantity, double stop_price)
	Creates and immediately sends an order to buy a given quantity of securities at a the given stop_price. More...
order_ref	buy_stop_order (quantity_t quantity, double stop_price)
	Creates, without sending, an order to buy a given quantity of securities at the given stop_price. More...
order_ref	sell_stop (quantity_t quantity, double stop_price)
	Creates and immediately sends an order to sell a given quantity of securities at a the given stop_price. More...
order_ref	sell_stop_order (quantity_t quantity, double stop_price)
	Creates, without sending, an order to sell a given quantity of securities at the given stop_price. More...
order_ref	buy_stop_limit (quantity_t quantity, double stop_price, double price_limit)
	Creates and immediately sends an order to buy a given quantity of securities at the given stop_price with the given price_limit. More...
order_ref	buy_stop_limit_order (quantity_t quantity, double stop_price, double price_limit)
	Creates, without sending, an order to buy a given quantity of securities at the given stop_price with given price_limit. More...
order_ref	sell_stop_limit (quantity_t quantity, double stop_price, double price_limit)
	Creates and immediately sends an order to sell a given quantity of securities at the given stop_price with the given price_limit. More...
order_ref	sell_stop_limit_order (quantity_t quantity, double stop_price, double limit_price)
	Creates, without sending, an order to sell a given quantity of securities at the given stop_price with given price_limit. More...
order_ref	buy_limit (quantity_t quantity, double limit_price)
	Creates and immediately sends an order to buy a given quantity of securities at a the given limit_price. More...
order_ref	buy_limit_order (quantity_t quantity, double limit_price)
	Creates, without sending, an order to sell at given limit_price a given quantity of securities. More...
order_ref	sell_limit (quantity_t quantity, double limit_price)
	Creates and immediately sends an order to sell at given limit_price a given quantity of securities. More...
order_ref	sell_limit_order (quantity_t quantity, double limit_price)
	Creates, without sending, an order to sell at given limit_price a given quantity of securities. More...

Order Management
void	cancel_all_orders (void)
	Cancels all 'active' orders owned by this instrument.
void	cancel_order (identifier_t id)
	Cancels the order with t given order id. More...
bool	order_exists (identifier_t id) const
	Returns true if an order with the given id exists. More...
void	get_orders (std::vector< order_ref > &v, bool active_only=true) const
	Populates vector v with either all or only the 'active' orders depending on the given active_only flag. More...
bool	has_active_orders (void) const
	Checks if this instrument object has 'active' orders. More...
void	get_active_orders (std::vector< order_ref > &v, order::type _ot, order::action) const
	Populates vector v with all 'active' orders. More...
order_ref	get_order (identifier_t id) const
	Returns an order with given id. More...
order *	get_order_ptr (identifier_t id) const
	Returns a pointer to the order with given id. Note that it is unusual to access an order object directly. Normally orders should be handled via order_ref objects. More...
size_t	order_count (void) const
	Returns the number of 'active' orders. More...
size_t	order_count_inclusive () const
	Returns the number of orders, both 'active' and 'inactive'. Inactive orders may be marked for deletion. More...

Position and Profitability
double	net_profit (void) const
	Returns the cumulative net profit/loss since strategy start. More...
POSITION::state	position_state () const
	Returns the position state. Possible values are: More...
bool	is_long (void) const
	Returns true if the position is 'long'. More...
bool	is_short (void) const
	Returns true if the position is 'short'. More...
bool	is_flat (void) const
	Returns true if the position is 'flat'. More...
quantity_t	position_size (void) const
	Returns the size of the position. More...
position_t	position (void) const
	Returns the current position. A negative number denotes a 'short' position. More...

Current Trade Metrics
size_t	trade_leg_count (void) const
	Returns the number of 'legs' in the current trade. A 'leg' is a change in position such as an 'add on' or 'partial exit', including the initial trade entry leg and final trade exit leg. More...
double	trade_PL (void) const
	Returns the profit/loss of the current trade. More...
size_t	trade_bar_count (void) const
	Returns the number of bars since the trade's first transaction. Returns 0 if the current position is flat. More...
double	trade_first_leg_entry_price (void) const
	Returns the price of the trade's first transaction (first leg). Returns 0 if current position is flat. More...
const date_time &	trade_first_leg_entry_timestamp (void) const
	Returns the timestamp of the trade's first transaction. More...
quantity_t	trade_max_position (void) const
	Returns the maximum position since the trade was initiated. A trade can have any number of 'add on' transactions and 'partial exits' and so the position size can vary over time. More...
double	trade_most_favorable_price (void) const
	Returns the most favorable price since the beginning of the trade. The trade may likely have been at its most profitable at that price, but not necessarily as this also depends on when 'add-on' transactions occurred and when 'partial-profit' was taken. More...
double	trade_point_change_since_entry (void) const

Transactions
const transaction &	get_most_recent_transaction (void) const
int64_t	transact_count (void)
	Returns the total number of transactions generated by the strategy so far. More...
int64_t	transact_count (order::type order_type)
	Returns the total number of transactions, for this instrument and for the given order type, generated since the beginning of the strategy. More...
int64_t	unit_count (void)
	Returns the total number of 'units' of this instrument traded since the beginning if the strategy. More...

Metrics
const metrics &	get_metrics (void) const
	Returns an instance of class metrics containing all metrics that describe this instrument's performance during simulation. Only call this member once the strategy has been finalized. More...
virtual variant	get_metric (perf_metric_type metric_type, trade_grouping grouping=all_trades) const
	Returns an individual metric value corresponding to the given metric_type and trade grouping. More...
virtual variant	metric (const std::string &metric_name, trade_grouping grouping=all_trades) const
	Returns an individual metric value corresponding to the given metric_name and trade grouping. More...

Detailed Description

Class instrument represents a tradeable security such as a stock, option, futures contract, currency, etc. Class instrument combines data-access with functionality for placing orders and managing positions.

A single strategy can have any number of instrument members which allow it to trade pairs, baskets, and other instrument combinations. Data access is implemented by an internal in_stream member, which means that class instrument can be used in the same way as in_stream objects for receiving streaming data. Use instrument objects when you need to place orders relating to a particlar record stream, and use in_stream members to receive complementary data, such as company fundamentals, macroeconomic timeseries, or any other relevant data.

During strategy simulations each instrument object retains a history of all trades, which are used to product various reports once the strategy is finalized. The trade history can also be accessed as part of strategy evaluation.

Please refer to the TS-API User Guide and corresponding tutorials for information on how to best use class instrument.

Member Function Documentation

void tsa::instrument::allow_null_values

(

bool

flag

)

Determines whether any incoming stream data is allowed to have 'null' ('N/A') values. If set to true, it is up to the user to explicitly check each value before using it. To check for null, values must be accessed as variants, not via auto-series. Use the variant::defined() member do check if the value is not null.

Parameters

flag	If true, allows incoming values to be 'null'.

bool tsa::instrument::allow_null_values

(

void

)

const

Returns true if 'null' values are allowed in incoming stream data.

Returns

bool.

void tsa::instrument::as_random_walk

(

duration

bar_duration = duration::days(1)

)

Tells the instrument to generate its own random walk sequence with intervals of bar_duration.

The internal random walk generator generates data for the following fields:

• open
• high
• low
• close
• volume
• bid
• ask
• bidsize
• asksize.

  Parameters

  bar_duration

  The duration between the timestamps of consecutive bars.

date_time tsa::instrument::begin

(

void

)

Returns the timestamp of the first record in the datasource to which this object is connected.

Note that returning this value is only possible if the stream object is connected to a database table. A live data feed is not considered to have a beginning.

Returns

A date_time.

double tsa::instrument::big_point

(

void

)

const

The value (in local currency) of a 1 point change in the instrument's price. This calculated as follows: big_point_value = (1.0 / min_tick) * tick_value;.

Returns

A double.

instrument & tsa::instrument::broker

(

const std::string &

broker_name

)

Same functionality as platform(const std::string& platform_name) member.

Parameters

broker_name

Name of the broker.

Returns

An instrument&. This return value allows multiple member calls to be chained.

order_ref tsa::instrument::buy

(

quantity_t

quantity

)

Creates and immediately sends an order to buy 'at market' a given quantity of securities.

Parameters

quantity

The quantity.

Returns

An order_ref.

order_ref tsa::instrument::buy_limit	(	quantity_t	quantity,
		double	limit_price
	)

Creates and immediately sends an order to buy a given quantity of securities at a the given limit_price.

Parameters

quantity	The quantity.
limit_price	The limit price.

Returns

An order_ref.

order_ref tsa::instrument::buy_limit_order	(	quantity_t	quantity,
		double	limit_price
	)

Creates, without sending, an order to sell at given limit_price a given quantity of securities.

Parameters

quantity	The quantity.
limit_price	The limit price.

Returns

An order_ref.

order_ref tsa::instrument::buy_order

(

quantity_t

quantity

)

Creates an order, without sending it, to buy 'at market' a given quantity of securities.

Parameters

quantity

The quantity.

Returns

An order_ref.

order_ref tsa::instrument::buy_stop	(	quantity_t	quantity,
		double	stop_price
	)

Creates and immediately sends an order to buy a given quantity of securities at a the given stop_price.

Parameters

quantity	The quantity.
stop_price	The stop price.

Returns

An order_ref.

order_ref tsa::instrument::buy_stop_limit	(	quantity_t	quantity,
		double	stop_price,
		double	price_limit
	)

Creates and immediately sends an order to buy a given quantity of securities at the given stop_price with the given price_limit.

Parameters

quantity	The quantity.
stop_price	The stop price.
price_limit	The price limit.

Returns

An order_ref.

order_ref tsa::instrument::buy_stop_limit_order	(	quantity_t	quantity,
		double	stop_price,
		double	price_limit
	)

Creates, without sending, an order to buy a given quantity of securities at the given stop_price with given price_limit.

Parameters

quantity	The quantity.
stop_price	The stop price.
price_limit	The price limit.

Returns

An order_ref.

order_ref tsa::instrument::buy_stop_order	(	quantity_t	quantity,
		double	stop_price
	)

Creates, without sending, an order to buy a given quantity of securities at the given stop_price.

Parameters

quantity	The quantity.
stop_price	The stop price.

Returns

An order_ref.

void tsa::instrument::cancel_order

(

identifier_t

id

)

Cancels the order with t given order id.

Parameters

id	The order identifier.

void tsa::instrument::commission

(

double

comm

)

Sets the per-side / per-unit commission. Commission is allocated on a per-unit basis (the default) or on a per-transaction basis depending on what was set via the cost_allocation() member.

Parameters

comm	The per-side commission.

double tsa::instrument::commission

(

void

)

const

Returns the value set via the instrument::commission(double) member which is zero by default.

Returns

A double.

void tsa::instrument::connect	(	const std::string &	stream_name,
		const std::string &	database_name = "default"
	)

Sets the given stream as the instrument's data source.

This member function will seek to open the stream by reading from the data_base with the given data_base_name.

Parameters

stream_name	Name of the stream.
database_name	Name of the database.

void tsa::instrument::cost_allocation

(

cost_alloc_type

t

)

Sets the cost-allocation type that affects how commission and slippage are accounted for during simulations. Valid values are:

• tsa::per_transaction
• tsa::per_unit.

  Parameters

  t	The cost_alloc_type.

bool tsa::instrument::costs_allocated_per_unit

(

void

)

const

Returns true if the cost allocation is set to 'per_unit' (the default). Returns false if 'per_transaction'.

Returns

bool.

instrument & tsa::instrument::currency

(

const std::string &

ccy

)

Sets the instrument's currency.

Parameters

ccy

The ccy.

Returns

An instrument&.

const std::string & tsa::instrument::currency

(

void

)

const

Returns the instrument's currency.

Returns

A std::string&.

double tsa::instrument::current_drawdown

(

void

)

const

Returns the size of the current equity drawdown for this instrument. If the strategy trades multiple instruments then each instrument will have its own drawdown measure.

Returns

A double.

const std::vector< trade_leg > & tsa::instrument::current_trade_legs

(

void

)

const

Returns a container with the current trade's 'legs'.

An open trade has at least one 'leg' that opened the trade, and any number of additional legs that increase of reduce the trade's position until the trade is closed out.

Returns

A std::vector<trade_leg>&.

void tsa::instrument::default_time_in_force

(

order::time_in_force

default_tif

)

Sets the default time-in-force, which determines order lifetime.

Parameters

default_tif

the time in force.

instrument & tsa::instrument::define	(	const std::string &	symbol,
		const std::string &	exchange,
		const std::string &	platform
	)

Use this member to identify the instrument. This is required for live trading via the server.

Parameters

symbol	The symbol or symbol expiry combination such as: 'IBM', 'ES:DEC15', ESZ15'.
exchange	The exchange such as 'GLOBEX', 'NYSE'. If using Interactive Brokers 'SMART' exchange, then you must also set the currency like so: 'SMART:USD'.
platform	The platform such as 'IB' for Interactive Brokers.

Returns

An instrument&.

date_time tsa::instrument::end

(

void

)

Returns the timestamp of the last record in the datasource to which this object is connected.

Note that returning this value is only possible if the stream object is connected to a database table. A live data feed is not considered to have an ending.

Returns

A date_time.

instrument & tsa::instrument::exchange

(

const std::string &

exch

)

Sets the instrument's exchange. Use the define() member instead unless there is a special requirement.

Parameters

exch	The exchange.

Returns

An instrument&.

const std::string & tsa::instrument::exchange

(

void

)

const

Returns the instrument's exchange.

Returns

A std::string&.

instrument & tsa::instrument::expiry

(

const std::string &

expiry

)

Sets the contract expiry. Use the define() member instead to pass a symbol-expiry combination like 'ES:DEC15', unless you have a special requirement.

Parameters

expiry

The expiry.

Returns

An instrument&.

const std::string & tsa::instrument::expiry

(

void

)

const

Returns the contract expiry like 'DEC15'.

Returns

A std::string&.

const std::string & tsa::instrument::expiry_yyyymm

(

void

)

const

Returns the contract expiry in yyyymm format like: 201512.

Returns

A std::string&.

std::string tsa::instrument::feed

(

void

)

const

Returns the name of the data feed to which the instrument is connected.

Returns

A std::string.

size_t tsa::instrument::field_count

(

void

)

const

Returns the number of fields in records streamed from the connected datasource.

Returns

A size_t.

bool tsa::instrument::field_exists

(

const std::string &

field_name

)

const

Returns true if a field with the given field_name exists in records coming from the data-source.

Parameters

field_name

The field/column name.

Returns

true if the field exists, else false.

size_t tsa::instrument::field_index

(

const std::string &

field_name

)

const

Return the zero based position of the field that has the given field_name.

Note

This member throws an exception if no corresponding field exists.

Parameters

field_name

The field name.

Returns

The position.

tsa::type_t tsa::instrument::field_type

(

const std::string &

field_name

)

const

Returns the field type of the field with the given field_name.

Parameters

field_name

Name of the field.

Returns

A tsa::type_t.

void tsa::instrument::get_active_orders	(	std::vector< order_ref > &	v,
		order::type	_ot,
		order::action	_at
	)		const

Populates vector v with all 'active' orders.

Parameters

[in,out]	v	The std::vector<order_ref>& to process.
	_ot	The ot.
	parameter3	The third parameter.

const std::vector< transaction > & tsa::instrument::get_bar_transactions

(

void

)

const

Returns a reference to a vectors containing the transactions that occured during the current bar.

Returns

The bar transactions.

variant tsa::instrument::get_metric ( perf_metric_type  metric_type, trade_grouping  grouping = all_trades  ) const

virtual

Returns an individual metric value corresponding to the given metric_type and trade grouping.

Parameters

metric_type	Type of the metric.
grouping	Type of the aggregation.

Returns

The metric.

Implements tsa::metrics_source.

const metrics & tsa::instrument::get_metrics

(

void

)

const

Returns an instance of class metrics containing all metrics that describe this instrument's performance during simulation. Only call this member once the strategy has been finalized.

Returns

The metrics.

order_ref tsa::instrument::get_order

(

identifier_t

id

)

const

Returns an order with given id.

Parameters

id	The identifier.

Returns

The corresponding order_ref.

order * tsa::instrument::get_order_ptr

(

identifier_t

id

)

const

Returns a pointer to the order with given id. Note that it is unusual to access an order object directly. Normally orders should be handled via order_ref objects.

Parameters

id	The identifier.

Returns

null if it fails, else the order pointer.

void tsa::instrument::get_orders	(	std::vector< order_ref > &	v,
		bool	active_only = true
	)		const

Populates vector v with either all or only the 'active' orders depending on the given active_only flag.

Parameters

[in,out]	v	The std::vector<order_ref>.
	active_only	flag.

bool tsa::instrument::has_active_orders

(

void

)

const

Checks if this instrument object has 'active' orders.

Returns

true if it does.

std::string tsa::instrument::instrument::type

(

void

)

const

Returns the instrument type like 'STK' or 'FUT'.

Returns

A std::string.

std::string tsa::instrument::interval

(

void

)

const

Returns the interval (bar) type and duration. Valid values look like '5MIN', '1SEC', '3TICK'.

Returns

A std::string.

bool tsa::instrument::is_flat

(

void

)

const

Returns true if the position is 'flat'.

Returns

bool.

bool tsa::instrument::is_live

(

void

)

const

Strategies driven by 'live' data can be started on 'backfill' data. Once the strategy has worked through the backfill records, it calls strategy::on_live() from which point onward the strategy switches to 'live' data and instrument::is_live() returns true.

Returns

true if live, false if not.

bool tsa::instrument::is_long

(

void

)

const

Returns true if the position is 'long'.

Returns

bool.

bool tsa::instrument::is_platform_driven

(

void

)

const

Returns true if the strategy is attached to a platform_proxy or net::socket_base derived object.

If the strategy is platform driven, all orders and data requests are forwarded to the attached object.

Returns

true if platform driven, false if not.

bool tsa::instrument::is_short

(

void

)

const

Returns true if the position is 'short'.

Returns

bool.

void tsa::instrument::limit_fill_proviso

(

double

proviso

)

Sets the 'limit fill proviso'. This value determines by what margin market prices must exceed a limit price for a limit order to be assumed filled as part of a simulation. This value can help make simulations more realistic.

The execution of 'limit orders' on an exchange is not guaranteed. In some cases a 'limit order' may be filled when traded prices 'hit' the limit price. However, in practice, it is likely that the traded price needs to move one tick past the limit price before a 'limit order' can be assumed to have been filled!

By default, this 'proviso' value is zero. With a setting of zero, prices must only move 'beyond' the limit price, no matter by how small an amount ( at leat 10e-9) for the limit order to be considered filled.

If the 'limit_fill_proviso' is, for example, set to 1.0, then, in the case of a limit sell order, traded prices must move below the limit price by more than 1.0.

Note that it is possible to reset the limit-fill-proviso while a strategy simulation is underway.

Note that the size of a single tick is not constant when dealing with price series that have been dividend-adjusted, split-adjusted, or roll-over adjusted. So adjusting the limit-fill- proviso throughout the simulation may be required for realistic simulation.

Parameters

proviso

The limit-fill-proviso.

double tsa::instrument::limit_fill_proviso

(

void

)

const

Returns the 'limit fill proviso'.

Returns

A double.

variant tsa::instrument::metric ( const std::string &  metric_name, trade_grouping  grouping = all_trades  ) const

virtual

Returns an individual metric value corresponding to the given metric_name and trade grouping.

Parameters

metric_name	Name of the metric.
grouping	The grouping.

Returns

A variant.

Implements tsa::metrics_source.

void tsa::instrument::name

(

const std::string &

name

)

Sets the instrument name.

The instrument name is intended to help identify instruments on reports. An instrument name must be unique to a strategy. Naming an instrument is not mandatory as each instrument is otherwise automatically assigned a default name, usually based on the name of the stream to which the instrument is connected.

Note

This instrument name is not used when sending order messages.

Parameters

name	The instrument name.

const std::string & tsa::instrument::name

(

void

)

const

Returns the instrument name.

Returns

A std::string&.

void tsa::instrument::negative_prices_ok

(

bool

neg_prices_ok

)

Sets a flag which if 'true' allows negative prices in fields 'open', 'high', 'low', 'close'.

By default prices at or below 0.0 are not allowed during simulations as some indicators and calculations may not be able to handle negative numbers or changes from positive to negative (such as indicators calculating percentage changes). If the flag is left as false, an exception will be thrown in case of violation.

Sub-zero prices can arise when creating 'continuous futures contracts' from individual futures contracts.

Parameters

neg_prices_ok.

bool tsa::instrument::negative_prices_ok

(

void

)

const

Returns true if negative prices are tolerated during strategy evaluation.

Returns

Returns the current value of the property.

double tsa::instrument::net_profit

(

void

)

const

Returns the cumulative net profit/loss since strategy start.

Returns

A double.

const series_core & tsa::instrument::operator()

(

size_t

field_pos

)

const

From records streamed from the data source this member returns the series corresponding to the given field_pos.

Parameters

field_pos

The column/field position.

Returns

Reference to the series. Use operator[] to access individual historical values.

const series_core & tsa::instrument::operator()

(

const std::string &

field_name

)

const

From records streamed from the data source this member returns the series corresponding to the given field_name.

Parameters

field_name

Name of the column/field.

Returns

Reference to the series. Use operator[] to access individual value.

size_t tsa::instrument::order_count

(

void

)

const

Returns the number of 'active' orders.

Returns

A size_t.

size_t tsa::instrument::order_count_inclusive

(

void

)

const

Returns the number of orders, both 'active' and 'inactive'. Inactive orders may be marked for deletion.

Returns

A size_t.

bool tsa::instrument::order_exists

(

identifier_t

id

)

const

Returns true if an order with the given id exists.

Parameters

id	The identifier.

Returns

true if the order exists.

instrument & tsa::instrument::platform

(

const std::string &

platform_name

)

Sets the name of the excution platform / broker. Note that different instrument objects can trade via different brokers.

Parameters

platform_name

The name.

Returns

An instrument&. This return value allows multiple member calls to be chained.

position_t tsa::instrument::position

(

void

)

const

Returns the current position. A negative number denotes a 'short' position.

Returns

A position_t.

quantity_t tsa::instrument::position_size

(

void

)

const

Returns the size of the position.

Returns

A quantity_t.

POSITION::state tsa::instrument::position_state

(

)

const

Returns the position state. Possible values are:

• is_long
• is_short
• is_flat

  Returns

  A POSITION::state.

date_time tsa::instrument::record_timestamp

(

void

)

const

Returns the timestamp of the current record.

Note that this timestamp normally corresponds to the timestamp of the current strategy- interval, as returned by the strategy::timestamp() member. In case the underlying data source has no record for the current strategy interval then the value returned by this member will not match the value returned by strategy::timestamp(). This may happen for example when working with multiple data streams of different timescales.

Returns

A date_time.

order_ref tsa::instrument::sell

(

quantity_t

quantity

)

Creates and immediately sends an order to sell 'at market' a given quantity of securities.

Parameters

quantity

The quantity.

Returns

An order_ref.

order_ref tsa::instrument::sell_limit	(	quantity_t	quantity,
		double	limit_price
	)

Creates and immediately sends an order to sell at given limit_price a given quantity of securities.

Parameters

quantity	The quantity.
limit_price	The limit price.

Returns

An order_ref.

order_ref tsa::instrument::sell_limit_order	(	quantity_t	quantity,
		double	limit_price
	)

Creates, without sending, an order to sell at given limit_price a given quantity of securities.

Parameters

quantity	The quantity.
limit_price	The limit price.

Returns

An order_ref.

order_ref tsa::instrument::sell_order

(

quantity_t

quantity

)

Creates, without sending, an order to sell 'at market' a given quantity of securities.

Parameters

quantity

The quantity.

Returns

An order_ref.

order_ref tsa::instrument::sell_stop	(	quantity_t	quantity,
		double	stop_price
	)

Creates and immediately sends an order to sell a given quantity of securities at a the given stop_price.

Parameters

quantity	The quantity.
stop_price	The stop price.

Returns

An order_ref.

order_ref tsa::instrument::sell_stop_limit	(	quantity_t	quantity,
		double	stop_price,
		double	price_limit
	)

Creates and immediately sends an order to sell a given quantity of securities at the given stop_price with the given price_limit.

Parameters

quantity	The quantity.
stop_price	The stop price.
price_limit	The price limit.

Returns

An order_ref.

order_ref tsa::instrument::sell_stop_limit_order	(	quantity_t	quantity,
		double	stop_price,
		double	limit_price
	)

Creates, without sending, an order to sell a given quantity of securities at the given stop_price with given price_limit.

Parameters

quantity	The quantity.
stop_price	The stop price.
limit_price	The limit price.

Returns

An order_ref.

order_ref tsa::instrument::sell_stop_order	(	quantity_t	quantity,
		double	stop_price
	)

Creates, without sending, an order to sell a given quantity of securities at the given stop_price.

Parameters

quantity	The quantity.
stop_price	The stop price.

Returns

An order_ref.

void tsa::instrument::set_next_bar	(	const date_time &	_ts,
		double	o,
		double	h,
		double	l,
		double	c,
		double	v
	)

Manually sets the next bar timestamp and ohlcv prices. Useful for writing test code.

Parameters

parameter1	The first parameter.
o	open price.
h	high price.
l	low price.
c	close price.
v	volume.

void tsa::instrument::slippage

(

double

slip

)

Sets the 'per side' or 'per transaction' slippage (by default it is interpreted as 'per-side' slippage. This can be changed via the cost_allocation() member). A realistic slippage setting helps make simulations more realistic by accounting for non-optimal fills. Slippage is only counted for stop and market orders. Limit orders never have slippage regardless of the slippage setting. Slippage can be reset during strategy evaluations to account for changes in volatility.

Parameters

slip	The value.

double tsa::instrument::slippage

(

void

)

const

Returns the slippage as set via the slippage(double slip) member.

Returns

A double.

std::string tsa::instrument::stream_name

(

void

)

const

Returns the name of the data stream to which the instrument is connected.

Returns

A std::string.

instrument & tsa::instrument::symbol

(

const std::string &

symb

)

Sets the instrument's symbol. Use the define() member instead unless you have a special requirement.

Parameters

symb	The symbol.

void tsa::instrument::tick	(	double	min_tick,
		double	tick_value,
		bool	auto_round = true
	)

Sets the value of the 'minimum tick' (the smallest possible price change for a given traded security) as well as the tick's cash value.

The default min_tick value is 0.01 points and a corresponding tick_value of 0.01 (local currency). This works fine for most traded stocks, but does not work for futures, options and other products.

The auto_round argument determines whether the system will automatically round stop and limit order prices passed to order functions (e.g instrument::buy()). Note that when working with split adjusted stock price series, the historical minimum tick is no longer accurate and you may need to disable automatic rounding.

Parameters

min_tick	The minimum tick.
tick_value	The tick value in the currency in which the instrument is traded.
auto_round	true to automatically round.

double tsa::instrument::tick_size

(

void

)

const

Returns the value of the smallest allowed price change (min_tick) as set via the tick() member.

Returns

A double.

double tsa::instrument::tick_value

(

void

)

const

Returns the cash value of the min_tick as set by via the tick() member.

By default the tick value is set to 0.01.

Returns

A double.

double tsa::instrument::ticks

(

int64_t

multiplier

)

const

Returns the price equivalent of a price tick multiplied by the given multiplier.

The tick value is either the default 0.01 or was previously set via instrument::tick(). This function is useful for adding a certain number of ticks to a price, to be used as stop or limit price in a trading scenario.

Parameters

multiplier

The tick multiplier.

Returns

A double.

size_t tsa::instrument::trade_bar_count

(

void

)

const

Returns the number of bars since the trade's first transaction. Returns 0 if the current position is flat.

Returns

A size_t.

double tsa::instrument::trade_first_leg_entry_price

(

void

)

const

Returns the price of the trade's first transaction (first leg). Returns 0 if current position is flat.

Returns

A double.

const date_time & tsa::instrument::trade_first_leg_entry_timestamp

(

void

)

const

Returns the timestamp of the trade's first transaction.

Returns

A date_time&.

size_t tsa::instrument::trade_leg_count

(

void

)

const

Returns the number of 'legs' in the current trade. A 'leg' is a change in position such as an 'add on' or 'partial exit', including the initial trade entry leg and final trade exit leg.

Returns

A size_t.

quantity_t tsa::instrument::trade_max_position

(

void

)

const

Returns the maximum position since the trade was initiated. A trade can have any number of 'add on' transactions and 'partial exits' and so the position size can vary over time.

Returns

A double.

double tsa::instrument::trade_most_favorable_price

(

void

)

const

Returns the most favorable price since the beginning of the trade. The trade may likely have been at its most profitable at that price, but not necessarily as this also depends on when 'add-on' transactions occurred and when 'partial-profit' was taken.

Returns

A double.

double tsa::instrument::trade_PL

(

void

)

const

Returns the profit/loss of the current trade.

Returns

A double.

int64_t tsa::instrument::transact_count

(

void

)

Returns the total number of transactions generated by the strategy so far.

Returns

An int64_t.

int64_t tsa::instrument::transact_count

(

order::type

order_type

)

Returns the total number of transactions, for this instrument and for the given order type, generated since the beginning of the strategy.

Parameters

order_type

The type.

Returns

An int64_t.

int64_t tsa::instrument::unit_count

(

void

)

Returns the total number of 'units' of this instrument traded since the beginning if the strategy.

Returns

A double.