CMSConvexityHull

Create CMSConvexityHull pricer object for CMS or CMSNote instrument using CMSConvexityHull model

Since R2023a

Description

Create and price a CMS or CMSNote instrument object with a CMSConvexityHull model and a CMSConvexityHull pricing method using this workflow:

Use fininstrument to create a CMS or CMSNote instrument object.
Use finmodel to specify a CMSConvexityHull model object for the CMS or CMSNote instrument object.
Use finpricer to specify a CMSConvexityHull pricer object for the CMS or CMSNote instrument object.

Note
If you do not specify a ProjectionCurve name-value argument when you create a CMS or CMSNote instrument with the CMSConvexityHull pricer, the ProjectionCurve value defaults to the DiscountCurve value.

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

Creation

Syntax

CMSConvexityHullPricerObj = finpricer(PricerType,Model=cmsconvexityhullmodel,DiscountCurve=ratecurve_obj)

Description

CMSConvexityHullPricerObj = finpricer(PricerType,Model=cmsconvexityhullmodel,DiscountCurve=ratecurve_obj) creates a CMSConvexityHull pricer object by specifying PricerType and the required name-value arguments Model and DiscountCurve to set properties. For example, CMSConvexityHullPricerObj = finpricer("Analytic",Model=CMSConvexityHull,DiscountCurve=ratecurve_obj) creates a CMSConvexityHull pricer object.

example

Input Arguments

expand all

`PricerType` — Pricer type
string with value `"Analytic"` | character vector with value `'Analytic'`

Pricer type, specified as a string with the value of "Analytic" or a character vector with the value of 'Analytic'.

Data Types: char | string

Name-Value Arguments

expand all

Specify required 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: CMSConvexityHullPricer = finpricer("analytic",Model=CMSConvexityHullModel,DiscountCurve=ZeroCurve)

`Model` — Model
`CMSConvexityHull` model object

Model, specified as Model and the name of a previously created CMSConvexityHull model object using finmodel.

Data Types: object

`DiscountCurve` — `ratecurve` object for discounting cash flows
`ratecurve` object

ratecurve object for discounting cash flows, specified as DiscountCurve and the name of a previously created ratecurve object.

Data Types: object

Output Arguments

expand all

`CMSConvexityHullPricerObj` — CMS Convexity Hull pricer
`CMSConvexityHull` object

CMS Convexity Hull pricer, returned as a CMSConvexityHull object.

Properties

expand all

`Model` — Model
`CMSConvexityHull` model object

Model, returned as a CMSConvexityHull model object.

Data Types: object

`DiscountCurve` — `ratecurve` object for discounting cash flows
`ratecurve` object

ratecurve object for discounting cash flows, returned as a ratecurve object.

Data Types: object

Object Functions

price Compute price for interest-rate, equity, or credit derivative instrument with Analytic pricer

Examples

collapse all

Use `CMSConvexityHull` Pricer and `CMSConvexityHull` Model to Price `CMS` and `CMSNote` Instruments

Open Live Script

This example shows the workflow to price a CMS and 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 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: [10×1 datetime]
                Rates: [10×1 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: [0×0 ratecurve]
       BusinessDayConvention: ["actual"    "actual"]
                    Holidays: NaT
                EndMonthRule: [1 1]
                   StartDate: NaT
                    Maturity: 15-Sep-2028
                        Name: "CMS instrument"

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: [0×0 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: [14×3 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: [1×1 finmodel.CMSConvexityHull]
    DiscountCurve: [1×1 ratecurve]

Price CMS and CMSNote Instruments

Use price to compute the price for the CMS and CMSNote instruments.

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

CMSPrice = 
11.5623

outPR = 
  priceresult with properties:

       Results: [1×1 table]
    PricerData: [13×7 timetable]

outPR.PricerData % For the CMS instrument

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

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

CMSNotePrice = 
109.1087

outPR = 
  priceresult with properties:

       Results: [1×1 table]
    PricerData: [13×7 timetable]

outPR.PricerData % For the CMS Note instrument

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 Convexity Hull Pricing Method

The CMS convexity Hull pricing method is a technique used in the finance industry to price CMS or CMSNote instruments and this method addresses the complex relationship between interest rates and the pricing of these financial instruments, particularly focusing on the convexity properties of the underlying interest-rate curves.

Convexity refers to the curvature in the relationship between bond prices and interest rates. In the context of CMS pricing, understanding and modeling convexity is crucial because it affects how the value of the swap changes with movements in interest rates.

Version History

Introduced in R2023a

CMSConvexityHull

Description

Creation

Syntax

Description

Input Arguments

`PricerType` — Pricer type
string with value `"Analytic"` | character vector with value `'Analytic'`

Name-Value Arguments

`Model` — Model
`CMSConvexityHull` model object

`DiscountCurve` — `ratecurve` object for discounting cash flows
`ratecurve` object

Output Arguments

`CMSConvexityHullPricerObj` — CMS Convexity Hull pricer
`CMSConvexityHull` object

Properties

`Model` — Model
`CMSConvexityHull` model object

`DiscountCurve` — `ratecurve` object for discounting cash flows
`ratecurve` object

Object Functions

Examples

Use `CMSConvexityHull` Pricer and `CMSConvexityHull` Model to Price `CMS` and `CMSNote` Instruments

More About

CMS Convexity Hull Pricing Method

Version History

See Also

Functions

Topics

CMSConvexityHull

Description

Creation

Syntax

Description

Input Arguments

PricerType — Pricer type string with value "Analytic" | character vector with value 'Analytic'

Name-Value Arguments

Model — Model CMSConvexityHull model object

DiscountCurve — ratecurve object for discounting cash flows ratecurve object

Output Arguments

CMSConvexityHullPricerObj — CMS Convexity Hull pricer CMSConvexityHull object

Properties

Model — Model CMSConvexityHull model object

DiscountCurve — ratecurve object for discounting cash flows ratecurve object

Object Functions

Examples

Use CMSConvexityHull Pricer and CMSConvexityHull Model to Price CMS and CMSNote Instruments

More About

CMS Convexity Hull Pricing Method

Version History

See Also

Functions

Topics

`PricerType` — Pricer type
string with value `"Analytic"` | character vector with value `'Analytic'`

`Model` — Model
`CMSConvexityHull` model object

`DiscountCurve` — `ratecurve` object for discounting cash flows
`ratecurve` object

`CMSConvexityHullPricerObj` — CMS Convexity Hull pricer
`CMSConvexityHull` object

`Model` — Model
`CMSConvexityHull` model object

`DiscountCurve` — `ratecurve` object for discounting cash flows
`ratecurve` object

Use `CMSConvexityHull` Pricer and `CMSConvexityHull` Model to Price `CMS` and `CMSNote` Instruments