CMSNote

CMSNote instrument object

Since R2023a

Description

Create and price a CMSNote (constant maturity swap note) instrument object for one or more CMS Note instruments using this workflow:

Use fininstrument to create a CMSNote instrument object for one or more CMS Note instruments.
Use finmodel to specify a CMSConvexityHull model object for the CMSNote instrument object.
Use finpricer to specify a CMSConvexityHull pricing method for the CMSNote instrument object.

For more information on this workflow, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.

Creation

Syntax

CMSNoteInstrument = fininstrument(InstrumentType,Maturity=maturity_date,CMSReferenceTenor=reference_tenor_value)

CMSNoteInstrument = fininstrument(___,Name=Value)

Description

CMSNoteInstrument = fininstrument(InstrumentType,Maturity=maturity_date,CMSReferenceTenor=reference_tenor_value) creates a CMSNote object for one or more CMS Note instruments by specifying InstrumentType and sets the properties for the required name-value pair arguments Maturity and CMSReferenceTenor.

The CMSNote instrument supports CMS-linked notes (bonds). For more information on a CMSNote instrument, see More About.

example

CMSNoteInstrument = fininstrument(___,Name=Value) sets optional properties using name-value arguments in addition to the required arguments in the previous syntax. For example, CMSNoteInstrument = fininstrument("CMSNote",Maturity=datetime(2028,9,15),CMSReferenceTenor=10) creates a CMSNote with a maturity of September 15, 2028. You can specify multiple name-value arguments.

example

Input Arguments

expand all

`InstrumentType` — Instrument type
string with value `"CMSNote"` | string array with values of `"CMSNote"` | character vector with value `'CMSNote'` | cell array of character vectors with values of `'CMSNote'`

Instrument type, specified as a string with the value of "CMSNote", a character vector with the value of 'CMSNote', an NINST-by-1 string array with values of "CMSNote", or an NINST-by-1 cell array of character vectors with values of 'CMSNote'.

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: CMSNoteInstrument = fininstrument("CMSNote",Maturity=datetime(2028,9,15),CMSReferenceTenor=10)

Required CMSNote Name-Value Arguments

expand all

`Maturity` — CMS maturity date
datetime array | string array | date character vector

CMS maturity date, specified as Maturity and a scalar or an NINST-by-1 vector using a datetime array, string array, or date character vectors.

If you use date character vectors or strings, the format must be recognizable by datetime because the Maturity property is stored as a datetime data type.

`CMSReferenceTenor` — Tenor, in years, for underlying reference swap of CMS leg
scalar or vector of positive values

Tenor, in years, for the underlying reference swap of the CMS leg, specified as CMSReferenceTenor and a scalar or an NINST-by-1 vector of positive values.

Data Types: double

Optional CMSNote Name-Value Pair Arguments

expand all

`Spread` — Spread over CMS rate
`0` (default) | scalar decimal

Spread over CMS rate, specified as Spread and a scalar decimal.

Data Types: double

`Period` — Frequency of actual payments per year
`2` (default) | scalar numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | numeric vector with values of `1`, `2`, `3`, `4`, `6`, or `12`

Frequency of actual payments per year, specified as Period and a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

`InitialCouponPeriod` — Number of initial periods with fixed interest
`0` (default) | scalar numeric | numeric vector

Number of initial periods with fixed interest, specified as InitialCoupnPeriod and a scalar or NINST-by-1 vector of numeric values.

Data Types: double

`InitialCouponRate` — Initial annual fixed coupon rate applicable to `InitialCouponPeriod`
`0` (default) | scalar positive decimal | positive vector of decimals

Initial annual fixed coupon rate, in decimals, applicable to InitialCouponPeriod, specified as InitialCouponRate and a scalar or NINST-by-1 vector of positive numeric values.

Data Types: double

`CMSReferenceReset` — Frequency of payments, per year, for underlying reference swap
`2` (default) | scalar numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | numeric vector with values of `1`, `2`, `3`, `4`, `6`, or `12`

Frequency of payments, per year, for the underlying reference swap, specified as CMSReferenceReset and a scalar or NINST-by-1 vector with supported numeric values.

Data Types: double

`ResetOffset` — Number of lagged days in rate setting
`0` (default) | scalar | vector

Number of lagged days in the rate setting, specified as ResetOffset and a scalar or an NINST-by-1 vector.

Data Types: double

`ProjectionCurve` — Rate curve for projecting floating cash flows
`ratecurve.empty` object (default) | scalar `ratecurve` object | vector of `ratecurve` objects

Rate curve for projecting floating cash flows, specified as ProjectionCurve and a scalar ratecurve object or an NINST-by-1 vector of ratecurve objects. You must create a ratecurve object using ratecurve.

Data Types: object

`Basis` — Day count basis
`0` (actual/actual) (default) | integer from `0` to `13`

