FutureTicker

class qf_lib.containers.futures.future_tickers.future_ticker.FutureTicker(name: str, family_id: str, N: int, days_before_exp_date: int, point_value: int = 1, designated_contracts: Optional[str] = None, security_type: qf_lib.common.enums.security_type.SecurityType = <SecurityType.FUTURE: 'FUT'>)

Bases: qf_lib.common.tickers.tickers.Ticker

Class to represent a Ticker, which gathers multiple future contracts.

The FutureTicker class extends the standard Ticker class. It allows the user to use only a Ticker abstraction, which provides all of the standard Ticker functionalities (e.g. just as standard tickers, it can be used along with DataHandler functions get_price, get_last_available_price, get_current_price etc.), without the need to manually manage the rolling of the contracts or to select a certain specific Ticker.

Notes

Methods

belongs_to_family(ticker)	Function, which takes a specific Ticker, and verifies if it belongs to the family of futures contracts, identified by the FutureTicker.
get_current_specific_ticker()	Method which returns the currently valid, specific Ticker.
get_expiration_dates()	Returns QFSeries containing the list of specific future contracts Tickers, indexed by their expiration dates.
initialize_data_provider(timer, data_provider)	Initialize the future ticker with data provider and ticker.
set_expiration_hour(hour, minute, second, …)	Sets the expiration hour.
supported_ticker_type()	Returns class of specific tickers which are supported by this FutureTicker (e.g.

Attributes

initialized	Boolean providing information on whether the data provider and timer were set for this Future Ticker instance or not.
name	Returns the name of the future ticker.
ticker	Property which returns the value of ‘ticker’ attribute of the currently valid, specific Ticker.

While downloading historical data (using for example get_price function) all of the prices would be provided for the current specific ticker, e.g. in case of the family of Cotton future contracts, if on a certain day the specific contract returned by the FutureTicker will be the December 2019 Cotton contract, all of the prices returned by get_price will pertain to this specific December contract and no prices chaining will occur. In order to use the get_price function along with futures contracts chaining (and eventual adjustments), the FuturesChain object has to be used.

Parameters

• name (str) – Field which contains a name (or a short description) of the FutureTicker.

• family_id (str) – Identificator used to describe the whole family of future contracts. In case of specific Future Tickers its purpose is to build an identificator, used by the data provider to download the chain of corresponding Tickers, and to verify whether a specific Ticker belongs to a certain futures family.

• N (int) – Since we chain individual contracts, we need to know which one to select. N determines which contract is used at any given time when we have to select a specific contract. For example N parameter set to 1, denotes the first (front) future contract. N set to 2 will be the second contract and so on.

• days_before_exp_date (int) – Number of days before the expiration day of each of the contract, when the “current” specific contract should be substituted with the next consecutive one.

• point_value (int) – Used to define the size of the contract.

• designated_contracts (str) – It is a string, which represents all month codes, that are being downloaded and stored in the chain of future contracts. Any specific order of letters is not required. E.g. providing this parameter value equal to “HMUZ”, would restrict the future chain to only the contracts, which expire in March, June, September and December, even if contracts for any other months exist and are returned by the DataProvider get_futures_chain_tickers function.

abstract belongs_to_family(ticker: qf_lib.common.tickers.tickers.Ticker) → bool

Function, which takes a specific Ticker, and verifies if it belongs to the family of futures contracts, identified by the FutureTicker.

Returns

Return type

bool

get_current_specific_ticker() → qf_lib.common.tickers.tickers.Ticker

Method which returns the currently valid, specific Ticker.

In order to optimize the computation of ticker value the ticker value is being cached. The ticker is assumed to expire at a given expiration hour (which can be adjusted using the set_expiration_hour, by default it points to midnight), which means that on the expiration date the old contract is returned till the expiration hour and the new contract is returned since the expiration hour (inclusive).

Returns

The current specific ticker.

Return type

Ticker

get_expiration_dates() → qf_lib.containers.series.qf_series.QFSeries

Returns QFSeries containing the list of specific future contracts Tickers, indexed by their expiration dates. The index contains original expiration dates, as returned by the data handler, without shifting it by the days_before_exp_date days (it is important to store the original values, instead of shifted ones, as this function is public and used by multiple other components).

Returns

QFSeries containing the list of specific future contracts Tickers, indexed by their expiration dates

Return type

QFSeries

initialize_data_provider(timer: qf_lib.common.utils.dateutils.timer.Timer, data_provider: DataProvider)

Initialize the future ticker with data provider and ticker.

Parameters

• timer (Timer) – Timer which is used further when computing the current ticker.

• data_provider (DataProvider) – Data provider which is used to download symbols of tickers, belonging to the given future ticker family

property initialized

Boolean providing information on whether the data provider and timer were set for this Future Ticker instance or not.

property name

Returns the name of the future ticker.

set_expiration_hour(hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0)

Sets the expiration hour. Expiration hour is used to compute the current specific ticker. By default the expiration hour is set to midnight, which means that within one day always the same current specific ticker is returned.

In case if the expiration hour is set to 8:00 pm then if that day was the last day the contract was valid, then the new contract is returned since 8:00 pm that day (inclusive).

Parameters

• hour (int) –

• minute (int) –

• second (int) –

• microsecond (int) –

abstract supported_ticker_type() → Type[qf_lib.common.tickers.tickers.Ticker]

Returns class of specific tickers which are supported by this FutureTicker (e.g. it should return BloombergTicker for the BloombergFutureTicker etc.

property ticker

Property which returns the value of ‘ticker’ attribute of the currently valid, specific Ticker. E.g. in case of Cotton FutureTicker in the beginning of December, before the expiration date of December ticker, the function will return the Ticker(“CTZ9 Comdty”).ticker string value.

Returns

String of the current specific ticker.

Return type

str