inflationCashflows

Compute cash flows for InflationBond instrument

Since R2021a

Syntax

outCF = inflationCashflows(inpInstrumentObject,Settle,inpInflationCurve)

Description

outCF = inflationCashflows(inpInstrumentObject,Settle,inpInflationCurve) computes cash flows for an InflationBond instrument object.

Examples

Price InflationBond Instrument Using inflationcurve and Inflation Pricer and Compute Cash Flows

This example shows the workflow to price an InflationBond instrument when you use an inflationcurve object and an Inflation pricing method. The cash flows for the InflationBond instrument are computed using inflationCashflows.

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2021,1,15);
Type = "zero";
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)

ZeroCurve = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10×1 datetime]
                Rates: [10×1 double]
               Settle: 15-Jan-2021
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create inflationcurve Object

Create an inflationcurve object using inflationcurve.

BaseDate = datetime(2020,10,1);
InflationTimes = [0 calyears([1 2 3 4 5 7 10 20 30])]';
InflationIndexValues = [100 102 103.5 105 106.8 108.2 111.3 120.1 130.4 150.2]';
InflationDates = BaseDate + InflationTimes;
myInflationCurve = inflationcurve(InflationDates,InflationIndexValues)

myInflationCurve = 
  inflationcurve with properties:

                    Basis: 0
                    Dates: [10×1 datetime]
     InflationIndexValues: [10×1 double]
    ForwardInflationRates: [9×1 double]
              Seasonality: [12×1 double]

Create InflationBond Instrument Object

Use fininstrument to create an InflationBond instrument object.

IssueDate = datetime(2021,1,1);
Maturity = datetime(2026,1,1);
CouponRate = 0.02;

InflationBond = fininstrument("InflationBond",'IssueDate',IssueDate,'Maturity',Maturity,'CouponRate',CouponRate,'Name',"inflation_bond_instrument")

InflationBond = 
  InflationBond with properties:

                  CouponRate: 0.0200
                      Period: 2
                       Basis: 0
                   Principal: 100
    DaycountAdjustedCashFlow: 0
                         Lag: 3
                  IssueIndex: NaN
       BusinessDayConvention: "actual"
                    Holidays: NaT
                EndMonthRule: 1
                   IssueDate: 01-Jan-2021
             FirstCouponDate: NaT
              LastCouponDate: NaT
                    Maturity: 01-Jan-2026
                        Name: "inflation_bond_instrument"

Create Inflation Pricer Object

Use finpricer to create an Inflation pricer object and use the ratecurve object with the 'DiscountCurve' name-value pair argument and the inflationcurve object with the 'InflationCurve' name-value pair argument.

outPricer = finpricer("Inflation",'DiscountCurve',ZeroCurve,'InflationCurve',myInflationCurve)

outPricer = 
  Inflation with properties:

     DiscountCurve: [1×1 ratecurve]
    InflationCurve: [1×1 inflationcurve]

Price InflationBond Instrument

Use price to compute the price and sensitivities for the InflationBond instrument.

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

Price = 
112.1856

outPR = 
  priceresult with properties:

       Results: [1×1 table]
    PricerData: []

outPR.Results

ans=table
    Price 
    ______

    112.19

Compute Cash Flows for InflationBond Instrument

Use inflationCashflows to compute the cash flows for the InflationBond instrument.

outCF = inflationCashflows(InflationBond,datetime(2021,1,15),myInflationCurve)

outCF=11×1 timetable
       Time        InflationCFAmounts
    ___________    __________________

    15-Jan-2021        -0.077407     
    01-Jul-2021           1.0099     
    01-Jan-2022             1.02     
    01-Jul-2022           1.0275     
    01-Jan-2023            1.035     
    01-Jul-2023           1.0425     
    01-Jan-2024             1.05     
    01-Jul-2024            1.059     
    01-Jan-2025            1.068     
    01-Jul-2025            1.075     
    01-Jan-2026           109.28     

Price Multiple InflationBond Instruments Using inflationcurve and Inflation Pricer and Compute Cash Flows

This example shows the workflow to price multiple InflationBond instruments when you use an inflationcurve object and an Inflation pricing method. The cash flows for the InflationBond instruments are computed using inflationCashflows.

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2021,1,15);
Type = "zero";
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)

ZeroCurve = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10×1 datetime]
                Rates: [10×1 double]
               Settle: 15-Jan-2021
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create inflationcurve Object

Create an inflationcurve object using inflationcurve.

BaseDate = datetime(2019,8,1);
InflationTimes = [0 calyears([1 2 3 4 5 7 10 20 30])]';
InflationIndexValues = [100 102 103.5 105 106.8 108.2 111.3 120.1 130.4 150.2]';
InflationDates = BaseDate + InflationTimes;
myInflationCurve = inflationcurve(InflationDates,InflationIndexValues)

