CMS

CMS instrument object

Since R2023a

Description

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

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

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

Creation

Syntax

CMSInstrument = fininstrument(InstrumentType,Maturity=maturity_date,LegRate=leg_rate,CMSReferenceTenor=reference_tenor)

CMSInstrument = fininstrument(___,Name=Value)

Description

CMSInstrument = fininstrument(InstrumentType,Maturity=maturity_date,LegRate=leg_rate,CMSReferenceTenor=reference_tenor) creates a CMS object for one or more CMS instruments by specifying InstrumentType and sets the properties for the required name-value arguments Maturity, LegRate, and CMSReferenceTenor. For more information on a CMS instrument, see More About.

example

CMSInstrument = fininstrument(___,Name=Value) sets optional properties using name-value arguments in addition to the required arguments in the previous syntax. For example, CMSInstrument = fininstrument("CMS",Maturity=datetime(2028,9,15),CMSReferenceTenor=10,LegRate=[0 0.01],LegType=["cms" "fixed"]) creates a CMS instrument with a maturity of September 15, 2028. You can specify multiple name-value pair arguments.

example

Input Arguments

expand all

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

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

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: CMSInstrument = fininstrument("CMS",Maturity=datetime(2028,9,15),CMSReferenceTenor=10,LegRate=[0 0.01],LegType=["cms" "fixed"])

Required CMS 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.

`LegRate` — Leg rate in decimal values
matrix

Leg rate in decimal values, specified as LegRate and a 1-by-2 or anNINST-by-2 matrix.

The first column represents the receiving leg, while the second column represents the paying leg. The LegRate definition depends on the LegType as follows:

For a "fixed" leg — Specify LegRate as the fixed coupon rate as an annual decimal rate.
For a "float" leg — Specify LegRate as the spread in an annual decimal rate over the reference floating rate.
For a "cms" leg — Specify LegRate as the spread in an annual decimal rate over the reference floating CMS rate.

For example, LegType=["cms" "fixed"] and LegRate = [0 0.01] defines a zero percent spread over the reference CMS rate for the CMS leg and a one percent fixed rate for the fixed leg.

Data Types: double

`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 CMS Name-Value Pair Arguments

expand all

`LegType` — Leg type
`["cms","fixed"]` for each instrument (default) | cell array of character vectors with values `{'cms','fixed'}`, `{'cms','float'}`, `{'fixed','cms'}`, or `{'float','cms'}` | string array with values `["cms","fixed"]`, `["cms","float"]`, `["fixed","cms"]`, or `["float","cms"]`

Leg type, specified as LegType and a cell array of character vectors or a string array with the supported values:

"fixed' — Fixed rate leg
"float" — Floating rate leg
"cms" — Floating CMS rate leg

The LegType defines the interpretation of the values that you enter in LegRate.

Data Types: cell | string

`Reset` — Frequency of actual payments per year
`[2 2]` (default) | numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | vector

Frequency of payments per year, specified Reset and scalar, NINST-by-1 vector, or NINST-by-2 vector if Reset is different for each leg with one of the following values: 1, 2, 3, 4, 6, or 12.

Data Types: double

`CMSReferenceReset` — Frequency of payments per year for underlying reference swap of CMS leg
`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 of the CMS leg, specified as CMSReferenceReset and a scalar or an NINST-by-1 vector with supported numeric values.

Data Types: double

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

Number of lagged days in the rate setting, specified as ResetOffset and a scalar, NINST-by-1 vector, or NINST-by-2 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, an NINST-by-1 vector, or an NINST-by-2 vector of ratecurve objects. You must create this ratecurve object using ratecurve.

Data Types: object

`Basis` — Day count basis representing the basis for each leg
`[0 0]` (actual/actual) (default) | integer from `0` to `13`

Day count basis representing the basis for each leg, specified as Basis and an NINST-by-1 vector (or NINST-by-2 vector if Basis is different for each leg).

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

`Notional` — Notional principal amount
`100` (default) | scalar numeric | numeric vector

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

Data Types: double

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

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

If LatestFloatingRate is different for each leg, then LatestFloatingRate is an NINST-by-2 vector.

Data Types: double

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

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

Setting LatestCMSRate overrides LatestFloatingRate for the CMS leg.

Data Types: double

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

Flag to adjust cash flows based on the day count convention (Basis), specified as DaycountAdjustedCashFlow and a scalar, NINST-by-1 vector, or NINST-by-2 vector if AdjustCashFlowsBasis is different for each leg.

