Mappings for generic and tradeable futures instruments

pip install mapping==0.1.6



PyPI version Build Status Coverage Status


mapping provides functionality for mapping to and from generic exposures and tradeable instruments for financial assets.

An example of this might be on 2016-12-01 we would have CL1 -> CLZ16, i.e. the first generic for Crude oil on the above date corresponds to trading the December 2016 contract.

The main features of mapping include:

  • creating continuous return series for Futures instruments
  • creating time series of percentage allocations to tradeable contracts
  • creating instrument trade lists

Currently there is no support for indexing/futures instrument rescaling, e.g. what happened to the VIX, discussed here. This should accounted for by rescaling the instrument data upstream of using mapping


The mapping of instruments to and from generics is equivalent to solving the equation Ax = b where A is the weights and b is the instrument holdings. When Ax = b has no solution we solve for x' such that Ax' is closest to b in the least squares sense with the additional constraint that sum(x') = sum(instruments).

A more realistic example of a mapping is given below

Generic Instruments
CL1 CL2 Scenario 1 Scenario 2 Scenario 3
CLX16 0.5 0 10 10 10
CLZ16 0.5 0.5 20 20 25
CLF17 0 0.5 10 11 11

Which would result in the following solutions to the mapping from instruments to generics

Generic Scenario 1 Scenario 2 Scenario 3
CL1 20 19.5 22
CL2 20 21.5 24


A general workflow for using mapping for mapping from generics to tradeable instruments is as follows


The layout for mapping from tradeables to generics is as follows



You can pip install this package from github, i.e.

pip install git+git://

mapping is also available on PyPI, you can pip install the latest version using

pip install mapping