Stitch.Contracts: Stitch Futures Contracts
In TomAspinall/TSE: N-Factor Commodity Pricing Models

Description Usage Arguments Details Value References Examples

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

Stitch.Contracts(
  Futures,
  TTM = NULL,
  maturity.matrix = NULL,
  rollover.frequency = NULL,
  Contract.Numbers = NULL,
  verbose = FALSE
)

`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.
`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

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 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 TTM. Contracts are rolled over at the frequency specified in rollover.frequency.

Method 2

Stitch.Contracts(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).

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.

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.

##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:
SSOilStitched.M1 <- Stitch.Contracts(Futures = SS.Oil$Contracts,
TTM = c(1, 5, 9, 13, 17)/12, maturity.matrix = SS.Oil$Contract.Maturities,
rollover.frequency = 1/12, verbose = TRUE)

##Not Run - Plot the Stitched Maturities:
#matplot(SSOilStitched.M1$Maturities, type = 'l')

###Method 2 - Stitch Crude Oil Contracts according to Contract Numbers:
SSOilStitched.M2 <- Stitch.Contracts(Futures = SS.Oil$Contracts,
Contract.Numbers = c(1, 5, 9, 13, 17), verbose = TRUE)

##Not Run - Plot the Stitched Futures Prices:
#matplot(SSOilStitched.M2$Prices, type = 'l')