cashflows

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

collapse all in page

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.

example

Examples

collapse all

Open Live Script

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: [10×1 datetime]
                Rates: [10×1 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: [1×1 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: [1×2 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
Open Live Script

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: [10×1 datetime]
                Rates: [10×1 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: [1×1 ratecurve]
         HistoricalFixing: [0×0 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: [1×1 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: [1×2 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
Open Live Script

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: [10×1 datetime]
                Rates: [10×1 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: [1×1 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
Open Live Script

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: [10×1 datetime]
                Rates: [10×1 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: [1×1 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: [1×2 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

collapse all

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

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

collapse all

Cash flow, returned as a timetable.

Version History

Introduced in R2020a

expand all

See Also

| | |

Topics