BondFuture

BondFuture instrument object

Since R2022a

Description

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

1. Use fininstrument to create a BondFuture instrument object for one or more Bond Future instruments.

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

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

4. Use cashsettle to compute the cash settlement for the BondFuture instrument and fairdelivery to compute the fair delivery price for the underlying asset for the BondFuture 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 BondFuture instrument, see Choose Instruments, Models, and Pricers.

Creation

Syntax

BondFutureObj = fininstrument(InstrumentType,Maturity=maturity_value,QuotedPrice=quoted_price,Bond=underlying_bond,ConversionFactor=conversion_factor)

BondFutureObj = fininstrument(___,Name=Value)

Description

BondFutureObj = fininstrument(InstrumentType,Maturity=maturity_value,QuotedPrice=quoted_price,Bond=underlying_bond,ConversionFactor=conversion_factor) creates a BondFuture object for one or more Bond Future instruments by specifying InstrumentType and sets the properties for the required name-value pair arguments Maturity, QuotedPrice, Bond, and ConversionFactor.

The BondFuture instrument supports bond futures such as Treasury bond futures, Eurobond futures, Japanese Government Bond (JGB) futures. For more information, see Bond Futures

You can use bond futures for interest-rate 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.

BondFutureObj = fininstrument(___,Name=Value) sets optional properties using additional name-value arguments in addition to the required arguments in the previous syntax. For example, BondFutureObj = fininstrument("BondFuture",Maturity=datetime(2022,9,1),QuotedPrice=86,Bond=myFixedBond,ConversionFactor=1.43,Name="bondfuture_instrument") creates a BondFuture instrument. You can specify multiple name-value arguments.

Input Arguments

InstrumentType — Instrument type

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

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

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: BondFutureObj = fininstrument("BondFuture",Maturity=datetime(2022,9,1),QuotedPrice=86,SpotPrice=125,Bond=myFixedBond,ConversionFactor=1.43,Name="bondfuture_instrument")

Required BondFuture Name-Value Arguments

Maturity — BondFuture maturity date

datetime array | string array | date character vector

BondFuture 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, BondFuture 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 — BondFuture quoted price

scalar numeric | numeric vector

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

Data Types: double

Bond — Underlying FixedBond instrument

FixedBond object | vector of FixedBond objects

Underlying FixedBond instrument, specified as a scalar FixedBond object or an NINST-by-1 vector of FixedBond objects.

Data Types: object

ConversionFactor — Conversion factor for underlying Bond

scalar numeric | numeric vector

Conversion factor for underlying Bond, specified as a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

Optional BondFuture Name-Value Arguments

Notional — Notional value

100000 (default) | scalar numeric | numeric vector

Notional value, specified as a scalar numeric or an NINST-by-1 vector.

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, character vector, or an NINST-by-1 cell array of character vectors, or a string array.

Data Types: char | cell | string

Properties

Maturity — BondFuture maturity date

scalar datetime | vector of datetimes

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

Data Types: datetime

QuotedPrice — BondFuture quoted price

scalar numeric | numeric vector

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

Data Types: double

Bond — Underlying FixedBond instrument

FixedBond object

Underlying FixedBond instrument, returned as a scalar FixedBond object or an NINST-by-1 vector of FixedBond objects.

Data Types: object

ConversionFactor — Conversion factor for underlying Bond

scalar numeric

Conversion factor for underlying Bond, returned as a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

Notional — Notional value

100000 (default) | scalar numeric | numeric vector

Notional value, returned as a scalar numeric or an NINST-by-1 vector.

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 BondFuture Instrument Using ratecurve and Future Pricer

This example shows the workflow to price a BondFuture 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 Underlying FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object.

FixB = fininstrument("FixedBond",Maturity=datetime(2032,9,1),CouponRate=0.05,Name="fixed_bond_instrument")

FixB = 
  FixedBond with properties:

                  CouponRate: 0.0500
                      Period: 2
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 01-Sep-2032
                        Name: "fixed_bond_instrument"

Create BondFuture Instrument Object

Use fininstrument to create a BondFuture instrument object.

BondFut = fininstrument("BondFuture",Maturity=datetime(2022,9,1),QuotedPrice=86,Bond=FixB,ConversionFactor=1.43,Name="bondfuture_instrument")

