CommodityFuture

CommodityFuture instrument object

Since R2022a

Description

Create and price a CommodityFuture instrument object for one or more Commodity Future instruments using this workflow:

1. Use fininstrument to create a CommodityFuture instrument object for one or more Commodity Future instruments.

2. Use ratecurve to specify a curve model for the CommodityFuture instrument object.

3. Use finpricer to specify a Future pricing method for one or more CommodityFuture instruments.

4. Use cashsettle to compute the cash settlement for the CommodityFuture instrument and fairdelivery to compute the fair delivery price for the underlying asset for the CommodityFuture instrument.

For more detailed information on this workflow, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.

For more information on the available models and pricing methods for a CommodityFuture instrument, see Choose Instruments, Models, and Pricers.

Creation

Syntax

CommodityFutureObj = fininstrument(InstrumentType,Maturity=maturity_value,QuotedPrice=quoted_price)

CommodityFutureObj = fininstrument(___,Name=Value)

Description

CommodityFutureObj = fininstrument(InstrumentType,Maturity=maturity_value,QuotedPrice=quoted_price) creates a CommodityFuture object for one of more Commodity Future instruments by specifying InstrumentType and sets the properties for the required name-value arguments Maturity and QuotedPrice.

You can use commodity futures for commodity futures and forwards. The main difference between forward and futures contracts:

• Forward contracts are private contracts between two parties, while futures contracts are more standardized and are traded on an exchange.

• Futures contracts are marked-to-market with corresponding settlement cash flows occurring on every trading day, while forward contract cash flows and deliveries do not occur until the maturity of the forward contract.

The CommodityFuture instrument supports oil, natural gas, gold, silver, and wheat, and other commodities. For more information, see Commodity Future.

CommodityFutureObj = fininstrument(___,Name=Value) sets optional properties using additional name-value arguments in addition to the required arguments in the previous syntax. For example, CommodityFutureObj = fininstrument("CommodityFuture",Maturity=datetime(2022,9,1),QuotedPrice=68,StorageCost=1000,Income=500,PercentStorageCost=0.03,Name="commodity_future_instrument") creates a CommodityFuture. You can specify multiple name-value arguments.

Input Arguments

InstrumentType — Instrument type

string with value "CommodityFuture" | string array with values of "CommodityFuture" | character vector with value 'CommodityFuture' | cell array of character vectors with values of 'CommodityFuture'

Instrument type, specified as a string with the value of "CommodityFuture", a character vector with the value of 'CommodityFuture', an NINST-by-1 string array with values of "CommodityFuture", or an NINST-by-1 cell array of character vectors with values of 'CommodityFuture'.

Data Types: char | cell | string

Name-Value Arguments

Specify required and optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: CommodityFutureObj = fininstrument("CommodityFuture",Maturity=datetime(2022,9,1), QuotedPrice=68,StorageCost=1000,Income=500,PercentStorageCost=0.03,Name="commodity_future_instrument")

Required CommodityFuture Name-Value Arguments

Maturity — CommodityFuture maturity date

datetime array | string array | date character vector

CommodityFuture maturity date, specified as Maturity and a scalar or an NINST-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, CommodityFuture also accepts serial date numbers as inputs, but they are not recommended.

If you use date character vectors or strings, the format must be recognizable by datetime because the Maturity property is stored as a datetime.

QuotedPrice — CommodityFuture quoted price

scalar numeric | numeric vector

CommodityFuture quoted price, specified as QuotedPrice and a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

Optional CommodityFuture Name-Value Arguments

StorageCost — Present value of storage cost for life of contract

0 (default) | scalar numeric | numeric vector

Present value of storage cost for the life of the contract, specified as StorageCost and a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

Income — Present value of income for life of contract

0 (default) | scalar numeric | numeric vector

Present value of income for the life of the contract, specified as Income and a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

PercentStorageCost — Annualized percentage storage cost

0 (default) | scalar decimal | vector of decimals

