Main Content

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

Description

example

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.

example

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

expand all

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

expand all

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.

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

Data Types: double

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

Data Types: object

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

expand all

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

Data Types: double

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

expand all

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

Data Types: datetime

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

Data Types: double

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

Data Types: object

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

Data Types: double

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

Data Types: double

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

Data Types: string

Object Functions

cashsettleCompute cash settlement for BondFuture, CommodityFuture, EquityIndexFuture, or FXFuture instrument
fairdeliveryCompute fair delivery price of underlying asset for BondFuture, CommodityFuture, EquityIndexFuture, or FXFuture instrument

Examples

collapse all

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       

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

expand all

Version History

Introduced in R2022a

expand all