BondFut = 
  BondFuture with properties:

            Maturity: 01-Sep-2022
         QuotedPrice: 86
                Bond: [1x1 fininstrument.FixedBond]
    ConversionFactor: 1.4300
            Notional: 100000
                Name: "bondfuture_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=125)

outPricer = 
  Future with properties:

    DiscountCurve: [1x1 ratecurve]
        SpotPrice: 125

Price BondFuture Instrument

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

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

Price = 
-151.9270

outPR = 
  priceresult with properties:

       Results: [1x4 table]
    PricerData: []

outPR.Results

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

    -151.93       1.2283e+05            85.893                0       

Price Multiple BondFuture Instruments Using ratecurve and Future Pricer

This example shows the workflow to price multiple BondFuture 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 Underlying FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object.

FixB = fininstrument("FixedBond",Maturity=datetime(2032,9,1),CouponRate=0.05,Name="fixed_bond_instrument")

FixB = 
  FixedBond with properties:

                  CouponRate: 0.0500
                      Period: 2
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 01-Sep-2032
                        Name: "fixed_bond_instrument"

Create BondFuture Instrument Object

Use fininstrument to create a BondFuture instrument object for three Bond Future instruments.

BondFut = fininstrument("BondFuture",Maturity=datetime([2022,9,1 ; 2022,10,1 ; 2022,11,1]),QuotedPrice=[86 ; 88 ; 90],Bond=FixB,ConversionFactor=1.43,Name="bondfuture_instrument")

BondFut=3×1 BondFuture array with properties:
    Maturity
    QuotedPrice
    Bond
    ConversionFactor
    Notional
    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=125)

outPricer = 
  Future with properties:

    DiscountCurve: [1x1 ratecurve]
        SpotPrice: 125

Price BondFuture Instruments

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

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

Price = 3×1
103 ×

   -0.1519
   -3.3603
   -6.5765

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

outPR.Results

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

    -151.93       1.2283e+05            85.893                0       

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

    -3360.3       1.2288e+05            85.643             0.41436    

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

    -6576.5       1.2294e+05            85.385             0.84254    

More About

Bond Futures

A bond future is a financial derivatives that obligates the contract holder to purchase or sell a bond on a specified date at a predetermined price.

$$B_0=(S_0-I)/DiscountFactor$$

• B₀ — Full fair future cash price for $100 face value of deliverable bond

• S₀ — Full spot cash price for $100 face value of deliverable bond

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

• DiscountFactor — Discount factor to maturity of contract

$$\begin{array}{l}FairFuturePrice=F_0=(B_0-AccruedInterest)/ConversionFactor\\ FairDeliveryPrice=B_0/100\times Size\end{array}$$

• F₀ — Clean fair future cash price for $100 face value

• B₀ — Full fair future cash price for $100 face value of the deliverable bond

• ConversionFactor — Conversion factor of the deliverable bond

• AccruedInterest — Accrued interest at delivery

• Size — Futures contract size

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=(B_0-K)\times DiscountFactor/100\times Size$$

  • B₀ — Full fair future cash price for $100 face value of the delivery bond

  • K₀ — Full contractual delivery bond price for $100 face value of the deliverable bond

  • DiscountFactor — Discount factor to the maturity of the contract

  • Size — Futures contract size

• Since futures contracts are settled on every trading day, the second workflow is to use fairdelivery to compute the current fair delivery bond price B₀ of the futures contract, fair future price F₀, and the accrued interest to support marking to market.

  $$\begin{array}{l}DelieveryBondPrice(B_0)=FairFuturePrice(F_0)\times ConversionFactor+AccruedInterest\\ MarkToMarket=(ChangeinFuturePrice\text{)}\times \text{(}ContractSize\text{)}\end{array}$$

  • B₀ — Full fair future cash price for $100 face value of the deliverable bond

  • F₀ — Clean fair future price for $100 face value

  • ConversionFactor — Conversion factor of the deliverable bond

  • AccruedInterest — Accrued interest at delivery for $100 fave value

Version History

Introduced in R2022a

R2022b: Serial date numbers not recommended

Although BondFuture 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.