FuturesContractGroup

class sigtech.framework.instruments.futures.FuturesContractGroup

Class containing common information for futures belonging to the same future strip.

Keyword arguments:

• currency

• price_factor - factor reflecting USd / GBp quoting of contracts

• contract_code - stub to identify future strip

• contract_sector - sector identifier for future strip

• exchange_code - exchange code identifier

• item_product_type - defines product type of future contracts belonging to the group

• underlying_index_ticker - instrument ticker the futures are based on

• use_history_schedule - if True will use the data points to drive the schedule, default is False

• asset_description - string description of the asset underlying the future

• front_generic_ticker - generic front ticker, e.g CL1, CO2, etc….

• first_contract - first available contract in the future strip

• market impact - dictionary containing market impact numbers applied for transaction costs

• contract_fixed_trade_cost - fixed costs applied for transaction costs

• tick_size - tick size definition from contract description

• contract_month_codes - future month codes available for the future strip

• contract_month_codes_exceptions - dictionary handling contract month code changes over time

• prime_history_field - prime history field for futures

• yield_quoted - defines if future price quotes are for yields, for example for bond futures

• exchange_open_stored - time when instrument opens for trading on a good business day (overrides same field in Exchange)

• exchange_close_stored - time when instrument closes for trading on a good business day (overrides same field in Exchange)

• holidays_stored - holiday calendars determining open instrument trading days (overrides same field in Exchange)

• settlement_time_stored - product specific settlement time at exchange

• exchange_product_symbol - product specific exchange product code relevant for trading at exchange directly

• futvalpt_raw - Value change in one tradable futures contract per 1.0 point move in the price

• contract_size - contract size of one tradable futures contract

• contract_units - unit of measurement of a tradable futures contract

• intraday_history_fields - intraday history fields for futures

• prime_intraday_history_field - prime history field for futures

• available_data_points - data points available for futures

• default_data_point - the default data point for futures

Expiry rule inputs:

• expiry_adjust_by_cd

• expiry_week_n

• expiry_offset

• expiry_adjust_start

• expiry_adjust_start_bdc - Business day convention to use for adjustment of reference date (either ‘PREVIOUS’ or ‘FOLLOWING’).

• expiry_month_offset

• expiry_bdc

• expiry_day

First delivery notice date rule inputs:

• first_notice_day

• first_notice_month_offset

• first_notice_week_n

• first_notice_day_adjust_by_cd

• first_notice_day_bdc

• first_notice_adjust_start

• first_notice_adjust_start_bdc - Business day convention to use for adjustment of reference date (either ‘PREVIOUS’ or ‘FOLLOWING’).

• first_notice_day_offset

Example object creation:

FuturesContractGroup(
    asset_description='Brent',
    contract_code='CO',
    contract_fixed_trade_cost=1.27,
    contract_month_codes=['F',
                          'G',
                          'H',
                          'J',
                          'K',
                          'M',
                          'N',
                          'Q',
                          'U',
                          'V',
                          'X',
                          'Z'],
    contract_month_codes_exceptions={'2016': ['FGHJKMNQUVXZ',
                                              ['F_0',
                                               'F_1',
                                               'F_2',
                                               'F_3',
                                               'F_4',
                                               'F_5',
                                               'F_6']],},
    item_product_type='Commodity Future',
    contract_sector='COMDTY',
    currency='USD',
    data_source_all=['Bloomberg'],
    exchange_code='ICE EXCHANGE GROUP',
    expiry_adjust_by_cd=-15,
    expiry_adjust_start=True,
    expiry_adjust_start_bdc='PREVIOUS',
    expiry_bdc='PRECEDE',
    expiry_day='1',
    expiry_month_offset=0,
    expiry_offset='-1BD',
    expiry_week_n=3,
    first_notice_adjust_start='FALSE',
    first_notice_adjust_start_bdc='PREVIOUS',
    first_notice_day='EOM',
    first_notice_day_adjust_by_cd='0',
    first_notice_day_bdc='FOLLOWING',
    first_notice_day_offset='-1BD',
    first_notice_month_offset='-1',
    first_notice_week_n='0',
    first_contract='COF89 COMDTY',
    front_generic_ticker='CO1 COMDTY',
    price_factor=1.0,
    product_type='Futures Contract Group',
    tick_size=0.01,
    use_history_schedule=False,
    yield_quoted=False,
    exchange_close_stored='16:00:00',  # expressed in exchange timezone
    exchange_open_stored='10:00:00',  # expressed in exchange timezone
    holidays_stored='ICE(T)',
    settlement_time_stored='16:30:00', # expressed in exchange timezone
    exchange_product_symbol='ZL',
)

