arbitragelab.util.base_futures_roller

This module implements the base Futures Roller.

Module Contents

Classes

BaseFuturesRoller

Basic Futures Roller implementation.
class BaseFuturesRoller(open_col: str = 'PX_OPEN', close_col: str = 'PX_LAST')

Basic Futures Roller implementation.

fit(dataset: pandas.DataFrame)

Stores price data in the class object for later processing.

Parameters:

dataset – (pd.DataFrame) Future price data.

diagnostic_summary() → pandas.DataFrame

After the dataset has been transformed, a dataframe with all the dates of each roll operation is stored in the class object. This will return that dataframe.

Returns:

(pd.DataFrame) Returns DataFrame with each roll and gap size.

transform(roll_forward: bool = True, handle_negative_roll: bool = False) → pandas.Series

Processes the dataset provided with the set roll dates.

Parameters:

  • roll_forward – (bool) The direction which the gaps should sum to.

  • handle_negative_roll – (bool) Process to remove negative values from series.

Returns:

(pd.Series) Series of gaps or Preprocessed rolled series.

generate_diagnostic_frame(dataset: pandas.DataFrame, termination_date_indexes: numpy.array, following_dates: pandas.DatetimeIndex) → pandas.DataFrame

Returns dataframe full of every roll operation and its gap size.

Parameters:

  • dataset – (pd.DataFrame) Price data.

  • termination_date_indexes – (np.array) Indexes of termination dates.

  • following_dates – (pd.DateTimeIndex) Dates following the termination dates.

Returns:

(pd.DataFrame) List of dates and their gap’s size.

static get_x_days_prior_available_target_date(n_days: int, dataset_datetime_index: pandas.DatetimeIndex, target_dates: pandas.DatetimeIndex) → pandas.DataFrame

Gets x days prior to target date(that must be available in the dataset index).

Parameters:

  • n_days – (int) Number of days to be shifted by.

  • dataset_datetime_index – (pd.DateTimeIndex) All dates that occur in the dataset

  • target_dates – (pd.DateTimeIndex) Dates used as the start for the shift. Important(!) these dates need to exist in ‘dataset_datetime_index’.

Returns:

(pd.Series) Price series x days prior to target date.

static get_available_date_per_month_from(price_df: pandas.DataFrame) → pandas.DataFrame

Gets first available day per month from the dataset.

Parameters:

price_df – (pd.DataFrame) Original prices dataframe.

Returns:

(pd.DataFrame) Frame with first available days per month.

static get_all_possible_static_dates_in(dataset_datetime_index: pandas.DatetimeIndex, day_of_month: int = 25) → pandas.DataFrame

Gets a series of static dates that could happen in a specific time range, described by the input ‘dataset_datetime_index’. The dates returned from this method do not take into consideration the fact of if the specified date happened in the dataset or not.

Parameters:

  • dataset_datetime_index – (pd.DateTimeIndex) All dates that occur in the dataset.

  • day_of_month – (int) Day of month.

Returns:

(pd.DataFrame) Dates.

static get_x_days_prior_missing_target_date(dataset: pandas.DataFrame, working_month_delta: pandas.Period, days_prior: int = 3, target_day: int = 25)

This method will get x available day prior to a specific date, in the special case that that date doesn’t exist in the dataset.

Parameters:

  • dataset – (pd.DataFrame) Price data.

  • working_month_delta – (pd.Period) specific Year-Month delta, ex. 1995-12

  • days_prior – (int) Days prior the newly found target date.

  • target_day – (int) The target day to be used as a starting point.

Returns:

(np.array) Target Dates.

roll(dataset: pandas.DataFrame, roll_dates: pandas.Series, match_end: bool = True)

Deals with single futures contracts. Forms a series of cumulative roll gaps and returns a diagnostic dataframe with dates of rolls for further analysis.

Parameters:

  • dataset – (pd.DataFrame) Price data.

  • roll_dates – (pd.Series) Specific dates that the roll will initialized on.

  • match_end – (bool) Defines from where to match the gaps.

Returns:

(pd.Series) (pd.DataFrame) Returns gaps and diagnostic frame.

static non_negativeize(rolled_series: pandas.Series, raw_series: pandas.Series) → pandas.Series

In general, non-negative series are preferred over negative series, which could easily occur, particularly if the contract sold off while in contango. The method employed here works as follows: the return as rolled price change is divided by the raw price and then a series is formed using those returns, ex (1+r).cumprod().

This method has been described originally in De Prado, M.L., 2018. “Advances in financial machine learning”. John Wiley & Sons.

Parameters:

  • rolled_series – (pd.Series) Rolled price change.

  • raw_series – (pd.Series) Raw price.

Returns:

(pd.Series) Resulting non-negative series.