adjust_contract and select

adjust_contract and select_contract Syntax

adjust_contract and select_contract are studies that you can use at any point in an XMIM query in order to determine the rollover policy for a series that is included in the query. The primary use of adjust_contract is for a user to customize the way a study in XMIM handles futures continuation crossover. The default assumption in an XMIM study is for the price difference between the old or expiring contract and the new contract to be subtracted or backed out of the equation as of the expiration date. adjust_contract lets you alter that default to a custom policy.

The adjust_contract syntax may also be used in a query to indicate a custom rollover date and policy in a slightly more flexible way that the rollover policy syntax. It is possible for example, to use adjust_contract to create a series where the rollover policy is based on the expiration of another commodity. This is frequently used in energy analysis to create crack spread refining margin calculations.

The select_contract syntax allows you to refer to a particular futures contract in relative terms, for example the nearest January contract or the second nearest January contract etc.

adjust_contract

There are four fields that are required to be specified within this syntax- the attribute or series, the deferred number of the contract chosen (i.e., 1 represents the contract nearest to expiration or the front contract, 2 represents the second nearest contract to expiration, etc.), the number of days until expiration that the contract should be followed (i.e. 0 specifies that the contract will be active until expiration, 1 specifies that the contract will be active or followed up until 1 day before expiration, etc.) and contract month which is the parameter which specifies the contract month of interest (i.e., Setting the field to 0 will disable this field thereby allowing the contract to roll to the regularly traded serial months, setting the field to 1 will specify only January contracts, etc.).

where is computed by offsetting each relation of type futures in X with an appropriate amount so that the expiration-day boundaries do not introduce an artificial jump.

Example 1: adjust_contract

Consider the trading day of 10/8/2002 for the following scenarios.

The prompt crude oil contract would be Nov 2002, CL_2002X .

The following shows the adjust_contract data table:

Date         LIM SYMBOL                 adjust_contract version

10/8/2002    CL_2002Z - Close           adjust 1st December contract out
                                        adjust_contract (CL, 1, 0, 12)
                                29.51                                     29.51
             CL_2003J - Close           adjust 6th contract month out
                                        adjust_contract (CL, 6, 0, 0)
                                27.6                                      27.6
             CL_2004H - Close           adjust 2nd March contract out
                                        adjust_contract (CL, 2, 0, 3)
                                23.86                                     23.86
             CL_2005F - Close           adjust 3rd January contract out
                                        adjust_contract (CL, 3, 2, 1)
                                23.03                                     23.03

Let’s look closer at each of these to see how the adjust_contract function chooses the correct contract.

December 2002 contract: This is the nearest December contract right now. The explicit LIM symbol is CL_2002Z. To ask for the closest contract month using adjust_contract you fill in adjust_contract (1, 12), where:

CL = base commodity symbol of choice.
1 = N nearest. 3 would imply the 3rd nearest, 6 the 6th nearest.
0 = This is “Number of days before Expiration”. Setting this number to 0 indicates the series will locate the next nearest contract when the contract expires. Setting this number to 4 would mean that the contract should roll to the next one 4 days before expiration of the current contract.
12 = This is the contract month specification, Numerical values represent certain months: 12 equals December, 5 equals May, 7 equals July and so on for values between 1-12.
Setting this number to 0 makes the parameter inactive, meaning the other parameters will determine the behavior.

April 2003 contract: This is the 6th nearest contract out. The explicit LIM symbol is CL_2003J. To ask for the literal N contract out using adjust_contract, you fill in adjust_contract (CL, 0, 0), where:

CL= base commodity symbol of choice.
6 = N nearest. 6 points to the 6th closest or nearest to expiration active contract.
0 = This is “Number of days before Expiration”. Setting this to 0 indicates the series will locate the next nearest contract when the contract expires. Setting this to 4 would mean that the contract should roll to the next one 4 days before expiration of the current contract.
0 = Normally, this is where you put in the contract month. However, since we want the exact 6th closest contract, this is set to 0.

March 2004 contract: This is the 2nd nearest March contract. The 1st nearest is the March 2003 contract. The 3rd nearest would be March 2005. To ask for the 2nd nearest March using adjust_contract, you would fill in adjust_contract (2, 3) where:

CL = base commodity symbol of choice.
2 = 2nd nearest
0 = This is “Number of days before Expiration”. Setting this to 0 indicates the series will locate the next nearest contract when the contract expires.
3 = March contract.