currency: str

price_factor: float

contract_code: str

contract_sector: str

exchange_code: str

item_product_type: str

coupon: Optional[float]

expiry_adjust_by_cd: Optional[int]

expiry_week_n: Optional[int]

expiry_offset: Optional[str]

expiry_adjust_start: Optional[bool]

expiry_adjust_start_bdc: Optional[str]

expiry_month_offset: Optional[int]

expiry_bdc: Optional[str]

underlying_index_ticker: Optional[str]

use_history_schedule: Optional[bool]

asset_description: Optional[str]

front_generic_ticker: Optional[str]

futvalpt_raw: Optional[Union[float, int, str]]

contract_size: Optional[float]

contract_units: Optional[str]

group_name: Optional[str]

first_contract: str

tick_size: float

contract_month_codes: list[str]

contract_fixed_trade_cost: Optional[float]

contract_month_codes_exceptions: Optional[dict]

prime_history_field: Optional[str]

history_fields: Optional[list[str]]

expiry_day: Optional[str]

yield_quoted: bool

is_tas: Optional[bool]

first_notice_day: Optional[str]

first_notice_month_offset: Optional[int]

first_notice_week_n: Optional[int]

first_notice_day_adjust_by_cd: Optional[int]

first_notice_day_bdc: Optional[str]

first_notice_adjust_start: Optional[bool]

first_notice_adjust_start_bdc: Optional[str]

first_notice_day_offset: Optional[str]

exchange_open_stored: Optional[datetime.time]

exchange_close_stored: Optional[datetime.time]

holidays_stored: Optional[str]

settlement_time_stored: Optional[datetime.time]

exchange_product_symbol: Optional[str]

trade_out: Optional[datetime.date]

prime_intraday_history_field: Optional[str]

intraday_history_fields: Optional[list[str]]

CONTRACT_MONTH_CODES_DICT = {'F': 1, 'G': 2, 'H': 3, 'J': 4, 'K': 5, 'M': 6, 'N': 7, 'Q': 8, 'U': 9, 'V': 10, 'X': 11, 'Z': 12}

CONTRACT_MONTH_CODES_LIST = ['F', 'G', 'H', 'J', 'K', 'M', 'N', 'Q', 'U', 'V', 'X', 'Z']

TAS_EQUIVALENCE_DICT = {'VXT INDEX FUTURES GROUP': 'UX INDEX FUTURES GROUP'}

property underlying_asset_description: str

Return a string representing the underlying asset.

property asset: str

Return a string representing the underlying asset (deprecated, use asset_description instead).

property holidays: str

Holiday calendar identifier followed by the instrument (or exchange, if no specific instrument calendar exists).

Returns

property settlement_time: datetime.time

The time of day when the settlement values are determined.

Returns

property timezone: str

Timezone info for this instrument.

property due_time: datetime.time

Time when data from the exchange is expected to be in the system.

property market_impact

Market impact for the group represented by contract code and contract sector.

static future_contract_year(ticker: str) → str

Parameters

ticker – Input futures ticker

Returns

The contract year from futures ticker

static month_code(month_number: int) → str

Parameters

month_number – Integer code for month

Returns

The futures code corresponding to given month number

static month_number(month_code: str) → int

Parameters

month_code – Futures month code

Returns

The month number corresponding to given code

static from_contract(contract_code: str, contract_sector: str, env: Optional[sigtech.framework.config.config.ConfiguredEnvironment] = None) → Any

Create a futures group from contract code and sector.

Parameters

• contract_code – Future string stub identifier

• contract_sector – Sector string

Returns

Instance of FuturesContractGroup

static name_from_contract(contract_code: str, contract_sector: str) → str