Annualized percentage storage cost, specified as PercentStorageCost and a scalar decimal or an NINST-by-1 vector of decimals.

Data Types: double

PercentStorageCostCompounding — Compounding frequency for PercentageStorageCost

-1 (continuous compounding) (default) | scalar integer with value of -1, 0, 1, 2, 4, 6, or 12 | vector of integers with values -1, 0, 1, 2, 4, 6, or 12

Compounding frequency for PercentageStorageCost, specified as PercentStorageCostCompounding and a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

PercentageStorageCostBasis — Day count basis for PercentStorageCost

0 (actual/actual) (default) | scalar integer from 0 to 13 | vector of integers from 0 to 13

Day count basis for PercentageStorageCost, specified as PercentageStorageCostBasis and scalar integer or an NINST-by-1 vector of integers using the following values:

• 0 — actual/actual

• 1 — 30/360 (SIA)

• 2 — actual/360

• 3 — actual/365

• 4 — 30/360 (PSA)

• 5 — 30/360 (ISDA)

• 6 — 30/360 (European)

• 7 — actual/365 (Japanese)

• 8 — actual/actual (ICMA)

• 9 — actual/360 (ICMA)

• 10 — actual/365 (ICMA)

• 11 — 30/360E (ICMA)

• 12 — actual/365 (ISDA)

• 13 — BUS/252

For more information, see Basis.

Data Types: double

ConvenienceYield — Annualized convenience yield

0 (default) | scalar decimal | vector of decimals

Annualized convenience yield, specified as ConvenienceYield and a scalar decimal or an NINST-by-1 vector of decimals.

Data Types: double

ConvenienceYieldCompounding — Compounding frequency for ConvenienceYield

1 (continuous compounding) (default) | scalar integer with value of -1, 0, 1, 2, 4, 6, or 12 | vector of integers with values -1, 0, 1, 2, 4, 6, or 12

Compounding frequency for ConvenienceYield, specified as ConvenienceYieldCompounding and a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

ConvenienceYieldBasis — Day count basis for ConvenienceYield

0 (actual/actual) (default) | scalar integer from 0 to 13 | vector of integers from 0 to 13

Day count basis for ConvenienceYield, specified as ConvenienceYieldBasis and scalar integer or an NINST-by-1 vector of integers using the following values:

• 0 — actual/actual

• 1 — 30/360 (SIA)

• 2 — actual/360

• 3 — actual/365

• 4 — 30/360 (PSA)

• 5 — 30/360 (ISDA)

• 6 — 30/360 (European)

• 7 — actual/365 (Japanese)

• 8 — actual/actual (ICMA)

• 9 — actual/360 (ICMA)

• 10 — actual/365 (ICMA)

• 11 — 30/360E (ICMA)

• 12 — actual/365 (ISDA)

• 13 — BUS/252

For more information, see Basis.

Data Types: double

Name — User-defined name for instrument

"" (default) | string | string array | character vector | cell array of character vectors

User-defined name for one or more instruments, specified as Name and a scalar string or character vector or an NINST-by-1 cell array of character vectors or string array.

Data Types: char | cell | string

Properties

Maturity — CommodityFuture maturity date

scalar datetime | vector of datetimes

CommodityFuture maturity date, returned as a scalar datetime or NINST-by-1 vector of datetimes.

Data Types: datetime

QuotedPrice — CommodityFuture quoted price

scalar numeric | numeric vector

CommodityFuture quoted price, returned as a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

StorageCost — Present value of storage cost for life of contract

0 (default) | scalar numeric | numeric vector

Present value of storage cost for the life of the contract, returned as a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

Income — Present value of income for life of contract

0 (default) | scalar numeric | numeric vector

Present value of income for the life of the contract, returned as an NINST-by-1 numeric vector.

Data Types: double

PercentStorageCost — Annualized percentage storage cost

0 (default) | scalar decimal | vector of decimals

Annualized percentage storage cost, returned as a scalar decimal or an NINST-by-1 vector of decimals.

Data Types: double