Day count basis, specified as Basis and a scalar or NINST-by-1 vector.

0 — actual/actual
1 — 30/360 (SIA)
2 — actual/360
3 — actual/365
4 — 30/360 (PSA)
5 — 30/360 (ISDA)
6 — 30/360 (European)
7 — actual/365 (Japanese)
8 — actual/actual (ICMA)
9 — actual/360 (ICMA)
10 — actual/365 (ICMA)
11 — 30/360E (ICMA)
12 — actual/365 (ISDA)
13 — BUS/252

For more information, see Basis.

Data Types: double

`Principal` — Principal amount
`100` (default) | scalar numeric | numeric vector

Principal amount or principal value schedule, specified as Principal and a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

`LatestFloatingRate` — Latest floating rate in decimals
if not specified, then `ratecurve` must contain this information (default) | scalar numeric | vector

Latest floating rate in decimals, specified as LatestFloatingRate and a scalar numeric or an NINST-by-1 vector.

Data Types: double

`LatestCMSRate` — Latest CMS rate in decimals
if not specified, then `ratecurve` or `LatestFloatingRate` must contain this information (default) | scalar numeric | vector

Latest CMS rate in decimals, specified as LatestCMSRate and a scalar numeric or an NINST-by-1 numeric vector.

Setting the LatestCMSRate overrides LatestFloatingRate.

Data Types: double

`DaycountAdjustedCashFlow` — Flag to adjust cash flows based on day count convention
`false` (default) | scalar logical value of `true` or `false` | vector of logical values of `true` or `false`

Flag to adjust cash flows based on day count convention (Basis), specified as DaycountAdjustedCashFlow and a scalar or an NINST-by-1 vector.

Data Types: logical

`BusinessDayConvention` — Business day conventions for cash flow dates
`"actual"` (default) | scalar string | string array | scalar character vector | cell array of character vectors

Business day conventions for cash flow dates, specified as BusinessDayConvention and scalar string or character vector or NINST-by-1 cell array or string array. The selection for business day convention determines how nonbusiness days are treated. Nonbusiness days are defined as weekends plus any other date that businesses are not open (for example, statutory holidays). Values are:

"actual" — Nonbusiness days are effectively ignored. Cash flows that fall on nonbusiness days are assumed to be distributed on the actual date.
"follow" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the following business day.
"modifiedfollow" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the following business day. However, if the following business day is in a different month, the previous business day is adopted instead.
"previous" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the previous business day.
"modifiedprevious" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the previous business day. However, if the previous business day is in a different month, the following business day is adopted instead.

Data Types: char | cell | string

`Holidays` — Holidays used in computing business days
`NaT` (default) | datetime array | date character vector | string array

Holidays used in computing business days, specified as Holidays and an NINST-by-1 vector using a datetime array, cell array of date character vectors, or date string array. For example:

H = holidays(datetime(2022,9,15),datetime(2029,9,15));

CMSNoteInstrument = fininstrument("CMSNote",Maturity=datetime(2028,9,15),CMSReferenceTenor=1,Holidays=H)

`EndMonthRule` — End-of-month rule flag for generating dates when `Maturity` is end-of-month date for month with 30 or fewer days
`true` (in effect) (default) | logical with value of `true` or `false` | vector of logicals with values of `true` or `false`

End-of-month rule flag for generating dates when Maturity is an end-of-month date for a month with 30 or fewer days, specified as EndMonthRule and a logical value of true or false using a scalar or NINST-by-1 vector.

If you set EndMonthRule to false, the software ignores the rule, meaning that a payment date is always the same numerical day of the month.
If you set EndMonthRule to true, the software sets the rule on, meaning that a payment date is always the last actual day of the month.

Data Types: logical

`StartDate` — Forward starting date of payments
`Settle` date from `ratecurve` (default) | datetime array | string | string array | date character vector | cell array of date character vectors

Forward starting date of payments, specified as StartDate and a scalar or an NINST-by-1 vector using a datetime array, string array, or cell array of date character vectors.

If you use date character vectors or strings, the format must be recognizable by datetime because the StartDate property is stored as a datetime data type.

Data Types: datetime | char | string | cell

`Name` — User-defined name for instrument
`""` (default) | string | character vector | cell array of character vectors | string array

User-defined name for the instrument, specified as Name and a scalar string, character vector, an NINST-by-1 cell array of character vectors, or a string array.

Data Types: char | cell | string

Properties

expand all

`Maturity` — Maturity date
scalar datetime value | vector of datetime values

Maturity date, returned as a scalar datetime value or an NINST-by-1 vector of datetime values.

Data Types: datetime

`CMSReferenceTenor` — Tenor, in years, for underlying reference swap of CMS leg
vector of positive values