Create a futures group name from contract code and sector.

Parameters

• contract_code – Future string stub identifier

• contract_sector – Sector string

Returns

Default name of instance of FuturesContractGroup

static ticker_to_year_month(ticker: str) → tuple

Parameters

ticker – Input ticker

Returns

A month and a year corresponding to given ticker

static contract_code_refining(contract_code: str) → str

Parameters

contract_code – Input contract_code

Returns

Add a space at the end of 1 letter contract code

exchange() → Any

Returns

Exchange these futures trade on

expiry_date_calculated(contract: str) → datetime.date

Calculates the expiry date for a contract from the group expiry rules.

Parameters

contract – Input contract string identifier string

Returns

The expiry date for the contract

month_codes_for_year(year: int) → list[str]

Parameters

year – Input year

Returns

List of month codes for given year

property exchange_close: datetime.time

The time of day that the instrument closes for trading on its exchange.

exchange_close_on_day(d: datetime.date) → datetime.datetime

Gets the close of the instrument (or exchange, if instrument-specific close does not exist) on a given date.

Parameters

d – Input date d

Returns

UTC time of exchange close on day d

exchange_open_on_day(d: Optional[datetime.date] = None) → datetime.datetime

Gets the open of the instrument (or exchange, if instrument-specific open does not exist) on a given date.

Parameters

d – Input date d. If set to None, use the open from data (instrument or exchange).

Returns

UTC time of instrument (or exchange) open on day d.

exchange_open(d: datetime.date = None) → datetime.datetime deprecated

Gets the open of the instrument (or exchange, if instrument-specific open does not exist) on a given date. Deprecated, use exchange_open_on_day instead.

Parameters

d – Input date d. If set to None, use the open from data (instrument or exchange).

Returns

UTC time of instrument (or exchange) open on day d.

property live_supported: bool

True if live streaming is supported

property discount_curve_obj

Object representing the discount curve for the instrument.

Returns

Object.

discount_curves(data_point=None, data_dates=None)

Discount curves for the instrument.

Parameters

• data_dates – List of dates.

• data_point – Input data point (optional).

Returns

pandas Series.

contract_name_from_year_month(year: int, month: int) → str

Parameters

• year – year input

• month – Future month number

Returns

Contract name from given year and month

contract_name_from_year_month_code(year: int, month_code: str) → str

Parameters

• year – Year input

• month_code – Future month code

Returns

Contract name from given year and month

contracts_series(end_date=None)

Make sure contract list has been lazily generated - return it.

get_contract_list(end_date=None) deprecated

Make sure contract list has been lazily generated - return it.

first_data_date()

The first day we have daily history for a contract in this group.

active_contract(d: Optional[datetime.date] = None, next_on_expiry: Optional[bool] = False) → Any

Parameters

• d – Input date, if no value is specified the environment date is used

• next_on_expiry – If True and active contract expires on d it will return the next contract

Returns

The active contract on a given date

contract_names(start: datetime.date, end: datetime.date) → list[str]

Given a date range, return a list of contract names that meet the following conditions:

• first_contract.expiry_date > start

• first_contract.prev_contract.expiry_date <= start

• last_contract.expiry_date > end

• last_contract.prev_contract.expiry_date <= end

Parameters

• start – Input start date

• end – Input end date

Returns

List of contract names meeting the above conditions

contract_instruments(start: datetime.date, end: datetime.date) → list[Any]

Parameters

• start – Input start date

• end – Input end date

Returns

List of instruments that expire between given dates

next_contract(expiry_date: datetime.date) → str

Parameters

expiry_date – Date used as cut-off

Returns

The next contract to one expiring on given date

next_available_contract(expiry_date: datetime.date) → Any

Parameters

expiry_date – Date used as cut-off

Returns

Next futures object with expiry date greater than expiry_date

prev_contract(expiry_date: datetime.date) → str

Parameters

expiry_date – Date used as cut-off

Returns

The previous contract to one expiring on given date

prev_available_contract(expiry_date: datetime.date) → Any

Parameters

expiry_date – Date used as cut-off

Returns

Previous futures object with expiry date less than expiry_date

contract_list(years: list[int], month_codes: list[str]) → list[str]