PercentStorageCostCompounding — Compounding frequency for PercentageStorageCost

-1 (continuous compounding) (default) | scalar integer with value of -1, 0, 1, 2, 4, 6, or 12 | vector of integers with values -1, 0, 1, 2, 4, 6, or 12

Compounding frequency for PercentageStorageCost, returned as a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

PercentageStorageCostBasis — Day count basis for PercentStorageCost

0 (actual/actual) (default) | scalar integer from 0 to 13 | vector of integers from 0 to 13

Day count basis for PercentageStorageCost, returned as a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

ConvenienceYield — Annualized convenience yield

0 (default) | scalar decimal | vector of decimals

Annualized convenience yield, returned as a scalar decimal or an NINST-by-1 vector of decimals.

Data Types: double

ConvenienceYieldCompounding — Compounding frequency for ConvenienceYield

1 (continuous compounding) (default) | scalar integer with value of -1, 0, 1, 2, 4, 6, or 12 | vector of integers with values -1, 0, 1, 2, 4, 6, or 12

Compounding frequency for ConvenienceYield, returned as a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

ConvenienceYieldBasis — Day count basis for ConvenienceYield

0 (actual/actual) (default) | scalar integer from 0 to 13 | vector of integers from 0 to 13

Day count basis for ConvenienceYield, returned as a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

Name — User-defined name for instrument

"" (default) | string | string array

User-defined name for the instrument, returned as a scalar string or an NINST-by-1 string array.

Data Types: string

Object Functions

cashsettle	Compute cash settlement for BondFuture, CommodityFuture, EquityIndexFuture, or FXFuture instrument
fairdelivery	Compute fair delivery price of underlying asset for BondFuture, CommodityFuture, EquityIndexFuture, or FXFuture instrument

Examples

Price CommodityFuture Instrument Using ratecurve and Future Pricer

This example shows the workflow to price a CommodityFuture instrument when you use a ratecurve object and a Future pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2022,3,1);
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])];
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
ZeroCurve = ratecurve("zero",Settle,ZeroDates,ZeroRates,Compounding=2);

Create CommodityFuture Instrument Object

Use fininstrument to create a CommodityFuture instrument object.

CommodityFut = fininstrument("CommodityFuture",Maturity=datetime(2022,9,1),QuotedPrice=68,StorageCost=25,Name="commodityfuture_instrument")

CommodityFut = 
  CommodityFuture with properties:

                         Maturity: 01-Sep-2022
                      QuotedPrice: 68
                      StorageCost: 25
                           Income: 0
               PercentStorageCost: 0
    PercentStorageCostCompounding: -1
          PercentStorageCostBasis: 0
                 ConvenienceYield: 0
      ConvenienceYieldCompounding: -1
            ConvenienceYieldBasis: 0
                             Name: "commodityfuture_instrument"

Create Future Pricer Object

Use finpricer to create a Future pricer object and use the ratecurve object with the DiscountCurve name-value argument.

outPricer = finpricer("Future",DiscountCurve=ZeroCurve,SpotPrice=66)

outPricer = 
  Future with properties:

    DiscountCurve: [1x1 ratecurve]
        SpotPrice: 66

Price CommodityFuture Instrument

Use price to compute the price and price result for the CommodityFuture instrument.

[Price,outPR] = price(outPricer,CommodityFut)

Price = 
23.1778

outPR = 
  priceresult with properties:

       Results: [1x4 table]
    PricerData: []

outPR.Results

ans=1×4 table
    Price     FairDeliveryPrice    FairFuturePrice    AccruedInterest
    ______    _________________    _______________    _______________

    23.178         91.239              91.239                0       

Price Multiple CommodityFuture Instruments Using ratecurve and Future Pricer

This example shows the workflow to price multiple CommodityFuture instruments when you use a ratecurve object and a Future pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2022,3,1);
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])];
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
ZeroCurve = ratecurve("zero",Settle,ZeroDates,ZeroRates,Compounding=2);