Tenor, in years, for the underlying reference swap of the CMS leg, returned as an NINST-by-1 vector of positive values.

Data Types: double

`Spread` — Spread over CMS rate
`0` (default) | scalar decimal

Spread over CMS rate, specified as Spread and a scalar decimal.

Data Types: double

`Period` — Frequency of actual payments per year
`2` (default) | scalar numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | numeric vector with values of `1`, `2`, `3`, `4`, `6`, or `12`

Frequency of actual payments per year, returned as a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

`InitialCouponPeriod` — Number of initial periods with fixed interest
`0` (default) | scalar numeric | numeric vector

Number of initial periods with fixed interest, returned as a scalar or NINST-by-1 vector of numeric values.

Data Types: double

`InitialCouponRate` — Initial annual fixed coupon rate applicable to `InitialCouponPeriod`
`0` (default) | scalar positive decimal | positive vector of decimals

Initial annual fixed coupon rate, in decimals, applicable to InitialCouponPeriod, returned as a scalar or NINST-by-1 vector of positive numeric values.

Data Types: double

`CMSReferenceReset` — Frequency of payments per year for underlying reference swap
`2` (default) | scalar numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | numeric vector with values of `1`, `2`, `3`, `4`, `6`, or `12`

Frequency of payments per year for the underlying reference swap, returned as a scalar or a NINST-by-1 vector with supported numeric values.

Data Types: double

`ResetOffset` — Number of lagged days in rate setting
`[0 0]` (default) | scalar numeric | numeric vector

Number of lagged days in the rate setting, returned as a scalar or NINST-by-1 vector.

Data Types: double

`ProjectionCurve` — Rate curve for projecting floating cash flows
`ratecurve.empty` object (default) | scalar `ratecurve` object | vector of `ratecurve` objects

Rate curve for projecting floating cash flows, returned as a scalar ratecurve object or an NINST-by-1 vector of ratecurve objects.

Data Types: object

`Basis` — Day count basis
`0` (actual/actual) (default) | integer from `0` to `13`

Day count basis, returned as a scalar or an NINST-by-1 vector.

Data Types: double

`Principal` — Principal amount
`100` (default) | scalar numeric | numeric vector

Principal amount or principal value schedule, returned as a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

`LatestFloatingRate` — Latest floating rate in decimals
if not specified, then `ratecurve` must contain this information (default) | scalar numeric | vector

Latest floating rate in decimals, returned as a scalar numeric or an NINST-by-1 vector.

Data Types: double

`LatestCMSRate` — Latest CMS rate in decimals
if not specified, then `ratecurve` or `LatestFloatingRate` must contain this information (default) | scalar numeric | vector

Latest CMS rate in decimals, returned as a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

`DaycountAdjustedCashFlow` — Flag to adjust cash flows based on day count convention
`false` (default) | scalar logical value of `true` or `false` | vector of logical values of `true` or `false`

Flag to adjust cash flows based on day count convention (Basis), returned as a scalar or an NINST-by-1 vector.

Data Types: logical

`BusinessDayConvention` — Business day conventions for cash flow dates
`"actual"` (default) | scalar string | string array

Business day conventions for cash flow dates, returned as a scalar string or an NINST-by-1 string array.

Data Types: string

`Holidays` — Holidays used in computing business days
`NaT` (default) | datetime values

Holidays used in computing business days, returned as an NINST-by-1 vector of datetime values.

Data Types: datetime

`EndMonthRule` — End-of-month rule flag for generating dates when `Maturity` is end-of-month date for month with 30 or fewer days
`true` (in effect) (default) | logical with value of `true` or `false` | vector of logicals with values of `true` or `false`

End-of-month rule flag for generating dates when Maturity is an end-of-month date for a month with 30 or fewer days, returned as a scalar or an NINST-by-1 vector.

Data Types: logical

`StartDate` — Forward starting date of payments
`Settle` date from `ratecurve` object (default) | scalar datetime value | vector of datetime values

Forward starting date of payments, returned as a scalar datetime value or an NINST-by-1 vector of datetime values.

Data Types: datetime

`Name` — User-defined name for instrument
`""` (default) | string | string array

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

Data Types: string

Object Functions

cmsCashflows Compute cash flows for CMS or CMSNote instrument

Examples

collapse all

Price `CMSNote` Instrument Using `CMSConvexityHull` Model and `CMSConvexityHull` Pricer

Open Live Script

This example shows the workflow to price a CMSNote instrument when you use a CMSConvexityHull model and a CMSConvexityHull pricing method.

Create ratecurve Object

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

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

ZeroCurve = 
  ratecurve with properties:

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

Create CMSNote Instrument Object

Use fininstrument to create a CMSNote instrument object.

