NFCP (version 1.2.1)

stitch_contracts: Stitch futures contracts

Description

Aggregate futures contract price data by stitching according to either approximate maturities and rollover frequency or contract number from closest maturity.

Usage

stitch_contracts(
  futures,
  futures_TTM = NULL,
  maturity_matrix = NULL,
  rollover_frequency = NULL,
  contract_numbers = NULL,
  verbose = FALSE
)

Arguments

futures

Contract futures price data. Each row of Futures should represent one observation of futures prices and each column should represent one quoted futures contract. NA's in Futures are allowed, representing missing observations.

futures_TTM

A vector of contract maturities to stitch

maturity_matrix

The time-to-maturity (in years) for each contract at each given observation point. The dimensions of maturity_matrix should match those of Futures

rollover_frequency

the frequency (in years) at which contracts should be rolled over

contract_numbers

A vector of contract numbers offset from the closest-to-maturity contract at which to stitch contracts.

verbose

logical. Should additional information be output? see details

Value

stitch_contracts returns a matrix of stitched futures prices if verbose = T and a list with two or three objects otherwise (see below).

prices	A data frame of Stitched futures prices. Each row represents an observation of the specified contracts.
maturities	A data frame of the time-to-maturity of observed futures prices. Each row represents an observation of the specified contracts. Returned only when Method 1 is used (see Details) and verbose = T.
tickers	A data frame of the named columns of observed futures prices (e.g. contract tickers). Returned only when Futures or maturity_matrix have named columns and verbose = T.

Details

This function aggregates a set of futures contract data by stitching contract data over an observation period, resulting in a set of futures observations that is 'complete' (ie. Does not feature missing observations). Aggregated futures data benefit from several computational efficiencies compared to raw contract data, but results in the loss of futures price information.

There are two methods of the stitch_contracts function that can be utilized the stitch contracts:

Method 1

stitch_contracts(futures, contract_numbers, verbose = T) Futures data may be aggregated by stitching prices according to maturity matching. This method requires the inputs futures_TTM, maturity_matrix and rollover_frequency. This method stitched contracts by matching the observation prices according to which contract has the closest time-to-maturity of the desired maturity specified in futures_TTM. Contracts are rolled over at the frequency specified in rollover_frequency.

Method 2

stitch_contracts(futures, futures_TTM, maturity_matrix, rollover_frequency, verbose = T) Futures data may be stitched according to the contract numbers offset from the closest-to-maturity contract. This method requires only the input contract_numbers specifying which contracts should be included. This method is most appropriate when the maturity of available contracts are consistent (ie. contracts expire every month or three months).

References

Schwartz, E. S., and J. E. Smith, (2000). Short-Term Variations and Long-Term Dynamics in Commodity Prices. Manage. Sci., 46, 893-911.

Cortazar, G., and L. Naranjo, (2006). An N-factor Gaussian model of oil futures prices. Journal of Futures Markets: Futures, Options, and Other Derivative Products, 26(3), 243-268.

Examples

# NOT RUN {

##These examples approximately replicate the Crude Oil data utilized within the
##prominent work of Schwartz and Smith (2000):

###Method 1 - Stitch crude oil contracts according to maturity matching:
SS_stitched_M1 <- stitch_contracts(futures = SS_oil$contracts,
                                  futures_TTM = c(1, 5, 9, 13, 17)/12,
                                  maturity_matrix = SS_oil$contract_maturities,
                                  rollover_frequency = 1/12, verbose = TRUE)

###Method 2 - Stitch crude oil contracts according to nearest contract numbers:
SS_stitched_M2 <- stitch_contracts(futures = SS_oil$contracts,
                                  contract_numbers = c(1, 5, 9, 13, 17), verbose = TRUE)

# }