myInflationCurve = 
  inflationcurve with properties:

                    Basis: 0
                    Dates: [10×1 datetime]
     InflationIndexValues: [10×1 double]
    ForwardInflationRates: [9×1 double]
              Seasonality: [12×1 double]

Create InflationBond Instrument Object

Use fininstrument to create an InflationBond instrument object for three Inflation Bond instruments.

IssueDate = datetime([2020,1,1 ; 2019,12,1 ; 2019,11,1]);
Maturity = datetime([2026,1,1 ; 2026,2,1 ; 2026,3,1]);
CouponRate = 0.02;

InflationBond = fininstrument("InflationBond",'IssueDate',IssueDate,'Maturity',Maturity,'CouponRate',CouponRate,'Name',"inflation_bond_instrument")

InflationBond=3×1 InflationBond array with properties:
    CouponRate
    Period
    Basis
    Principal
    DaycountAdjustedCashFlow
    Lag
    IssueIndex
    BusinessDayConvention
    Holidays
    EndMonthRule
    IssueDate
    FirstCouponDate
    LastCouponDate
    Maturity
    Name

Create Inflation Pricer Object

Use finpricer to create an Inflation pricer object and use the ratecurve object with the 'DiscountCurve' name-value pair argument and the inflationcurve object with the 'InflationCurve' name-value pair argument.

outPricer = finpricer("Inflation",'DiscountCurve',ZeroCurve,'InflationCurve',myInflationCurve)

outPricer = 
  Inflation with properties:

     DiscountCurve: [1×1 ratecurve]
    InflationCurve: [1×1 inflationcurve]

Price InflationBond Instruments

Use price to compute the prices and sensitivities for the InflationBond instruments.

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

Price = 3×1

  113.6829
  113.9533
  114.2316

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

outPR.Results

ans=table
    Price 
    ______

    113.68

ans=table
    Price 
    ______

    113.95

ans=table
    Price 
    ______

    114.23

Compute Cash Flows for InflationBond Instruments

Use inflationCashflows to compute the cash flows for the three InflationBond instruments.

outCF = inflationCashflows(InflationBond(1),datetime(2021,1,15),myInflationCurve)

outCF=11×1 timetable
       Time        InflationCFAmounts
    ___________    __________________

    15-Jan-2021        -0.078871     
    01-Jul-2021           1.0266     
    01-Jan-2022           1.0341     
    01-Jul-2022           1.0415     
    01-Jan-2023           1.0495     
    01-Jul-2023           1.0585     
    01-Jan-2024           1.0668     
    01-Jul-2024           1.0738     
    01-Jan-2025            1.081     
    01-Jul-2025           1.0886     
    01-Jan-2026           110.73     

outCF = inflationCashflows(InflationBond(2),datetime(2021,1,15),myInflationCurve)

outCF=12×1 timetable
       Time        InflationCFAmounts
    ___________    __________________

    15-Jan-2021         -0.92699     
    01-Feb-2021            1.022     
    01-Aug-2021           1.0295     
    01-Feb-2022            1.037     
    01-Aug-2022           1.0444     
    01-Feb-2023           1.0527     
    01-Aug-2023           1.0617     
    01-Feb-2024           1.0697     
    01-Aug-2024           1.0767     
    01-Feb-2025            1.084     
    01-Aug-2025           1.0917     
    01-Feb-2026           111.05     

outCF = inflationCashflows(InflationBond(3),datetime(2021,1,15),myInflationCurve)

outCF=12×1 timetable
       Time        InflationCFAmounts
    ___________    __________________

    15-Jan-2021         -0.76871     
    01-Mar-2021            1.025     
    01-Sep-2021           1.0325     
    01-Mar-2022             1.04     
    01-Sep-2022           1.0475     
    01-Mar-2023            1.056     
    01-Sep-2023            1.065     
    01-Mar-2024           1.0726     
    01-Sep-2024           1.0797     
    01-Mar-2025           1.0871     
    01-Sep-2025           1.0948     
    01-Mar-2026           111.36     

Input Arguments

inpInstrumentObject — Instrument object

InflationBond object

Instrument object, specified using a previously created instrument object for an InflationBond.

Note

If the inpInstrumentObject is a vector of instruments, you must use inflationCashflows separately with each instrument.

Data Types: object

Settle — Settlement date for instrument cash flow

datetime scalar | string scalar | date character vector

Settlement date for instrument cash flow, specified as a scalar datetime, string, or date character vector.

Note

The Settle date you specify must be before the Maturity date for the InflationBond instrument.

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

inpInflationCurve — Inflation curve

inflationcurve object

Inflation curve, specified using a previously created inflation curve object using inflationcurve.

Data Types: object

Output Arguments

outCF — Output cash flow

timetable

Output cash flow, returned as a timetable.

Version History

Introduced in R2021a

R2022b: Serial date numbers not recommended

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