CMSNoteInstrument = fininstrument("CMSNote",Maturity=datetime(2028,9,15),CMSReferenceTenor=10,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"

Create CMSConvexityHull Model Object

Use finmodel to create a CMSConvexityHull model object.

SwapStartDates = datetime(2022,3,15) + calmonths(0:6:13*6)';

FwdSwapVolatility = [37.5;38.7;39.3;39.5;39.4;39.3;39.2;...
    39;38.8;38.5;38.3;38;37.8;37.7]./100;

CMSConvexityHullModel = finmodel("CMSConvexityHull",CMSConvexityData=timetable(SwapStartDates,FwdSwapVolatility))

CMSConvexityHullModel = 
  CMSConvexityHull with properties:

    CMSConvexityData: [14x3 timetable]

CMSConvexityHullModel.CMSConvexityData

ans=14×3 timetable
    SwapStartDates    FwdSwapVolatility    FwdVolatility    FwdSwapFwdCorrelation
    ______________    _________________    _____________    _____________________

    15-Mar-2022             0.375                0                    0          
    15-Sep-2022             0.387                0                    0          
    15-Mar-2023             0.393                0                    0          
    15-Sep-2023             0.395                0                    0          
    15-Mar-2024             0.394                0                    0          
    15-Sep-2024             0.393                0                    0          
    15-Mar-2025             0.392                0                    0          
    15-Sep-2025              0.39                0                    0          
    15-Mar-2026             0.388                0                    0          
    15-Sep-2026             0.385                0                    0          
    15-Mar-2027             0.383                0                    0          
    15-Sep-2027              0.38                0                    0          
    15-Mar-2028             0.378                0                    0          
    15-Sep-2028             0.377                0                    0

Create CMSConvexityHull Pricer Object

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

CMSConvexityHullPricer = finpricer("analytic",Model=CMSConvexityHullModel,DiscountCurve=ZeroCurve)

CMSConvexityHullPricer = 
  CMSConvexityHull with properties:

            Model: [1x1 finmodel.CMSConvexityHull]
    DiscountCurve: [1x1 ratecurve]

Price CMSNote Instrument

Use price to compute the price for the CMSNote instrument.

[CMSPrice, outPR] = price(CMSConvexityHullPricer,CMSNoteInstrument)

CMSPrice = 
109.1087

outPR = 
  priceresult with properties:

       Results: [1x1 table]
    PricerData: [13x7 timetable]

outPR.PricerData

ans=13×7 timetable
       Time        SwapStartDates    ForwardSwapRates    ConvexityAdjustments    TimingAdjustments    CMSRates    Accruals    SwapEndDates
    ___________    ______________    ________________    ____________________    _________________    ________    ________    ____________

    15-Sep-2022     15-Sep-2022          0.021605                      0                 0            0.021605        0       15-Sep-2032 
    15-Mar-2023     15-Sep-2022          0.021605                      0                 0            0.021605      0.5       15-Sep-2032 
    15-Sep-2023     15-Mar-2023           0.02286             0.00019992                 0             0.02306      0.5       15-Mar-2033 
    15-Mar-2024     15-Sep-2023          0.024135             0.00045273                 0            0.024588      0.5       15-Sep-2033 
    15-Sep-2024     15-Mar-2024          0.025431             0.00074919                 0             0.02618      0.5       15-Mar-2034 
    15-Mar-2025     15-Sep-2024          0.026751              0.0010992                 0             0.02785      0.5       15-Sep-2034 
    15-Sep-2025     15-Mar-2025           0.02801              0.0014918                 0            0.029502      0.5       15-Mar-2035 
    15-Mar-2026     15-Sep-2025          0.029262              0.0019316                 0            0.031194      0.5       15-Sep-2035 
    15-Sep-2026     15-Mar-2026          0.030318              0.0023865                 0            0.032705      0.5       15-Mar-2036 
    15-Mar-2027     15-Sep-2026            0.0313              0.0028593                 0             0.03416      0.5       15-Sep-2036 
    15-Sep-2027     15-Mar-2027          0.032102               0.003331                 0            0.035433      0.5       15-Mar-2037 
    15-Mar-2028     15-Sep-2027          0.032798              0.0038007                 0            0.036599      0.5       15-Sep-2037 
    15-Sep-2028     15-Mar-2028          0.033406              0.0042947                 0              0.0377      0.5       15-Mar-2038

Price Multiple `CMSNote` Instruments Using `CMSConvexityHull` Model and `CMSConvexityHull` Pricer

Open Live Script

This example shows the workflow to price multiple CMSNote instruments when you use a CMSConvexityHull model and a CMSConvexityHull pricing method.

Create ratecurve Object

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

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

ZeroCurve = 
  ratecurve with properties:

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

Create CMSNote Instrument Object

Use fininstrument to create a CMS instrument object for three CMSNote instruments.

CMSNoteInstrument = fininstrument("CMSNote",Maturity=datetime([2026,9,15 ; 2027,9,15 ; 2028,9,15]),CMSReferenceTenor=10)

CMSNoteInstrument=3×1 CMSNote array with properties:
    CMSReferenceReset
    CMSReferenceTenor
    Spread
    InitialCouponPeriod
    InitialCouponRate
    Period
    Basis
    Principal
    LatestFloatingRate
    LatestCMSRate
    ResetOffset
    DaycountAdjustedCashFlow
    ProjectionCurve
    BusinessDayConvention
    Holidays
    EndMonthRule
    StartDate
    Maturity
    Name

Create CMSConvexityHull Model Object

Use finmodel to create a CMSConvexityHull model object.

SwapStartDates = datetime(2022,3,15) + calmonths(0:6:13*6)';

FwdSwapVolatility = [37.5;38.7;39.3;39.5;39.4;39.3;39.2;...
    39;38.8;38.5;38.3;38;37.8;37.7]./100;

CMSConvexityHullModel = finmodel("CMSConvexityHull",CMSConvexityData=timetable(SwapStartDates,FwdSwapVolatility))

CMSConvexityHullModel = 
  CMSConvexityHull with properties:

    CMSConvexityData: [14x3 timetable]

CMSConvexityHullModel.CMSConvexityData

ans=14×3 timetable
    SwapStartDates    FwdSwapVolatility    FwdVolatility    FwdSwapFwdCorrelation
    ______________    _________________    _____________    _____________________

    15-Mar-2022             0.375                0                    0          
    15-Sep-2022             0.387                0                    0          
    15-Mar-2023             0.393                0                    0          
    15-Sep-2023             0.395                0                    0          
    15-Mar-2024             0.394                0                    0          
    15-Sep-2024             0.393                0                    0          
    15-Mar-2025             0.392                0                    0          
    15-Sep-2025              0.39                0                    0          
    15-Mar-2026             0.388                0                    0          
    15-Sep-2026             0.385                0                    0          
    15-Mar-2027             0.383                0                    0          
    15-Sep-2027              0.38                0                    0          
    15-Mar-2028             0.378                0                    0          
    15-Sep-2028             0.377                0                    0

Create CMSConvexityHull Pricer Object

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

CMSConvexityHullPricer = finpricer("analytic",Model=CMSConvexityHullModel,DiscountCurve=ZeroCurve)

CMSConvexityHullPricer = 
  CMSConvexityHull with properties:

            Model: [1x1 finmodel.CMSConvexityHull]
    DiscountCurve: [1x1 ratecurve]

Price CMSNote Instruments

Use price to compute the price for the three CMSNote instruments.

[CMSPrice, outPR] = price(CMSConvexityHullPricer,CMSNoteInstrument)

CMSPrice = 3×1

  106.9455
  108.1561
  109.1087

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

outPR.PricerData

ans=9×7 timetable
       Time        SwapStartDates    ForwardSwapRates    ConvexityAdjustments    TimingAdjustments    CMSRates    Accruals    SwapEndDates
    ___________    ______________    ________________    ____________________    _________________    ________    ________    ____________

    15-Sep-2022     15-Sep-2022          0.021605                      0                 0            0.021605        0       15-Sep-2032 
    15-Mar-2023     15-Sep-2022          0.021605                      0                 0            0.021605      0.5       15-Sep-2032 
    15-Sep-2023     15-Mar-2023           0.02286             0.00019992                 0             0.02306      0.5       15-Mar-2033 
    15-Mar-2024     15-Sep-2023          0.024135             0.00045273                 0            0.024588      0.5       15-Sep-2033 
    15-Sep-2024     15-Mar-2024          0.025431             0.00074919                 0             0.02618      0.5       15-Mar-2034 
    15-Mar-2025     15-Sep-2024          0.026751              0.0010992                 0             0.02785      0.5       15-Sep-2034 
    15-Sep-2025     15-Mar-2025           0.02801              0.0014918                 0            0.029502      0.5       15-Mar-2035 
    15-Mar-2026     15-Sep-2025          0.029262              0.0019316                 0            0.031194      0.5       15-Sep-2035 
    15-Sep-2026     15-Mar-2026          0.030318              0.0023865                 0            0.032705      0.5       15-Mar-2036

ans=11×7 timetable
       Time        SwapStartDates    ForwardSwapRates    ConvexityAdjustments    TimingAdjustments    CMSRates    Accruals    SwapEndDates
    ___________    ______________    ________________    ____________________    _________________    ________    ________    ____________

    15-Sep-2022     15-Sep-2022          0.021605                      0                 0            0.021605        0       15-Sep-2032 
    15-Mar-2023     15-Sep-2022          0.021605                      0                 0            0.021605      0.5       15-Sep-2032 
    15-Sep-2023     15-Mar-2023           0.02286             0.00019992                 0             0.02306      0.5       15-Mar-2033 
    15-Mar-2024     15-Sep-2023          0.024135             0.00045273                 0            0.024588      0.5       15-Sep-2033 
    15-Sep-2024     15-Mar-2024          0.025431             0.00074919                 0             0.02618      0.5       15-Mar-2034 
    15-Mar-2025     15-Sep-2024          0.026751              0.0010992                 0             0.02785      0.5       15-Sep-2034 
    15-Sep-2025     15-Mar-2025           0.02801              0.0014918                 0            0.029502      0.5       15-Mar-2035 
    15-Mar-2026     15-Sep-2025          0.029262              0.0019316                 0            0.031194      0.5       15-Sep-2035 
    15-Sep-2026     15-Mar-2026          0.030318              0.0023865                 0            0.032705      0.5       15-Mar-2036 
    15-Mar-2027     15-Sep-2026            0.0313              0.0028593                 0             0.03416      0.5       15-Sep-2036 
    15-Sep-2027     15-Mar-2027          0.032102               0.003331                 0            0.035433      0.5       15-Mar-2037

ans=13×7 timetable
       Time        SwapStartDates    ForwardSwapRates    ConvexityAdjustments    TimingAdjustments    CMSRates    Accruals    SwapEndDates
    ___________    ______________    ________________    ____________________    _________________    ________    ________    ____________

    15-Sep-2022     15-Sep-2022          0.021605                      0                 0            0.021605        0       15-Sep-2032 
    15-Mar-2023     15-Sep-2022          0.021605                      0                 0            0.021605      0.5       15-Sep-2032 
    15-Sep-2023     15-Mar-2023           0.02286             0.00019992                 0             0.02306      0.5       15-Mar-2033 
    15-Mar-2024     15-Sep-2023          0.024135             0.00045273                 0            0.024588      0.5       15-Sep-2033 
    15-Sep-2024     15-Mar-2024          0.025431             0.00074919                 0             0.02618      0.5       15-Mar-2034 
    15-Mar-2025     15-Sep-2024          0.026751              0.0010992                 0             0.02785      0.5       15-Sep-2034 
    15-Sep-2025     15-Mar-2025           0.02801              0.0014918                 0            0.029502      0.5       15-Mar-2035 
    15-Mar-2026     15-Sep-2025          0.029262              0.0019316                 0            0.031194      0.5       15-Sep-2035 
    15-Sep-2026     15-Mar-2026          0.030318              0.0023865                 0            0.032705      0.5       15-Mar-2036 
    15-Mar-2027     15-Sep-2026            0.0313              0.0028593                 0             0.03416      0.5       15-Sep-2036 
    15-Sep-2027     15-Mar-2027          0.032102               0.003331                 0            0.035433      0.5       15-Mar-2037 
    15-Mar-2028     15-Sep-2027          0.032798              0.0038007                 0            0.036599      0.5       15-Sep-2037 
    15-Sep-2028     15-Mar-2028          0.033406              0.0042947                 0              0.0377      0.5       15-Mar-2038

More About

expand all

CMS-Linked Note

A CMS-linked note is a debt instrument issued at a specific face value, where the periodic coupon payments can change depending on the CMS rates.

In the simplest type of CMS-linked notes, the coupon payments are made based on a specific CMS rate (for example, a 10-year CMS rate) that is updated every period. The tenor of the CMS reference swaps can be different from the maturity of the CMS-linked note itself (for example, 10-year swap tenors versus 6-year CMS-linked note maturity). Also, the reset frequency of the CMS reference swaps can be different from the period of the CMS-linked note itself. Some CMS-linked notes can have additional features that affect the cash flows, such as an initial coupon period during which the coupon rate is fixed.

Version History

Introduced in R2023a

CMSNote

Description

Creation

Syntax

Description

Input Arguments

InstrumentType — Instrument type string with value "CMSNote" | string array with values of "CMSNote" | character vector with value 'CMSNote' | cell array of character vectors with values of 'CMSNote'

Maturity — CMS maturity date datetime array | string array | date character vector

CMSReferenceTenor — Tenor, in years, for underlying reference swap of CMS leg scalar or vector of positive values

Spread — Spread over CMS rate 0 (default) | scalar decimal

Period — Frequency of actual payments per year 2 (default) | scalar numeric value of 1, 2, 3, 4, 6, or 12 | numeric vector with values of 1, 2, 3, 4, 6, or 12

InitialCouponPeriod — Number of initial periods with fixed interest 0 (default) | scalar numeric | numeric vector

InitialCouponRate — Initial annual fixed coupon rate applicable to InitialCouponPeriod 0 (default) | scalar positive decimal | positive vector of decimals

CMSReferenceReset — Frequency of payments, per year, for underlying reference swap 2 (default) | scalar numeric value of 1, 2, 3, 4, 6, or 12 | numeric vector with values of 1, 2, 3, 4, 6, or 12

ResetOffset — Number of lagged days in rate setting 0 (default) | scalar | vector

ProjectionCurve — Rate curve for projecting floating cash flows ratecurve.empty object (default) | scalar ratecurve object | vector of ratecurve objects

Basis — Day count basis 0 (actual/actual) (default) | integer from 0 to 13

Principal — Principal amount 100 (default) | scalar numeric | numeric vector

LatestFloatingRate — Latest floating rate in decimals if not specified, then ratecurve must contain this information (default) | scalar numeric | vector

LatestCMSRate — Latest CMS rate in decimals if not specified, then ratecurve or LatestFloatingRate must contain this information (default) | scalar numeric | vector

DaycountAdjustedCashFlow — Flag to adjust cash flows based on day count convention false (default) | scalar logical value of true or false | vector of logical values of true or false

BusinessDayConvention — Business day conventions for cash flow dates "actual" (default) | scalar string | string array | scalar character vector | cell array of character vectors

Holidays — Holidays used in computing business days NaT (default) | datetime array | date character vector | string array

EndMonthRule — End-of-month rule flag for generating dates when Maturity is end-of-month date for month with 30 or fewer days true (in effect) (default) | logical with value of true or false | vector of logicals with values of true or false

StartDate — Forward starting date of payments Settle date from ratecurve (default) | datetime array | string | string array | date character vector | cell array of date character vectors

Name — User-defined name for instrument "" (default) | string | character vector | cell array of character vectors | string array

Properties

Maturity — Maturity date scalar datetime value | vector of datetime values

CMSReferenceTenor — Tenor, in years, for underlying reference swap of CMS leg vector of positive values

Spread — Spread over CMS rate 0 (default) | scalar decimal

Period — Frequency of actual payments per year 2 (default) | scalar numeric value of 1, 2, 3, 4, 6, or 12 | numeric vector with values of 1, 2, 3, 4, 6, or 12

InitialCouponPeriod — Number of initial periods with fixed interest 0 (default) | scalar numeric | numeric vector

InitialCouponRate — Initial annual fixed coupon rate applicable to InitialCouponPeriod 0 (default) | scalar positive decimal | positive vector of decimals

CMSReferenceReset — Frequency of payments per year for underlying reference swap 2 (default) | scalar numeric value of 1, 2, 3, 4, 6, or 12 | numeric vector with values of 1, 2, 3, 4, 6, or 12

ResetOffset — Number of lagged days in rate setting [0 0] (default) | scalar numeric | numeric vector

ProjectionCurve — Rate curve for projecting floating cash flows ratecurve.empty object (default) | scalar ratecurve object | vector of ratecurve objects

Basis — Day count basis 0 (actual/actual) (default) | integer from 0 to 13

Principal — Principal amount 100 (default) | scalar numeric | numeric vector

LatestFloatingRate — Latest floating rate in decimals if not specified, then ratecurve must contain this information (default) | scalar numeric | vector

LatestCMSRate — Latest CMS rate in decimals if not specified, then ratecurve or LatestFloatingRate must contain this information (default) | scalar numeric | vector

DaycountAdjustedCashFlow — Flag to adjust cash flows based on day count convention false (default) | scalar logical value of true or false | vector of logical values of true or false

BusinessDayConvention — Business day conventions for cash flow dates "actual" (default) | scalar string | string array

Holidays — Holidays used in computing business days NaT (default) | datetime values

EndMonthRule — End-of-month rule flag for generating dates when Maturity is end-of-month date for month with 30 or fewer days true (in effect) (default) | logical with value of true or false | vector of logicals with values of true or false

StartDate — Forward starting date of payments Settle date from ratecurve object (default) | scalar datetime value | vector of datetime values

Name — User-defined name for instrument "" (default) | string | string array

Object Functions

Examples

Price CMSNote Instrument Using CMSConvexityHull Model and CMSConvexityHull Pricer

Price Multiple CMSNote Instruments Using CMSConvexityHull Model and CMSConvexityHull Pricer

More About

CMS-Linked Note

Version History

See Also

Functions

Topics

`InstrumentType` — Instrument type
string with value `"CMSNote"` | string array with values of `"CMSNote"` | character vector with value `'CMSNote'` | cell array of character vectors with values of `'CMSNote'`

`Maturity` — CMS maturity date
datetime array | string array | date character vector

`CMSReferenceTenor` — Tenor, in years, for underlying reference swap of CMS leg
scalar or vector of positive values

`Spread` — Spread over CMS rate
`0` (default) | scalar decimal

`Period` — Frequency of actual payments per year
`2` (default) | scalar numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | numeric vector with values of `1`, `2`, `3`, `4`, `6`, or `12`

`InitialCouponPeriod` — Number of initial periods with fixed interest
`0` (default) | scalar numeric | numeric vector

`InitialCouponRate` — Initial annual fixed coupon rate applicable to `InitialCouponPeriod`
`0` (default) | scalar positive decimal | positive vector of decimals

`CMSReferenceReset` — Frequency of payments, per year, for underlying reference swap
`2` (default) | scalar numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | numeric vector with values of `1`, `2`, `3`, `4`, `6`, or `12`

`ResetOffset` — Number of lagged days in rate setting
`0` (default) | scalar | vector

`ProjectionCurve` — Rate curve for projecting floating cash flows
`ratecurve.empty` object (default) | scalar `ratecurve` object | vector of `ratecurve` objects

`Basis` — Day count basis
`0` (actual/actual) (default) | integer from `0` to `13`

`Principal` — Principal amount
`100` (default) | scalar numeric | numeric vector

`LatestFloatingRate` — Latest floating rate in decimals
if not specified, then `ratecurve` must contain this information (default) | scalar numeric | vector

`LatestCMSRate` — Latest CMS rate in decimals
if not specified, then `ratecurve` or `LatestFloatingRate` must contain this information (default) | scalar numeric | vector

`DaycountAdjustedCashFlow` — Flag to adjust cash flows based on day count convention
`false` (default) | scalar logical value of `true` or `false` | vector of logical values of `true` or `false`

`BusinessDayConvention` — Business day conventions for cash flow dates
`"actual"` (default) | scalar string | string array | scalar character vector | cell array of character vectors

`Holidays` — Holidays used in computing business days
`NaT` (default) | datetime array | date character vector | string array

`EndMonthRule` — End-of-month rule flag for generating dates when `Maturity` is end-of-month date for month with 30 or fewer days
`true` (in effect) (default) | logical with value of `true` or `false` | vector of logicals with values of `true` or `false`

`StartDate` — Forward starting date of payments
`Settle` date from `ratecurve` (default) | datetime array | string | string array | date character vector | cell array of date character vectors

`Name` — User-defined name for instrument
`""` (default) | string | character vector | cell array of character vectors | string array

`Maturity` — Maturity date
scalar datetime value | vector of datetime values

`CMSReferenceTenor` — Tenor, in years, for underlying reference swap of CMS leg
vector of positive values

`Spread` — Spread over CMS rate
`0` (default) | scalar decimal

`Period` — Frequency of actual payments per year
`2` (default) | scalar numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | numeric vector with values of `1`, `2`, `3`, `4`, `6`, or `12`

`InitialCouponPeriod` — Number of initial periods with fixed interest
`0` (default) | scalar numeric | numeric vector

`InitialCouponRate` — Initial annual fixed coupon rate applicable to `InitialCouponPeriod`
`0` (default) | scalar positive decimal | positive vector of decimals

`CMSReferenceReset` — Frequency of payments per year for underlying reference swap
`2` (default) | scalar numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | numeric vector with values of `1`, `2`, `3`, `4`, `6`, or `12`

`ResetOffset` — Number of lagged days in rate setting
`[0 0]` (default) | scalar numeric | numeric vector

`ProjectionCurve` — Rate curve for projecting floating cash flows
`ratecurve.empty` object (default) | scalar `ratecurve` object | vector of `ratecurve` objects

`Basis` — Day count basis
`0` (actual/actual) (default) | integer from `0` to `13`

`Principal` — Principal amount
`100` (default) | scalar numeric | numeric vector

`LatestFloatingRate` — Latest floating rate in decimals
if not specified, then `ratecurve` must contain this information (default) | scalar numeric | vector

`LatestCMSRate` — Latest CMS rate in decimals
if not specified, then `ratecurve` or `LatestFloatingRate` must contain this information (default) | scalar numeric | vector

`DaycountAdjustedCashFlow` — Flag to adjust cash flows based on day count convention
`false` (default) | scalar logical value of `true` or `false` | vector of logical values of `true` or `false`

`BusinessDayConvention` — Business day conventions for cash flow dates
`"actual"` (default) | scalar string | string array

`Holidays` — Holidays used in computing business days
`NaT` (default) | datetime values

`EndMonthRule` — End-of-month rule flag for generating dates when `Maturity` is end-of-month date for month with 30 or fewer days
`true` (in effect) (default) | logical with value of `true` or `false` | vector of logicals with values of `true` or `false`

`StartDate` — Forward starting date of payments
`Settle` date from `ratecurve` object (default) | scalar datetime value | vector of datetime values

`Name` — User-defined name for instrument
`""` (default) | string | string array

Price `CMSNote` Instrument Using `CMSConvexityHull` Model and `CMSConvexityHull` Pricer

Price Multiple `CMSNote` Instruments Using `CMSConvexityHull` Model and `CMSConvexityHull` Pricer