CMSConvexityHull
Description
Create and price a CMS
or CMSNote
instrument object with a CMSConvexity
model using this
workflow:
Use
fininstrument
to create aCMS
orCMSNote
instrument object.Use
finmodel
to specify aCMSConvexityHull
model object for theCMS
orCMSNote
instrument object.Use
finpricer
to specify aCMSConvexityHull
pricing method for theCMS
orCMSNote
instrument object.
For more information on this workflow, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.
Creation
Description
creates a CMSConvexityHullModelObj
= finmodel(ModelType
,CMSConvexityData
=cmsconvexity_value)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.
Input Arguments
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
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 valuesFwdSwapVolatility
— Forward swap rate volatilities in decimalsFwdVolatility
— Forward rate volatilities in decimalsFwdSwapFwdCorrelation
— 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
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
Use CMSConvexityHull
Model and CMSConvexityHull
Pricer to Price CMS
and CMSNote
Instrument
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
Use CMSConvexityHull
Model with Timing Adjustments and CMSConvexityHull
Pricer to Price CMS
and CMSNote
Instruments
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
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 t0, t1, t2, ... . The actual floating leg payments are usually made after a time lag at times t1, t2, t3, ... , so that the floating payment at time ti +1 is
where Si is the swap rate at time ti 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 ti+1 and ti, and the correlation (ρi) between the forward swap rates and the forward rates. For each payment date ti+1 of the CMS leg, the CMS rate set at ti is computed as follows:
yi — Forward swap rate for the CMS reference swap starting at ti.
τi — CMS accrual fraction starting at ti and ending at ti+ 1.
δk — CMS reference swap accrual fraction at period k.
σy,i — Volatility of forward swap rate yi.
Fi — Forward rate between ti and ti+ 1.
σF,i — Volatility of forward rate Fi.
ρi — Correlation between yi and Fi.
Gi(x) — Price at ti of a bond with yield x with CMS reference swap's maturity and compounding.
G'i(x) — First partial derivative of Gi(x) with respect to yield x.
G"i(x) — Second partial derivative of Gi(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 Gi(x) paying at rate yi.
In the equation for CMSRatei, the convexity adjustment is the second term:
The timing adjustment is the last term:
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
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)