cmsCashflows

Compute cash flows for CMS or CMSNote instrument

Since R2023a

Syntax

outCF = cmsCashflows(InstrumentObject,Settle,CMSRateTimeTable)

Description

outCF = cmsCashflows(InstrumentObject,Settle,CMSRateTimeTable) computes the cash flows for the underlying asset of a CMS or CMSNote instrument object.

Examples

Compute Cash Flows for CMS Instrument

This example shows how to compute the cash flows for a CMS instrument.

Create CMS Instrument Object

Use fininstrument to create a CMS instrument object.

Settle = datetime(2022,9,15);
Maturity = datetime(2028,9,15);
CMSLegPeriod = 2;
FixedLegPeriod = 2;

CMSInstrument = fininstrument("CMS",Maturity=datetime(2028,9,15),CMSReferenceTenor=10,Reset=[CMSLegPeriod FixedLegPeriod],LegRate=[0 0.01],LegType=["cms" "fixed"],Name="CMS instrument")

CMSInstrument = 
  CMS with properties:

           CMSReferenceReset: 2
           CMSReferenceTenor: 10
                     LegRate: [0 0.0100]
                     LegType: ["cms"    "fixed"]
                       Reset: [2 2]
                       Basis: [0 0]
                    Notional: 100
          LatestFloatingRate: [NaN NaN]
               LatestCMSRate: NaN
                 ResetOffset: [0 0]
    DaycountAdjustedCashFlow: [0 0]
             ProjectionCurve: [0x0 ratecurve]
       BusinessDayConvention: ["actual"    "actual"]
                    Holidays: NaT
                EndMonthRule: [1 1]
                   StartDate: NaT
                    Maturity: 15-Sep-2028
                        Name: "CMS instrument"

Compute Cash Flows

Create the CMSRateTimeTable using cfdates with Settle and Matrurity values.

