Rolltables made easy

Major commodity future indices, like the Bloomberg Commodity Index (BCOM) and the S&P GSCI periodically roll future contracts following a pre-determined contract schedule. Such a schedule is known as a rolltable. The rolltables module provides an easy-to-use interface to resolve active future contracts and prior contracts.

Quickstart

Installing rolltables is simple with pip:

$ pip install rolltables

Using rolltables is also easy

>>> from datetime import date
>>> from rolltables import Rolltable, BCOM, GSCI

#determine the current active contract
>>> BCOM.resolve("CL", date(2020, 2, 1) "roll-out")
'CLH2020'

#determine the next active future
>>> BCOM.resolve("CL", "F0", 2, 2020, "roll-in")
'CLK2020'

#resolve the F6 contract
>>> BCOM.resolve("CL", "F6", 2, 2020, "roll-in")
'CLX2020'

#resolve the C2 contract (2nd distinct contract after F0)
>>> BCOM.resolve("CL", "C2", 2, 2020, "roll-in")
'CLU2020'

#check whether a contract is in the rolltable
>>> 'CLX2019' in BCOM, 'CLZ2019' in BCOM
True, False

Creating your custom rolltable

Creating a rolltable simply involves either parsing a pd.DataFrame or passing a dictionary mapping a commodity name (e.g. NG) to a list of nearby contracts. Each contract should be comprised of a month letter (F for January…) and a year offset (0 for the same month, 1 for next year, etc.)

>>> from rolltables import Rolltable

#you can parse a pandas.DataFrame
#the dataframe should have 12 columns, with the index representing commodity names
>>> table = Rolltable.parse(data, "roll-in")

#alternatively construct a rolltable from scratch
>>> table = Rolltable({"CL":["G0","H0","J0","K0","M0","N0","Q0","U0","V0","X0","Z0","F1"]}, "roll-in")
>>> table.resolve("CL", "F0", 3, 2020)
'CLJ2020'

Warning

the rolltables module comes with the BCOM and GSCI rolltables preloaded, but you should not rely on the accuracy of these for your production code.

Design choices

the rolltable.resolve method takes 5 arguments:

  1. the commodity shortcode (e.g. NG)
  2. the forward name (one of F0..F6 or one of C1..C6)
  3. the month (e.g. 1 for January)
  4. the year (e.g. 2020)
  5. one of ‘roll-in’ or ‘roll-out’ to disambiguate which contract is being resolved

Note

Why not take a date in lieu of the 3rd and 4th argument? Some indices pre-roll ahead of the benchmarks - the above approach forces the user to unambiguously specify which month the rolltable should resolve.

Note

What are Fx and Cx forwards? F forwards are the contracts the index will hold in x months from today: the F1 is simply the contract that will be held in a month’s time.

Prior contract tables

A contract’s prior contract is the future contract expiring immediately before the given contract. These prior contracts may or may not be in a rolltable; as such, the F0 contract is not necessarily the prior contract of the F1 contract. The Priortable object allows to resolve this contract easily.

>>> from rolltables.priortables import Priortable, BCOMRS

>>> BCOMRS.resolve("CLX2020")
'CLV2020'

Warning

the rolltables module comes with the BCOMRS prior contract table preloaded, but you should not rely on the accuracy of this table for your production code.

Utils

Using the utility functions and classes can help you express the logic of rolling commodity futures.

>>> from rolltables import F

>>> F(1) + 1
'F2'

>>> C(4) - 1
'C3'

API Documentation

Rolltable

class rolltables.Rolltable(table, tabletype='roll-out')

Class designed to interface a commodity roll-table, where users can resolve the current forward (“F0”) contract or any other contract that would be be the current forward contract some months from the given review date

Parameters:
  • table (dict) – a mapping of commodity tickers to list of 12 contracts e.g. {"CL":["G0","G0",...,"Z0","F1"]}
  • tabletype (str, optional (defaults to 'roll-out')) – must be one of ‘roll-in’ or ‘roll-out’ specifies whether the provided table is a roll-out table or a roll-in table, i.e. whether the contract listed for each month is the contract that prevails before or after the roll period.
Raises:

ValueError – on invalid arguments

classmethod parse(data, tabletype='roll-out')

converts a pd.Series or a pd.DataFrame into a rolltable

priortable

Returns the priortable

Note

The priortable includes only those contracts in the rolltable. Users will most generally use a generic prior table rather than the priortable of a given rolltable.

reverse(future, month, year, which=None)

resolves the F-name of the given future contract as long as the contract is within 9 Fs of the current F0 if the same contract is held over several rolltables.constants.MONTHS, this returns the nearest F-name from the current F0

Parameters:
  • future (str) – a future full name (e.g. CLZ2019)
  • month (int) – must be one of 1..12
  • year (int:) – must be one of 1950..2050
  • which (str, optional) – must be one of None, ‘roll-in’ or ‘roll-out’ specifies whether the requested forward should be the one that prevails before or after the roll period if which is None, then it is assumed it is the same as the table type
Returns:

F-name – one of [F-9..F9]

Return type:

str

Raises:

ValueError: – on invalid arguments

shift(offset, tabletype=None)

Returns a roll table shifted by an offset. A positive offset (e.g. +1) will shift the table forward, i.e. the F1 will become the new F0 (assuming tabletype is unchanged). A negative offset (e.g. -1 will shift the table backward).

Example

>>> table = {"CL":["H0","H0","K0"..."X0"]}
>>> rolltable = Rolltable(table, tabletype="roll-in")
>>> rolltable.shift(1).table
{"CL":["HO","K0"..."H1"]}

Priortable

class rolltables.Priortable(table)

Class designed to interface a prior contract table

Parameters:table (dict) – a mapping of commodity tickers to mapping of contracts to prior contracts e.g. "CL":{"F":"Z", ..., "Z":"X"}
get(future)

alias for resolve

resolve(future)

resolves the prior contract for a given future contract, i.e. the eligible contract that expires immeditely before the given future

Parameters:future (str) – the name of the future contract for which we resolve the prior contract e.g. CLZ2019
Returns:prior contract
Return type:str
Raises:ValueError – if the commodity is not in the prior contract table if the month is not in the prior contract table