Data Types: logical

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

Business day conventions for the cash flow dates, specified as BusinessDayConvention and a scalar string or character vector, NINST-by-1 cell array or string array, or NINST-by-2 cell array or string array if BusinessDayConvention is different for each leg. The selection for business day convention determines how nonbusiness days are treated. Nonbusiness days are 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 datetimes array, cell array of date character vectors, or date string array. For example:

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

CMSInstrument = fininstrument("CMS", Maturity=datetime(2028,9,15), ...
CMSReferenceTenor=1, LegRate=[0 0.01], 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 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, NINST-by-1 vector, or NINST-by-2 vector if EndMonthRule is different for each leg.

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

`LegRate` — Leg rate
vector

Leg rate, returned as an NINST-by-2 matrix of decimal values.

Data Types: double

`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

`LegType` — Leg type
`["cms","fixed"]` for each instrument (default) | string array with values `["cms","fixed"]`, `["cms","float"]`, `["fixed","cms"]`, or `["float","cms"]`

Leg type, returned as a string array.

Data Types: string

`Reset` — Frequency of actual payments per year
`[2 2]` (default) | numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | vector

Frequency of payments per year, returned as a scalar, NINST-by-1 vector, or NINST-by-2 vector.

Data Types: double

`CMSReferenceReset` — Frequency of payments per year for underlying reference swap of CMS leg
`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 of the CMS leg, returned as a scalar or an 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, NINST-by-1 vector, or NINST-by-2 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 or NINST-by-2 vector of ratecurve objects.

Data Types: object

`Basis` — Day count basis representing basis for each leg
`[0 0]` (actual/actual) (default) | integer from `0` to `13`

Day count basis representing the basis for each leg, returned as an NINST-by-1 vector, or if Basis is different for each leg, an NINST-by-2 vector.

Data Types: double

`Notional` — Notional principal amount
`100` (default) | scalar numeric | numeric vector

Notional 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, for floating legs
if not specified, then `ratecurve` must contain this information (default) | scalar numeric | vector

Latest floating rate, in decimals, for float legs, returned as a scalar numeric, NINST-by-1 vector, or NINST-by-2 numeric vector.

Data Types: double

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

Latest CMS rate, in decimals, for the CMS leg, 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 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, NINST-by-1 vector, or NINST-by-2 vector if DaycountAdjustedCashFlow is different for each leg.

Data Types: logical

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

Business day conventions for cash flow dates, returned as a scalar string, NINST-by-1 string array, or NINST-by-2 string array if BusinessDayConvention is different for each leg.

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 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 an NINST-by-1 vector or an NINST-by-2 vector if EndMonthRule is different for each leg.

Data Types: logical

`StartDate` — Date swap starts
`Settle` date from `ratecurve` object (default) | scalar datetime value | vector of datetime values

Date swap starts, 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 `CMS` Instrument Using `CMSConvexityHull` Model and `CMSConvexityHull` Pricer

Open Live Script

This example shows the workflow to price a CMS 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 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 CMS Instrument Object

Use fininstrument to create a CMS instrument object.

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

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 CMS Instrument

Use price to compute the price for the CMS instrument.

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

CMSPrice = 
11.5623

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 `CMS` Instruments Using `CMSConvexityHull` Model and `CMSConvexityHull` Pricer

Open Live Script

This example shows the workflow to price multiple CMS 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 CMS Instrument Object

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

CMSInstrument = fininstrument("CMS",Maturity=datetime([2026,9,15 ; 2027,9,15 ; 2028,9,15]),CMSReferenceTenor=10,LegRate=[0 0.01],LegType=["cms" "fixed"])

CMSInstrument=3×1 CMS array with properties:
    CMSReferenceReset
    CMSReferenceTenor
    LegRate
    LegType
    Reset
    Basis
    Notional
    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 CMS Instruments

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

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

CMSPrice = 3×1

    6.7046
    9.0543
   11.5623

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

A constant maturity swap (CMS) is a special kind of interest-rate swap, where one of its two legs is a floating "CMS leg" that resets periodically using the par swap rate at a constant tenor (for example, a 10 year swap rate).

Typically, the term CMS rate refers to this floating par swap rate of the CMS leg, where the actual cash flows could also have a fixed spread over the reference CMS rate. The other leg could be fixed or floating just like a regular interest-rate swap. If the other leg is floating, it is based on a reference rate at some tenor (for example, a 6-month LIBOR) and sometimes this floating leg may have a fixed spread over the reference rate.

In the following diagram, the blue arrows indicate the cash flows of the CMS itself and the red arrows indicate the cash flows of the reference interest-rate swaps that determine the CMS rates for the CMS leg. The tenor of the CMS reference swaps can be different from the maturity of the CMS itself (for example, 10-year swap tenors versus 6-year CMS maturity). Also, the reset frequency of the CMS reference swaps can be different from the reset frequency of the CMS leg itself.

Version History

Introduced in R2023a

CMS

Description

Creation

Syntax

Description

Input Arguments

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

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

LegRate — Leg rate in decimal values matrix

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

LegType — Leg type ["cms","fixed"] for each instrument (default) | cell array of character vectors with values {'cms','fixed'}, {'cms','float'}, {'fixed','cms'}, or {'float','cms'} | string array with values ["cms","fixed"], ["cms","float"], ["fixed","cms"], or ["float","cms"]

Reset — Frequency of actual payments per year [2 2] (default) | numeric value of 1, 2, 3, 4, 6, or 12 | vector

CMSReferenceReset — Frequency of payments per year for underlying reference swap of CMS leg 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 | vector

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

Basis — Day count basis representing the basis for each leg [0 0] (actual/actual) (default) | integer from 0 to 13

Notional — Notional principal amount 100 (default) | scalar numeric | numeric vector

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

LatestCMSRate — Latest CMS rate, in decimals, for the CMS leg 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 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" "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 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

LegRate — Leg rate vector

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

LegType — Leg type ["cms","fixed"] for each instrument (default) | string array with values ["cms","fixed"], ["cms","float"], ["fixed","cms"], or ["float","cms"]

Reset — Frequency of actual payments per year [2 2] (default) | numeric value of 1, 2, 3, 4, 6, or 12 | vector

CMSReferenceReset — Frequency of payments per year for underlying reference swap of CMS leg 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 representing basis for each leg [0 0] (actual/actual) (default) | integer from 0 to 13

Notional — Notional principal amount 100 (default) | scalar numeric | numeric vector

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

LatestCMSRate — Latest CMS rate, in decimals, for CMS leg 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 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" "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 true] (in effect) (default) | logical with value of true or false | vector of logicals with values of true or false

