cashflows

Compute cash flow for FixedBond, FloatBond, Swap, FRA, STIRFuture, OISFuture, OvernightIndexedSwap, or Deposit instrument

Since R2020a

Syntax

CF = cashflows(InstrumentObject,Settle)

Description

CF = cashflows(InstrumentObject,Settle) computes cash flow for a Deposit, FRA, Swap, STIRFuture, OISFuture, FixedBond, OvernightIndexedSwap, or FloatBond instrument object.

Examples

Calculate Cash Flow for FRA Instrument

This example shows the workflow to price a FRA (forward rate agreement) instrument and then use cashflows to determine the cash flow for the FRA instrument.

Create FRA Instrument Object

Use fininstrument to create a FRA instrument object.

FRAObj = fininstrument("FRA",'StartDate',datetime(2020,9,15),'Maturity',datetime(2022,9,15),'Rate',0.175)

FRAObj = 
  FRA with properties:

                     Rate: 0.1750
                    Basis: 2
                StartDate: 15-Sep-2020
                 Maturity: 15-Sep-2022
                Principal: 100
    BusinessDayConvention: "actual"
                 Holidays: NaT
                     Name: ""

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018,9,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;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

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

Create Discount Pricer Object

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

outPricer = finpricer("Discount", 'DiscountCurve',myRC)

outPricer = 
  Discount with properties:

    DiscountCurve: [1x1 ratecurve]

Price FRA Instrument

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

[Price, outPR] = price(outPricer, FRAObj,["all"])

Price = 
34.1757

outPR = 
  priceresult with properties:

       Results: [1x2 table]
    PricerData: []

outPR.Results

ans=1×2 table
    Price      DV01  
    ______    _______

    34.176    0.01368

Use cashflows for the FRA instrument with a Settle date of 15-Dec-2021. The specified Settle date must be before the instrument Maturity date.

CF = cashflows(FRAObj,datetime(2021,12,15))

CF= 1×1timetable
       Time         CFA  
    ___________    ______

    15-Sep-2022    35.486

Calculate Cash Flow for OIS Future Instrument

This example shows the workflow to price an OISFuture instrument and then use cashflows to calculate the cashflow for the OISFuture instrument.

Create ratecurve Object

Create a ratecurve object using ratecurve for the underlying interest-rate curve for the STIRFuture instrument.