January 2005 contract: This is the 3rd nearest January contract. The closest or first nearest would be January 2003. To ask for the 3rd nearest using adjust_contract, you will fill in adjust_contract (CL, 2, 1), where:

CL = base commodity symbol of choice
3 = 3rd nearest
2 = This is “Number of days before Expiration”. Setting this to 2 indicates the series will roll 2 days before the contract expires and choose the next 3rd nearest contract.
1 = January contract.

Example 2: Using adjust_contract to Create a Crack Spread

The following example shows how you can use adjust_contract to make the rollover policy of one commodity the same as the rollover policy of another commodity.

This particular functionality is typically used in the energy business for the analysis of Crude Oil and Products. Crude is the raw material commodity and is traded as a future on the NYMEX (CL) and the IPE (FB). The constituent products (finished goods) that are refined from Crude are also traded on the NYMEX (HU and HO) and IPE (FP).

It is natural for traders and analysts to want to compare the price of these raw materials with their finished goods to estimate the refining margin. These crude/product spreads are known as Crack spreads after a common refinery process unit called a Hydrocracker.

Looking at the spread between different futures commodities also means looking at the spread between different continuation series for these commodities. When you compare two commodities as continuation series, you want to compare apples with apples, so the rollover policies need to be in line. In reality the crude contracts roll at different times of the month to the products.

To calculate a true crack spread, the relevant products and crudes need to have their rollover policy adjusted so that they roll on the same day as each other.

Problem:

NYMEX Crude (CL) rolls on or about the 20^th day of the month

NYMEX Gasoline (HU) and NYMEX Heating OIL (HO) roll on the last day of the month.

We need to adjust the rollover of gasoline and heating oil to coincide with the crude rollover before we calculate the crack spread.

Solution:

Use the adjust_contract function, together with an IF statement to create new series for Heating Oil (or Gasoline) that roll when Crude expires.

Example:

IF Date is from CL expiration_day to HU expiration_day THEN adjust_contract ( HU, 2, 0, 0 ) ELSE adjust_contract ( HU, 1, 0, 0 ) ENDIF

The example simply determines which HU contract to use to create the continuation by reference to a date condition triggered by the expiration of the CL contract.

The result is a series that always rolls on the same day as crude.

This series then can be used against CL to create a gas crack as follows:

LET
    ATTR RolledUnlead= IF 
   Date is from CL  expiration_day to HU expiration_day 
   THEN adjust_contract ( HU, 2, 0, 0 ) 
   ELSE adjust_contract ( HU, 1, 0, 0 ) 
   ENDIF
SHOW:
  1: RolledUnlead – CL
WHEN
  Date is within one year

Complex Crack Spread Example:

This is an example of a NYMEX 3-2-1 Crack Spread:

  LET 
     ATTR roll_HO = IF 
                        Date is from CL  expiration_day to HO  expiration_day 
                    THEN adjust_contract ( HO, 2, 0, 0 ) 
                    ELSE adjust_contract ( HO, 1, 0, 0 ) 
                    ENDIF  
   LET 
     ATTR roll_HU = IF 
                        Date is from CL  expiration_day to HU  expiration_day 
                    THEN adjust_contract ( HU, 2, 0, 0 ) 
                    ELSE adjust_contract ( HU, 1, 0, 0 ) 
                    ENDIF  
   SHOW 
     1: (roll_HU * 0.28 + roll_HO * 0.14) - Close of CL 
   WHEN 
       Date is within 1 year

Example 3: More Real-World Examples

How do you ask for?

Spread between the 2nd December and the 1st December contract. Often times this is referred to as a Dec – Red Dec spread.
```
adjust_contract (CL, 1, 0, 12) – adjust_contract (CL, 2, 0, 12)
```

The spread between the 1st and 2nd nearby contracts.

adjust_contract (CL, 1, 0, 0) – adjust_contract (CL, 2, 0, 0)

The 3rd nearest November contract.
```
adjust_contract (CL, 3, 0, 11)
```
The 15th closest contract out.
```
adjust_contract (CL, 15, 0, 0)
```

select_contract

