Main Content

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:

  1. Use fininstrument to create a CMS or CMSNote instrument object.

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

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

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

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

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

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

Properties

expand all

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

Data Types: timetable

Examples

collapse all

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: [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 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 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: [1x1 table]
    PricerData: [13x7 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: [1x1 table]
    PricerData: [13x7 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 

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: [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 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 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: [14x3 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: [1x1 finmodel.CMSConvexityHull]
    DiscountCurve: [1x1 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: [1x1 table]
    PricerData: [13x7 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: [1x1 table]
    PricerData: [13x7 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

References

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

Version History

Introduced in R2023a