StartDate — Date swap starts 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 CMS Instrument Using CMSConvexityHull Model and CMSConvexityHull Pricer

Price Multiple CMS Instruments Using CMSConvexityHull Model and CMSConvexityHull Pricer

More About

CMS

Version History

See Also

Functions

Topics

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

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

`LegRate` — Leg rate in decimal values
matrix

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

`LegType` — Leg type
`["cms","fixed"]` for each instrument (default) | cell array of character vectors with values `{'cms','fixed'}`, `{'cms','float'}`, `{'fixed','cms'}`, or `{'float','cms'}` | string array with values `["cms","fixed"]`, `["cms","float"]`, `["fixed","cms"]`, or `["float","cms"]`

`Reset` — Frequency of actual payments per year
`[2 2]` (default) | numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | vector

`CMSReferenceReset` — Frequency of payments per year for underlying reference swap of CMS leg
`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 | vector

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

`Basis` — Day count basis representing the basis for each leg
`[0 0]` (actual/actual) (default) | integer from `0` to `13`

`Notional` — Notional principal amount
`100` (default) | scalar numeric | numeric vector

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

`LatestCMSRate` — Latest CMS rate, in decimals, for the CMS leg
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 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" "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 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

`LegRate` — Leg rate
vector

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

`LegType` — Leg type
`["cms","fixed"]` for each instrument (default) | string array with values `["cms","fixed"]`, `["cms","float"]`, `["fixed","cms"]`, or `["float","cms"]`

`Reset` — Frequency of actual payments per year
`[2 2]` (default) | numeric value of `1`, `2`, `3`, `4`, `6`, or `12` | vector

`CMSReferenceReset` — Frequency of payments per year for underlying reference swap of CMS leg
`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 representing basis for each leg
`[0 0]` (actual/actual) (default) | integer from `0` to `13`

`Notional` — Notional principal amount
`100` (default) | scalar numeric | numeric vector

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

`LatestCMSRate` — Latest CMS rate, in decimals, for CMS leg
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 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" "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 true]` (in effect) (default) | logical with value of `true` or `false` | vector of logicals with values of `true` or `false`

`StartDate` — Date swap starts
`Settle` date from `ratecurve` object (default) | scalar datetime value | vector of datetime values

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

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

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