CMSConvexityHull

Create CMSConvexityHull model object for CMS or CMSNote instrument

Since R2023a

Description

Create and price a CMS or CMSNote instrument object with a CMSConvexity model 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 pricing method for the CMS or CMSNote instrument object.

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

Creation

Syntax

CMSConvexityHullModelObj = finmodel(ModelType,CMSConvexityData=cmsconvexity_value)

Description

CMSConvexityHullModelObj = finmodel(ModelType,CMSConvexityData=cmsconvexity_value) creates a CMSConvexityHull model object for convexity adjustment by specifying ModelType and the required name-value argument CMSConvexityData to set properties. For example, CMSConvexityHullModelObj = finmodel("CMSConvexity",CMSConvexityData=timetable(SwapStartDates,FwdSwapVolatility)) creates a CMSConvexity model object.

example

Input Arguments

expand all

`ModelType` — Model type
string with value `"CMSConvexityHull"` | character vector with value `'CMSConvexityHull'`

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

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: CMSConvexityHullModelObj = finmodel("CMSConvexity",CMSConvexityData=timetable(SwapStartDates,FwdSwapVolatility))

`CMSConvexityData` — Specification for convexity and timing adjustments
timetable

Specification for CMS and CMSNote convexity and timing adjustments, specified as CMSConvexityData and a (NumMaturities-by-3) timetable with the column variables in the following order, left to right:

SwapStartDates — Swap start dates in datetime values
FwdSwapVolatility — Forward swap rate volatilities in decimals
FwdVolatility — Forward rate volatilities in decimals
FwdSwapFwdCorrelation — Correlations between forward swap rates and forward rates in decimals

Note

Optionally, a NumMaturities-by-1 timetable can contain only the first two columns (SwapStartDates and FwdSwapVolatility) for convexity adjustments and omit the last two columns for timing adjustments.

For more information on timing adjustments, see Hull Model for Convexity and Timing Adjustments.

Data Types: timetable

Output Arguments

expand all

`CMSConvexityHullModelObj` — CMS Convexity Hull model
`CMSConvexityHull` object

CMS Convexity Hull model, returned as a CMSConvexityHull object.

Properties

expand all

`CMSConvexityData` — Required information for CMS convexity and timing adjustments
timetable

Required information for CMS convexity and timing adjustments, returned as a timetable.

Data Types: timetable

Examples

collapse all

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

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

Use `CMSConvexityHull` Model with Timing Adjustments and `CMSConvexityHull` Pricer 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 with timing adjustments 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 using the CMSConvexityData name-value argument for specifying a timing adjustment.

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;

FwdVolatility = [34.5;35.3;36.3;36.7;36.6;36.5;36.3; ...
    36.2;36;35.8;35.5;35.3;35.2;35]./100;

FwdSwapFwdCorrelation = [0.95;0.943;0.902;0.81;0.773;0.734;0.687; ...
    0.664;0.639;0.598;0.583;0.542;0.527;0.501];

CMSConvexityHullModelwithTiming = finmodel("CMSConvexityHull",CMSConvexityData= ...
    timetable(SwapStartDates,FwdSwapVolatility, ...
    FwdVolatility,FwdSwapFwdCorrelation))

CMSConvexityHullModelwithTiming = 
  CMSConvexityHull with properties:

    CMSConvexityData: [14×3 timetable]

Create CMSConvexityHull Pricer Object

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

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

CMSConvexityHullPricer = 
  CMSConvexityHull with properties:

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

CMSConvexityHullModelwithTiming.CMSConvexityData

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

    15-Mar-2022             0.375              0.345                 0.95        
    15-Sep-2022             0.387              0.353                0.943        
    15-Mar-2023             0.393              0.363                0.902        
    15-Sep-2023             0.395              0.367                 0.81        
    15-Mar-2024             0.394              0.366                0.773        
    15-Sep-2024             0.393              0.365                0.734        
    15-Mar-2025             0.392              0.363                0.687        
    15-Sep-2025              0.39              0.362                0.664        
    15-Mar-2026             0.388               0.36                0.639        
    15-Sep-2026             0.385              0.358                0.598        
    15-Mar-2027             0.383              0.355                0.583        
    15-Sep-2027              0.38              0.353                0.542        
    15-Mar-2028             0.378              0.352                0.527        
    15-Sep-2028             0.377               0.35                0.501

Price CMS and CMSNote Instruments

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

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