The select_contract function is used to ‘anchor' the current contract that satisfies our expiration requirements (i.e., if the front contract is the March 1998 contract, the studies will be performed exclusively on this contract and will ignore all previous contracts that meet our expiration requirement). There are four fields that are required to be specified within this syntax- the Attribute or series (select your futures series), the deferred number of the contract chosen (i.e., 1 represents the contract nearest to expiration or the front contract, 2 represents the second nearest contract to expiration, etc.), the number of days until expiration that the contract should be followed (i.e., 0 specifies that the contract will be active until expiration, 1 specifies that the contract will be active or followed up until 1 day before expiration, etc.) and contract month which is the parameter which specifies the contract month of interest (i.e., Setting the field to 0 will disable this field thereby allowing the contract to roll to the regularly traded serial months. Setting the field to 1 will specify only January contracts, etc.).

whereis computed by replacing all references to a relation in X with the corresponding current contract. The current contract is selected as in adjustContract.

Example 1: select_contract

Consider the trading day of 10/8/2002 for the following scenarios.

The prompt crude oil contract would be Nov 2002, CL_2002X .

The following shows the select_contract data table:

Date         LIM SYMBOL                 adjust_contract version

10/8/2002    CL_2002Z - Close           adjust 1st December contract out
                                        select_contract (CL, 1, 0, 12)
                                29.51                                     29.51
             CL_2003J - Close           adjust 6th contract month out
                                        select_contract (CL, 6, 0, 0)
                                27.6                                      27.6
             CL_2004H - Close           adjust 2nd March contract out
                                        select_contract (CL, 2, 0, 3)
                                23.86                                     23.86
             CL_2005F - Close           adjust 3rd January contract out
                                        select_contract (CL, 3, 2, 1)
                                23.03                                     23.03

Let’s look closer at each of these to see how the select_contract function chooses the correct contract.

December 2002 contract: This is the nearest December contract right now. The explicit LIM symbol is CL_2002Z. To ask for the closest contract month using select_contract you fill in select_contract (CL, 1, 0, 12), where:

CL = base commodity symbol of choice.
1 = N nearest. 3 would imply the 3rd nearest, 6 the 6th nearest.
0 = This is “Number of days before Expiration”. Setting this number to 0 indicates the series will locate the next nearest contract when the contract expires. Setting this number to 4 would mean that the contract should roll to the next one 4 days before expiration of the current contract.
12 = This is the contract month, 12 equals December, 5 equals May, 7 equals July.

Setting this number to 0 makes the parameter inactive, meaning the other parameters will determine the behavior.

April 2003 contract: This is the 6th nearest contract out. The explicit LIM symbol is CL_2003J. To ask for the literal N contract out using select_contract, you fill in select_contract (CL, 6, 0, 0), where:

CL= base commodity symbol of choice.
6 = N nearest. 6 points to the 6th closest or nearest to expiration active contract.
0 = This is “Number of days before Expiration”. Setting this to 0 indicates the series will locate the next nearest contract when the contract expires. Setting this to 4 would mean that the contract should roll to the next one 4 days before expiration of the current contract.
0 = Normally, this is where you put in the contract month. However, since we want the exact 6th closest contract, this is set to 0.

March 2004 contract: This is the 2nd nearest March contract. The 1st nearest is the March 2003 contract. The 3rd nearest would be March 2005. To ask for the 2nd nearest March using select_contract, you would fill in select_contract (CL, 2, 0, 3) where:

CL = base commodity symbol of choice.
2 = 2nd nearest
0 = This is “Number of days before Expiration”. Setting this to 0 indicates the series will locate the next nearest contract when the contract expires.
3 = March contract.

January 2005 contract: This is the 3rd nearest January contract. The closest or first nearest would be January 2003. To ask for the 3rd nearest using select_contract, you will fill in select_contract (CL, 2, 1), where:

CL = base commodity symbol of choice
3 = 3rd nearest
2 = This is “Number of days before Expiration”. Setting this to 2 indicates the series will roll 2 days before the contract expires and choose the next 3rd nearest contract.
1 = January contract.

Example 2: select_contract

SHOW  
     NGjan: select_contract ( NG, 1, 0, 0 ) 
     NGfeb: select_contract ( NG, 2, 0, 0 ) 
     NGmar: select_contract ( NG, 3, 0, 0 ) 
     avg: (select_contract ( NG, 1, 0, 0 )  +  select_contract ( NG, 2, 0, 0 ) +select_contract (  NG, 3, 0, 0 ) 
     )/3
WHEN
     Date is December

Prev	Up	Next
Examples with Data	Home	Appendix D: Studies and Server Macros