Create CommodityFuture Instrument Object

Use fininstrument to create a CommodityFuture instrument object for three Commodity Future instruments.

CommodityFut = fininstrument("CommodityFuture",Maturity=datetime([2022,9,1 ; 2022,10,1 ; 2022,11,1]),QuotedPrice=[68 ; 70 ; 72],StorageCost=25,PercentStorageCost=.02,PercentStorageCostCompounding=4,Name="commodityfuture_instrument")

CommodityFut=3×1 CommodityFuture array with properties:
    Maturity
    QuotedPrice
    StorageCost
    Income
    PercentStorageCost
    PercentStorageCostCompounding
    PercentStorageCostBasis
    ConvenienceYield
    ConvenienceYieldCompounding
    ConvenienceYieldBasis
    Name

Create Future Pricer Object

Use finpricer to create a Future pricer object and use the ratecurve object with the DiscountCurve name-value argument.

outPricer = finpricer("Future",DiscountCurve=ZeroCurve,SpotPrice=66)

outPricer = 
  Future with properties:

    DiscountCurve: [1x1 ratecurve]
        SpotPrice: 66

Price CommodityFuture Instruments

Use price to compute the prices and price results for the CommodityFuture instruments.

[Price,outPR] = price(outPricer,CommodityFut)

Price = 3×1

   24.0976
   22.2855
   20.4822

outPR=1×3 priceresult array with properties:
    Results
    PricerData

outPR.Results

ans=1×4 table
    Price     FairDeliveryPrice    FairFuturePrice    AccruedInterest
    ______    _________________    _______________    _______________

    24.098         92.161              92.161                0       

ans=1×4 table
    Price     FairDeliveryPrice    FairFuturePrice    AccruedInterest
    ______    _________________    _______________    _______________

    22.286         92.354              92.354                0       

ans=1×4 table
    Price     FairDeliveryPrice    FairFuturePrice    AccruedInterest
    ______    _________________    _______________    _______________

    20.482         92.555              92.555                0       

More About

Commodity Future

A commodity future contract is an agreement to buy or sell a predetermined amount of a commodity at a specific price on a specific date in the future.

In the commodity futures market, the underlying commodity has a standardized size and quality in the contract specification (for example, 1000 barrels of light sweet crude oil for WTI Crude Oil futures). During the life of the contract, the underlying commodity may have unit storage cost or unit income that occurs at specific times. It may also have percentage storage cost or convenience yield that is proportional to the price of the commodity.

$$\begin{array}{l}{F}_0=(S_0+U-I)\exp (r+w-y)T\\ FairDeliveryPrice=F_0\end{array}$$

• F₀ — Fair future price of commodity

• S₀ — Spot price of commodity

• U — Present value of storage cost for the life of the contract

• I — Present value of interest income for the life of the contract

• r — Continuously compounded zero rate

• w — Continuously compounded annualized percent storage cost

• y — Continuously compounded annualized convenience yield

• T — Time to maturity of contract

There are two workflows:

• The first workflow is to compute the discounted present value of the futures contract using cashsettle assuming it is held until maturity like a forward contract.

  $$f=(F_0-K)\exp (-rT)Size=(F_0-K)\times DiscountFactor\times Size$$

  • F₀ — Fair future price

  • K — Contractual price

  • r — Continuously compounded zero rate

  • T — Time to maturity of contract

• Since futures contracts are settled on every trading day, the second workflow is to use fairdelivery to compute the current fair delivery price of the futures contract to support marking to market.

  $$MarkToMarket=(ChangeinFuturePrice\text{)}\times \text{(}ContractSize\text{)}$$

Version History

Introduced in R2022a

R2022b: Serial date numbers not recommended

Although CommodityFuture supports serial date numbers, datetime values are recommended instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

To convert serial date numbers or text to datetime values, use the datetime function. For example:

t = datetime(738427.656845093,"ConvertFrom","datenum");
y = year(t)

y =

        2021

There are no plans to remove support for serial date number inputs.