CMSPrice = 
11.5247

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            -4.2322e-06       0.023056      0.5       15-Mar-2033 
    15-Mar-2024     15-Sep-2023          0.024135             0.00045273            -9.0742e-06       0.024579      0.5       15-Sep-2033 
    15-Sep-2024     15-Mar-2024          0.025431             0.00074919            -1.4836e-05       0.026165      0.5       15-Mar-2034 
    15-Mar-2025     15-Sep-2024          0.026751              0.0010992            -2.5603e-05       0.027825      0.5       15-Sep-2034 
    15-Sep-2025     15-Mar-2025           0.02801              0.0014918             -3.514e-05       0.029467      0.5       15-Mar-2035 
    15-Mar-2026     15-Sep-2025          0.029262              0.0019316            -6.0101e-05       0.031133      0.5       15-Sep-2035 
    15-Sep-2026     15-Mar-2026          0.030318              0.0023865            -7.8949e-05       0.032626      0.5       15-Mar-2036 
    15-Mar-2027     15-Sep-2026            0.0313              0.0028593            -0.00010605       0.034054      0.5       15-Sep-2036 
    15-Sep-2027     15-Mar-2027          0.032102               0.003331            -0.00013209       0.035301      0.5       15-Mar-2037 
    15-Mar-2028     15-Sep-2027          0.032798              0.0038007            -0.00015071       0.036448      0.5       15-Sep-2037 
    15-Sep-2028     15-Mar-2028          0.033406              0.0042947            -0.00017798       0.037522      0.5       15-Mar-2038

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

CMSNotePrice = 
109.0712

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            -4.2322e-06       0.023056      0.5       15-Mar-2033 
    15-Mar-2024     15-Sep-2023          0.024135             0.00045273            -9.0742e-06       0.024579      0.5       15-Sep-2033 
    15-Sep-2024     15-Mar-2024          0.025431             0.00074919            -1.4836e-05       0.026165      0.5       15-Mar-2034 
    15-Mar-2025     15-Sep-2024          0.026751              0.0010992            -2.5603e-05       0.027825      0.5       15-Sep-2034 
    15-Sep-2025     15-Mar-2025           0.02801              0.0014918             -3.514e-05       0.029467      0.5       15-Mar-2035 
    15-Mar-2026     15-Sep-2025          0.029262              0.0019316            -6.0101e-05       0.031133      0.5       15-Sep-2035 
    15-Sep-2026     15-Mar-2026          0.030318              0.0023865            -7.8949e-05       0.032626      0.5       15-Mar-2036 
    15-Mar-2027     15-Sep-2026            0.0313              0.0028593            -0.00010605       0.034054      0.5       15-Sep-2036 
    15-Sep-2027     15-Mar-2027          0.032102               0.003331            -0.00013209       0.035301      0.5       15-Mar-2037 
    15-Mar-2028     15-Sep-2027          0.032798              0.0038007            -0.00015071       0.036448      0.5       15-Sep-2037 
    15-Sep-2028     15-Mar-2028          0.033406              0.0042947            -0.00017798       0.037522      0.5       15-Mar-2038

More About

expand all

Hull Model for Convexity and Timing Adjustments

The CMSConvexityHull model supports convexity and time adjustments for pricing CMS and CMSNote instruments.

With CMS and CMSNote can be priced using convexity and timing adjustments that are added to the forward swap rates to estimate the expected the CMS rates. The convexity adjustment is required due to the nonlinear relationship between the expected value of the reference swap and the corresponding par swap rate. This relationship is analogous to the nonlinear relationship between bond prices and yields. For CMS and CMSNote instruments, the forward swap rates are not the same as the expected swap rates. Because the cash flows in the CMS derivatives are directly based on the swap rates (rather than the values of the underlying swap legs), the forward swap rates need to be adjusted to estimate the expected CMS rates.

In addition, timing adjustments arise from the fact that the CMS rates are observed one period before the actual payment date. For example, in a CMS instrument, the floating CMS leg payments are based on the swap rates that are set at times t₀, t₁, t₂, ... . The actual floating leg payments are usually made after a time lag at times t₁, t₂, t₃, ... , so that the floating payment at time t_{i +1} is

$\begin{array}{l} τ_{i} L S_{i} \\ τ_{i} = t_{i + 1} - t_{i} \end{array}$

where S_i is the swap rate at time t_i and L is the notional principal.

The Hull convexity and timing adjustment model requires the volatilities (σ_y,i) of forward swap rates corresponding to the relevant CMS reference swap start dates, the volatilities (σ_F,i) of the forward rates between t_i+1 and t_i, and the correlation (ρ_i) between the forward swap rates and the forward rates. For each payment date t_i+1 of the CMS leg, the CMS rate set at t_i is computed as follows:

$\begin{array}{l} C M S R a t e_{i} = y_{i} - \frac{1}{2} y_{i}^{2} σ_{y, i}^{2} t_{i} \frac{G_{i}^{"} (y_{i})}{G_{i}^{'} (y_{i})} - \frac{y_{i} τ_{i} F_{i} ρ_{i} σ_{y, i} σ_{F, i} t_{i}}{1 + F_{i} τ_{i}} \\ G_{i} (x) = \sum_{k = 1}^{C o m p F r e q \times S w a p T e n o r} \begin{array}{l} \frac{C o u p o n R a t e / C o m p F r e q}{{(1 + x / C o m p F r e q)}^{C o m p F r e q \times δ_{k}}} + \frac{1}{{(1 + x / C o m p F r e q)}^{C o m p F r e q \times S w a p T e n o r}} \\ τ_{i} = t_{i + 1} - t_{i} \end{array} \end{array}$

y_i — Forward swap rate for the CMS reference swap starting at t_i.
τ_i — CMS accrual fraction starting at t_i and ending at t_{i+
1}.
δ_k — CMS reference swap accrual fraction at period k.
σ_y,i — Volatility of forward swap rate y_i.
F_i — Forward rate between t_i and t_{i+
1}.
σ_F,i — Volatility of forward rate F_i.
ρ_i — Correlation between y_i and F_i.
G_i(x) — Price at t_i of a bond with yield x with CMS reference swap's maturity and compounding.
G^'_i(x) — First partial derivative of G_i(x) with respect to yield x.
G^"_i(x) — Second partial derivative of G_i(x) with respect to yield x.
CompFreq — Compounding frequency per year for the CMS reference swap.
SwapTenor — Tenor, in years, for the CMS reference swap.
CouponRate — Coupon rate of bond G_i(x) paying at rate y_i.

In the equation for CMSRate_i, the convexity adjustment is the second term:

$- \frac{1}{2} y_{i}^{2} σ_{y, i}^{2} t_{i} \frac{G_{i}^{"} (y_{i})}{G_{i}^{'} (y_{i})}$

The timing adjustment is the last term:

$- \frac{y_{i} τ_{i} F_{i} ρ_{i} σ_{y, i} σ_{F, i} t_{i}}{1 + F_{i} τ_{i}}$

In addition to this model for convexity and timing adjustment, the CMSNote instrument can have an initial coupon period with a fixed initial coupon rate.

References

[1] Hull, J. Options, Futures and Other Derivatives. 11th Edition. Pearson, 2021.

Version History

Introduced in R2023a

CMSConvexityHull

Description

Creation

Syntax

Description

Input Arguments

`ModelType` — Model type
string with value `"CMSConvexityHull"` | character vector with value `'CMSConvexityHull'`

Name-Value Arguments

`CMSConvexityData` — Specification for convexity and timing adjustments
timetable

Output Arguments

`CMSConvexityHullModelObj` — CMS Convexity Hull model
`CMSConvexityHull` object

Properties

`CMSConvexityData` — Required information for CMS convexity and timing adjustments
timetable

Examples

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

Use `CMSConvexityHull` Model with Timing Adjustments and `CMSConvexityHull` Pricer to Price `CMS` and `CMSNote` Instruments

More About

Hull Model for Convexity and Timing Adjustments

References

Version History

See Also

Functions

Topics

CMSConvexityHull

Description

Creation

Syntax

Description

Input Arguments

ModelType — Model type string with value "CMSConvexityHull" | character vector with value 'CMSConvexityHull'

Name-Value Arguments

CMSConvexityData — Specification for convexity and timing adjustments timetable

Output Arguments

CMSConvexityHullModelObj — CMS Convexity Hull model CMSConvexityHull object

Properties

CMSConvexityData — Required information for CMS convexity and timing adjustments timetable

Examples

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

Use CMSConvexityHull Model with Timing Adjustments and CMSConvexityHull Pricer to Price CMS and CMSNote Instruments

More About

Hull Model for Convexity and Timing Adjustments

References

Version History

See Also

Functions

Topics

`ModelType` — Model type
string with value `"CMSConvexityHull"` | character vector with value `'CMSConvexityHull'`

`CMSConvexityData` — Specification for convexity and timing adjustments
timetable

`CMSConvexityHullModelObj` — CMS Convexity Hull model
`CMSConvexityHull` object

`CMSConvexityData` — Required information for CMS convexity and timing adjustments
timetable

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

Use `CMSConvexityHull` Model with Timing Adjustments and `CMSConvexityHull` Pricer to Price `CMS` and `CMSNote` Instruments