Main Content

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:

  1. Use fininstrument to create a CMSNote instrument object for one or more CMS Note instruments.

  2. Use finmodel to specify a CMSConvexityHull model object for the CMSNote instrument object.

  3. 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

Description

example

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.

Input Arguments

expand all

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

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.

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 over CMS rate, specified as Spread and a scalar decimal.

Data Types: double

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

Data Types: double

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

Data Types: double

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

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

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

Data Types: double

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

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 amount or principal value schedule, specified as Principal and a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

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

Data Types: double

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

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

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 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)

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

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

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 date, returned as a scalar datetime value or an NINST-by-1 vector of datetime values.

Data Types: datetime

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 over CMS rate, specified as Spread and a scalar decimal.

Data Types: double

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

Data Types: double

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

Data Types: double

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

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

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

Data Types: double

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

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

Data Types: double

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

Data Types: double

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

Data Types: double

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

Data Types: double

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

Data Types: logical

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

Data Types: string

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

Data Types: datetime

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

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

Data Types: datetime

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

Data Types: string

Object Functions

cmsCashflowsCompute cash flows for CMS or CMSNote instrument

Examples

collapse all

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 

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

Version History

Introduced in R2023a