Settle = datetime(2019,9,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;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

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

Create OISFuture Instrument Object

Use fininstrument to create an OISFuture instrument object.

OISFuture = fininstrument("OISFuture",'Maturity',datetime(2022,12,15),'QuotedPrice',99.5,'StartDate',datetime(2022,9,15),'Notional',90,'ProjectionCurve',myRC,'Name',"ois_future_instrument")

OISFuture = 
  OISFuture with properties:

              QuotedPrice: 99.5000
                   Method: "compound"
                    Basis: 2
                StartDate: 15-Sep-2022
                 Maturity: 15-Dec-2022
                 Notional: 90
    BusinessDayConvention: "actual"
                 Holidays: NaT
          ProjectionCurve: [1x1 ratecurve]
         HistoricalFixing: [0x0 timetable]
                     Name: "ois_future_instrument"

Create Discount Pricer Object

Use finpricer to create a Discount pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

outPricer = finpricer("Discount",'DiscountCurve',myRC)

outPricer = 
  Discount with properties:

    DiscountCurve: [1x1 ratecurve]

Price OISFuture Instrument

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

[Price, outPR] = price(outPricer,OISFuture,["all"])

Price = 
2.6543

outPR = 
  priceresult with properties:

       Results: [1x2 table]
    PricerData: []

outPR.Results

ans=1×2 table
    Price        DV01   
    ______    __________

    2.6543    -0.0013589

Use cashflows to calculate the cash flow for the OISFuture instrument with a Settle date of 15-Sep-2022. The specified Settle date must be before the instrument Maturity date.

CF = cashflows(OISFuture,datetime(2022,9,15))

CF= 1×1timetable
       Time         CFA  
    ___________    ______

    15-Dec-2022    2.7225

Calculate Cash Flow for Multiple FRA Instruments

This example shows the workflow to price multiple FRA (forward rate agreement) instruments and then use cashflows to determine the cash flow for each of the FRA instruments.

Create FRA Instrument Object

Use fininstrument to create a FRA instrument object for three FRA instruments.

FRAObj = fininstrument("FRA",'StartDate',datetime([2020,9,15 ; 2020,10,15 ; 2020,11,15]),'Maturity',datetime([2022,9,15 ; 2022,10,15 ; 2022,11,15]),'Rate',0.175)

FRAObj=3×1 FRA array with properties:
    Rate
    Basis
    StartDate
    Maturity
    Principal
    BusinessDayConvention
    Holidays
    Name

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018,9,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;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

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

Create Discount Pricer Object

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

outPricer = finpricer("Discount", 'DiscountCurve',myRC)

outPricer = 
  Discount with properties:

    DiscountCurve: [1x1 ratecurve]

Price FRA Instruments

Use price to compute the prices and sensitivities for the three FRA instrument.

[Price, outPR] = price(outPricer, FRAObj,["all"])

Price = 3×1

   34.1757
   34.1207
   34.0627

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

outPR.Results

ans=1×2 table
    Price      DV01  
    ______    _______

    34.176    0.01368

ans=1×2 table
    Price       DV01  
    ______    ________

    34.121    0.013938

ans=1×2 table
    Price       DV01  
    ______    ________

    34.063    0.014204

Use cashflows for the three FRA instruments with a Settle date of April 15, 2022. The specified Settle date must be before the instrument Maturity date.

CF = cashflows(FRAObj(1),datetime(2022,4,15))

CF= 1×1timetable
       Time         CFA  
    ___________    ______

    15-Sep-2022    35.486

CF = cashflows(FRAObj(2),datetime(2022,4,15))

CF= 1×1timetable
       Time         CFA  
    ___________    ______

    15-Oct-2022    35.486

CF = cashflows(FRAObj(3),datetime(2022,4,15))

CF= 1×1timetable
       Time         CFA  
    ___________    ______

    15-Nov-2022    35.486

Calculate Cash Flow for FixedBond Instrument

This example shows the workflow to price a FixedBond instrument and then use cashflows to calculate the cash flow for the FixedBond instrument.

Create FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object.

FixB = fininstrument("FixedBond",'Maturity',datetime(2022,9,15),'CouponRate',0.05,'Period',4,'Basis',7,'Principal',1000,'BusinessDayConvention',"follow",'Name',"fixed_bond_instrument")

FixB = 
  FixedBond with properties:

                  CouponRate: 0.0500
                      Period: 4
                       Basis: 7
                EndMonthRule: 1
                   Principal: 1000
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "follow"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 15-Sep-2022
                        Name: "fixed_bond_instrument"

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018,9,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;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

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

Create Discount Pricer Object

Use finpricer to create a Discount pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

outPricer = finpricer("Discount",'DiscountCurve',myRC)

outPricer = 
  Discount with properties:

    DiscountCurve: [1x1 ratecurve]

Price FixedBond Instrument

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

[Price, outPR] = price(outPricer, FixB,["all"])

Price = 
1.1600e+03

outPR = 
  priceresult with properties:

       Results: [1x2 table]
    PricerData: []

outPR.Results

ans=1×2 table
    Price     DV01  
    _____    _______

    1160     0.42712

Use cashflows to calculate the cash flow for the FixedBond instrument for any specified Settle date before the instrument Maturity date.

CF = cashflows(FixB,datetime(2021,9,15))

CF=5×1 timetable
       Time         Var1 
    ___________    ______

    15-Sep-2021         0
    15-Dec-2021      12.5
    15-Mar-2022      12.5
    15-Jun-2022      12.5
    15-Sep-2022    1012.5

Input Arguments

InstrumentObject — Instrument object

Deposit object | FixedBond object | FloatBond object | Swap object | STIRFuture object | OISFuture object | OvernightIndexedSwap object | FRA object

Instrument object, specified using a previously created instrument object for one of the following: Deposit, FixedBond, FloatBond, Swap, STIRFuture, OISFuture, OvernightIndexedSwap, or FRA.

Note

If the InstrumentObject is a vector of instruments, you must use cashflows 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 Deposit, FixedBond, FloatBond, Swap, STIRFuture, OISFuture,OvernightIndexedSwap, or FRA instrument.

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

Output Arguments

CF — Cash flow

timetable

Cash flow, returned as a timetable.

Version History

Introduced in R2020a

R2022b: Serial date numbers not recommended

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