Parameters

• years – Input list containing years

• month_codes – Input list containing month codes

Returns

Given two lists of years and months, return a list of contract names.

generic_contracts(offset_list: list[int], dates: list[datetime.date], fill_gaps: Optional[bool] = True) → tuple

Parameters

• offset_list – List of contract offsets, e.g. [1, 3]

• dates – List of dates to generate contracts for

• fill_gaps – If history is too short fill the gap with data from previous contracts

Returns

Generic contract prices and instruments, e.g. CL1, CL2, … etc.

get_future_curve(date: datetime.date) → pandas.core.frame.DataFrame

Get the future contracts prices and days-to-expiry for all available contracts on date.

Parameters

date – Date to fetch data from.

Returns

Dataframe of contract name, price, expiry date and days-to-expiry on date.

property curve_plots

A CurvePlotWrapper interface to produce plots for the curve for this contract group.

get_price_curve(date: datetime.date, factor_point: Optional[Any] = None, start: Optional[int] = 10, end: Optional[int] = 800, step: Optional[int] = 10, interpolation_type: Optional[Any] = 2) → dict

Calculate interpolated prices for the curve at one date.

Parameters

• date – Date for curve

• factor_point – Point to standardize around, , e.g. 'mean', None, or # days to expiry

• start – Number of days to expiry to start interpolation

• end – Number of days to expiry to end interpolation

• step – Number of days between each entry

• interpolation_type – Interpolation method (defaults to 2 i.e. quadratic splines)

Returns

Dictionary of days to expiry : prices

get_historic_curve(start_date: datetime.date, end_date: datetime.date, factor_point: Optional[Any] = None, seasonal: Optional[bool] = False, steps: Optional[int] = 1)

Retrieve the history of future curve points.

Parameters

• start_date – Start date

• end_date – End date

• factor_point – Point to standardize around, , e.g. 'mean', None, or # days to expiry

• seasonal – Group by point in the year

• steps – Days per step

Returns

DataFrame of prices

cftc_data(raw_data: Optional[bool] = False)

Retrieve dataframe of commitments of traders data for future group.

Parameters

raw_data – Boolean flag, if set this will return the full table otherwise the metrics are split out.

Returns

DataFrame of CFTC data.

add_contract(year: int, month_code: str, prices: pandas.core.series.Series, start_date: Optional[datetime.date] = None, expiry_date: Optional[datetime.date] = None, **kwargs) → str

Add a contract to this future group. This will fail if contract already exists. If you wish to overwrite the history of an existing contract use:

contract = env.object.get("<contract ticker e.g. CLH22 COMDTY>")
contract.add_custom_history(custom_prices)

Parameters

• year – Year as int (e.g. 2000)

• month_code – Code as string (e.g. "H")

• prices – pd.Series of history for this new contract.

• start_date – Starting date of this contract, if left blank first index of prices is used.

• expiry_date – Expiry date of this contract, if left blank last index of prices is used.

• kwargs – Passed to contract constructor.

Returns

Name of newly created contract

property available_data_points: Optional[list[sigtech.framework.infra.data_adapter.common.DataPoint]]

Available data points for this object.

available_data_providers(entitled_only=True) → Optional[List[str]]

Available data providers for this object. Bool to return entitled providers only

property cache_name: str

Cache name of this object.

property class_name

Class name of this object.

property class_short_name

Short name of the object class.

clear_cached_data()

Clear all the cached data of the object.

clone_object(params=None)

Return a clone of the object with amended parameters.

Parameters

params – Optional dictionary of parameters to override.

Returns

New object.

compute_dependencies(root_dependency: Optional[sigtech.framework.internal.infra.mu.graph.registry.factory.Dependency] = None)

Compute these dependencies - triggers MDS requests

static convert_dtypes(clz)

Class decorator to convert classes’ BaseType into variable annotations (PEP-526), and to generate __aliases__ based on BaseType.db_name when required.

data_dict()

Return the object attributes in a dict.

property data_source: str

Field used when retrieving history.

property default_data_point: sigtech.framework.infra.data_adapter.common.DataPoint

Return the default data point.