Time = [Settle;cfdates(Settle,Maturity,CMSLegPeriod)'];
CMSRates = [0.0216 0.0216 0.0231 0.0246 0.0262 0.0279 ...
    0.0295 0.0312 0.0327 0.0342 0.0354 0.0366 0.0377]';
CMSRateTimeTable = timetable(Time,CMSRates)

CMSRateTimeTable=13×1 timetable
       Time        CMSRates
    ___________    ________

    15-Sep-2022     0.0216 
    15-Mar-2023     0.0216 
    15-Sep-2023     0.0231 
    15-Mar-2024     0.0246 
    15-Sep-2024     0.0262 
    15-Mar-2025     0.0279 
    15-Sep-2025     0.0295 
    15-Mar-2026     0.0312 
    15-Sep-2026     0.0327 
    15-Mar-2027     0.0342 
    15-Sep-2027     0.0354 
    15-Mar-2028     0.0366 
    15-Sep-2028     0.0377 

Use cmsCashflows to compute the cash flows for the CMS instrument.

cmsCashflows(CMSInstrument,Settle,CMSRateTimeTable)

ans=13×2 timetable
       Time        Var1_RecCF    Var1_PayCF
    ___________    __________    __________

    15-Sep-2022          0             0   
    15-Mar-2023       1.08          -0.5   
    15-Sep-2023      1.155          -0.5   
    15-Mar-2024       1.23          -0.5   
    15-Sep-2024       1.31          -0.5   
    15-Mar-2025      1.395          -0.5   
    15-Sep-2025      1.475          -0.5   
    15-Mar-2026       1.56          -0.5   
    15-Sep-2026      1.635          -0.5   
    15-Mar-2027       1.71          -0.5   
    15-Sep-2027       1.77          -0.5   
    15-Mar-2028       1.83          -0.5   
    15-Sep-2028      1.885          -0.5   

Compute Cash Flows for CMSNote Instrument

This example shows how to compute the cash flows for a CMSNote instrument.

Create CMSNote Instrument Object

Use fininstrument to create a CMSNote instrument object.

Settle = datetime(2022,9,15);
Maturity = datetime(2028,9,15);
Period = 2;
CMSNoteInstrument = fininstrument("CMSNote",Maturity=Maturity,CMSReferenceTenor=10,Period=Period,Name="CMSNote instrument")

CMSNoteInstrument = 
  CMSNote with properties:

           CMSReferenceReset: 2
           CMSReferenceTenor: 10
                      Spread: 0
         InitialCouponPeriod: 0
           InitialCouponRate: 0
                      Period: 2
                       Basis: 0
                   Principal: 100
          LatestFloatingRate: NaN
               LatestCMSRate: NaN
                 ResetOffset: 0
    DaycountAdjustedCashFlow: 0
             ProjectionCurve: [0x0 ratecurve]
       BusinessDayConvention: "actual"
                    Holidays: NaT
                EndMonthRule: 1
                   StartDate: NaT
                    Maturity: 15-Sep-2028
                        Name: "CMSNote instrument"

Compute Cash Flows

Create the CMSRateTimeTable using cfdates with Settle and Matrurity values.

Time = [Settle;cfdates(Settle,Maturity,Period)'];
CMSRates = [0.0216 0.0216 0.0231 0.0246 0.0262 0.0279 ...
    0.0295 0.0312 0.0327 0.0342 0.0354 0.0366 0.0377]';
CMSRateTimeTable = timetable(Time,CMSRates)

CMSRateTimeTable=13×1 timetable
       Time        CMSRates
    ___________    ________

    15-Sep-2022     0.0216 
    15-Mar-2023     0.0216 
    15-Sep-2023     0.0231 
    15-Mar-2024     0.0246 
    15-Sep-2024     0.0262 
    15-Mar-2025     0.0279 
    15-Sep-2025     0.0295 
    15-Mar-2026     0.0312 
    15-Sep-2026     0.0327 
    15-Mar-2027     0.0342 
    15-Sep-2027     0.0354 
    15-Mar-2028     0.0366 
    15-Sep-2028     0.0377 

Use cmsCashflows to compute the cash flows for the CMSNote instrument.

cmsCashflows(CMSNoteInstrument,Settle,CMSRateTimeTable)

ans=13×1 timetable
       Time         Var1 
    ___________    ______

    15-Sep-2022         0
    15-Mar-2023      1.08
    15-Sep-2023     1.155
    15-Mar-2024      1.23
    15-Sep-2024      1.31
    15-Mar-2025     1.395
    15-Sep-2025     1.475
    15-Mar-2026      1.56
    15-Sep-2026     1.635
    15-Mar-2027      1.71
    15-Sep-2027      1.77
    15-Mar-2028      1.83
    15-Sep-2028    101.89

Input Arguments

InstrumentObject — Instrument object

CMS object | CMSNote object

Instrument object, specified using a previously created instrument object for one of the following: CMS or CMSNote.

Note

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

Data Types: object

Settle — Settlement date

datetime scalar | string scalar | date character vector

Settlement date, specified as a scalar datetime value, string, or date character vector. The Settle date must be before the Maturity date for the CMS or CMSNote instrument.

If you use a date character vector or string, the format must be recognizable by datetime because the Settle property is stored as a datetime data type.

CMSRateTimeTable — CMS rate timetable

timetable with two columns

CMS rate timetable, specified as CMSRateTimeTable and a timetable with the following columns:

• Time — NumCashFlows-by-1 cash flow dates in datetime format in the first column of the timetable

• CMSRates — NumCashFlows-by-1 CMS rates in decimals

Data Types: timetable

Output Arguments

outCF — Cash flow for underlying asset

timetable

Cash flow for underlying asset (InstrumentObject), returned as a timetable.

Note

To compute outCF for float legs for a CMS instrument, you must specify a ProjectionCurve name-value argument when creating the CMS instrument object.

Version History

Introduced in R2023a