dependencies(input_dependency: Optional[sigtech.framework.internal.infra.mu.graph.registry.factory.Dependency] = None, valuation_currency: Optional[str] = None, use_start: bool = True) → list[sigtech.framework.internal.infra.mu.graph.registry.factory.Dependency]

Returns a list of Dependency

Parameters

• input_dependency – A Dependency object representing the root of the dependency tree to be returned.

• valuation_currency – If supplied, include the dependencies required to output the data in this currency.

• use_start – If False, return only dependencies required to calculate an earliest start date - self.start_date will be None in this case.

Returns

List of Dependency objects representing the current level in the dependency tree.

property dependency_type

Should return GraphNodeType. Return None to autodetect based on result of dependencies()

property env: sigtech.framework.config.config.ConfiguredEnvironment

Return the configured environment.

env_date_change(old_env_dt: datetime.datetime, new_env_dt: datetime.datetime, live_data_update=None)

Routine called after the environment date is changed.

Parameters

• old_env_dt – Old datetime (tz aware).

• new_env_dt – New datetime (tz aware).

• live_data_update – Live streaming data associated with the environment date change.

finalize_for_comparison()

Method to call to ensure all data dict values are finalized prior to doing object comparisons.

classmethod from_dictionary(dct: dict[str, Any], cache: bool = True, identifier: Optional[sigtech.framework.infra.data_adapter.identifier.Identifier] = None, env: Optional[sigtech.framework.config.config.ConfiguredEnvironment] = None, **kwargs)

Factory method to create object using data dictionary

classmethod get_names(sort_by_group: Optional[bool] = False, include_db: Optional[bool] = True, include_local: Optional[bool] = True, include_children: Optional[bool] = False, ignore_unmapped: Optional[bool] = True) → list[str]

Return an ordered list of object names associated with the class.

Parameters

• sort_by_group – If set, the list is first ordered by sector/group, if applies, e.g. commodity or index futures (default is False).

• include_db – If set, include objects available from the database (default is True).

• include_local – If set, include objects available in the local environment (default is True).

• include_children – If set, include objects available from child classes (default is False).

• ignore_unmapped – If set, ignore errors due to unmapped database objects (default is True).

Returns

List of object names.

property identifier: sigtech.framework.infra.data_adapter.identifier.Identifier

Return the object identifier.

info() → dict

Return a dictionary with useful object information.

property input_parameters

Values of initial input parameters entered when creating the instance.

property internal_id

Ticker - i.e. part of name determining content of the class. For types with saved reference data - ticker will be self._ticker. For software types - ticker should be calculated.

property is_unmapped

Check if the object is not mapped.

property name

Primary name by which the FrameworkObject is identified. If reference information (or e.g. corresponding time series) are stored in the DB, then this name will be used.

print_dependencies(root_dependency: Optional[sigtech.framework.internal.infra.mu.graph.registry.factory.Dependency] = None, resolve_future_dependencies: bool = True, fields: Optional[list] = None)

Pretty print dependency tree :param root_dependency: starting dependency of the tree. :param resolve_future_dependencies: resolve future dependencies before printing. If ‘false’ nothing get printed. :param fields: additional fields to extract from dependencies object. Default fields are product_type, currency, frequency and data_source. To get the list of available fields for an object you can use the data_dict() method.

property product_type

Return the product_type property of this object.

property publication_delay: str

Publication delay of data for this group.

query_instrument_names() → list[str]

Generic doc store query to retrieve names of objects meeting filter criteria. :return: List of object names meeting filter criteria.

query_instruments() → list[sigtech.framework.internal.infra.objects.core.framework_object.FrameworkObject]

Generic doc store query to retrieve objects meeting filter criteria. :return: List of objects meeting filter criteria

property sector

Sector used on BBG, or the class ID for SIG instruments.

session_data()

Returns the raw Copp-Clarke trading sessions data for this group

static sort_key_static(name)

Convert a name to the sort key as of Portfolio Presentation Guidelines for performance reasons.

Parameters

name – Input name.

Returns

Tuple (sort key, length of sort key, input name).

textual_representation()

Return a printable representation of this object.

validate()

Validation routine adding checks that will be run on object creation.

data_source_all: Optional[list[str]]

instrument_id: Optional[int]