Swaption

Swaption instrument object

Description

Create and price a Swaption instrument object using this workflow:

1. Use fininstrument to create a Swaption instrument object.

2. Use finmodel to specify a HullWhite, BlackKarasinski, Black, Normal, or SABR model for the Swaption instrument.

3. Use finpricer to specify a Normal, SABR, Black, HullWhite, or IRTree pricing method for the Swaption instrument.

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

For more information on the available models and pricing methods for a Swaption instrument, see Choose Instruments, Models, and Pricers.

Creation

Syntax

SwaptionInstrument = fininstrument(InstrumentType,'Strike',strike_value,'ExerciseDate',exercice_date)

SwaptionInstrument = fininstrument(___,Name,Value)

Description

SwaptionInstrument = fininstrument(InstrumentType,'Strike',strike_value,'ExerciseDate',exercice_date) creates a Swaption object by specifying InstrumentType and sets the properties for the required name-value pair arguments Strike and ExerciseDate. For more information on a Swaption instrument, see More About.

SwaptionInstrument = fininstrument(___,Name,Value) sets optional properties using additional name-value pairs in addition to the required arguments in the previous syntax. For example, SwaptionInstrument = fininstrument("Swaption",'Strike',0.67,'ExerciseDate',datetime(2019,1,30),'Swap',Swap_obj,'OptionType',"put",'ExerciseStyle',"European",'Name',"swaption_instrument") creates a Swaption put instrument with a strike of 0.67 and an European exercise. You can specify multiple name-value pair arguments.

Input Arguments

InstrumentType — Instrument type

string with value "Swaption" | character vector with value 'Swaption'

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

Data Types: char | string

Swaption Name-Value Pair Arguments

Specify required and optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: SwaptionInstrument = fininstrument("Swaption",'Strike',.67,'ExerciseDate',datetime(2019,1,30),'Swap',Swap_obj,'OptionType',"put",'ExerciseStyle',"European",'Name',"swaption_instrument")

Required Swaption Name-Value Pair Arguments

'Strike' — Option strike value

nonnegative decimal

Option strike value, specified as the comma-separated pair consisting of 'Strike' and a scalar nonnegative decimal value.

Data Types: double

'ExerciseDate' — Option exercise date

datetime | serial date number | date character vector | date string

Option exercise date, specified as the comma-separated pair consisting of 'ExerciseDate' and a scalar datetime, serial date number, date character vector, or date string.

Note

For a European option, there is only one ExerciseDate on the option expiry date.

If you use a date character vector or date string, the format must be recognizable by datetime because the ExerciseDate property is stored as a datetime.

Data Types: double | char | string | datetime

'Swap' — Underlying Swap object

Swap object

Underlying Swap object, specified as the comma-separated pair consisting of 'Swap' and a scalar Swap object.

Data Types: object

Optional Swaption Name-Value Pair Arguments

'OptionType' — Option type

"call" (default) | string with values "call" or "put" | character vector with value 'call' or 'put'

Option type, specified as the comma-separated pair consisting of 'OptionType' and a scalar string or character vector.

Data Types: char | string

'ExerciseStyle' — Option exercise style

"European" (default) | string with value "European" | character vector with value 'European'

Option exercise style, specified as the comma-separated pair consisting of 'ExerciseStyle' and a scalar string or character vector.

Note

When you specify a Swap instrument as the underlying asset for a Swaption instrument and use a Normal, SABR, Black, or HullWhite pricer, the Swap instrument LegType must be ["fixed","float"] or ["float","fixed"] and the Swaption instrument ExerciseStyle must be "European".

Data Types: string | char

'Name' — User-defined name for instrument

" " (default) | string | character vector

User-defined name for the instrument, specified as the comma-separated pair consisting of 'Name' and a scalar string or character vector.

Data Types: char | string

Properties

Strike — Option strike value

nonnegative decimal

Option strike value, returned as a scalar nonnegative decimal value.

Data Types: double

ExerciseDate — Option exercise date

datetime

Option exercise date, returned as a datetime.

Data Types: datetime

Swap — Underlying Swap object

Swap object

Swap object, returned as a scalar Swap object.

Data Types: object

OptionType — Option type

"call" (default) | string with value "call" or "put"

Option type, returned as a string with a value of "call" or "put".

Data Types: string

ExerciseStyle — Option exercise style

"European" (default) | string with value "European"

Option exercise style, returned as a string with a value of "European".

Data Types: string

Name — User-defined name for instrument

" " (default) | string

User-defined name for the instrument, returned as a string.

Data Types: string

Examples

Price Swaption Instrument Using SABR Model and SABR Pricer

This example shows the workflow to price a Swaption instrument when you use a SABR model and a SABR pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018,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;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10x1 datetime]
                Rates: [10x1 double]
               Settle: 15-Sep-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Swap Instrument Object

Use fininstrument to create the underlying Swap instrument object.

Swap = fininstrument("Swap",'Maturity',datetime(2027,3,15),'LegRate',[0 0],'LegType',...
    ["float","fixed"],'Notional',100,'StartDate',datetime(2022,3,15),'Name',"swap_instrument")

Swap = 
  Swap with properties:

                     LegRate: [0 0]
                     LegType: ["float"    "fixed"]
                       Reset: [2 2]
                       Basis: [0 0]
                    Notional: 100
          LatestFloatingRate: [NaN NaN]
                 ResetOffset: [0 0]
    DaycountAdjustedCashFlow: [0 0]
             ProjectionCurve: [0x0 ratecurve]
       BusinessDayConvention: ["actual"    "actual"]
                    Holidays: NaT
                EndMonthRule: [1 1]
                   StartDate: 15-Mar-2022
                    Maturity: 15-Mar-2027
                        Name: "swap_instrument"

Create Swaption Instrument Object

Use fininstrument to create a Swaption instrument object.

Swaption = fininstrument("Swaption",'Strike',0.02,'ExerciseDate',datetime(2022,3,15),'Swap',Swap,'Name',"swaption_option")

Swaption = 
  Swaption with properties:

       OptionType: "call"
    ExerciseStyle: "european"
     ExerciseDate: 15-Mar-2022
           Strike: 0.0200
             Swap: [1x1 fininstrument.Swap]
             Name: "swaption_option"

Create SABR Model Object

Use finmodel to create a SABR model object.

SabrModel = finmodel("SABR",'Alpha',0.032,'Beta',0.04,'Rho',.08,'Nu',0.49,'Shift',0.002)

SabrModel = 
  SABR with properties:

             Alpha: 0.0320
              Beta: 0.0400
               Rho: 0.0800
                Nu: 0.4900
             Shift: 0.0020
    VolatilityType: "black"

Create SABR Pricer Object

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

outPricer = finpricer("analytic",'Model',SabrModel,'DiscountCurve',myRC)

outPricer = 
  SABR with properties:

    DiscountCurve: [1x1 ratecurve]
            Model: [1x1 finmodel.SABR]

Price Swaption Instrument

Use price to compute the price for the Swaption instrument.

Price = price(outPricer,Swaption)

Price = 10.8558

Price Swaption Instrument Using Black Model and Black Pricer

This example shows the workflow to price a Swaption instrument when you use a Black model and a Black pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018,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;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10x1 datetime]
                Rates: [10x1 double]
               Settle: 15-Sep-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Swap Instrument Object

Use fininstrument to create the underlying Swap instrument object.

Swap = fininstrument("Swap",'Maturity',datetime(2027,3,15),'LegRate',[0 0],'LegType',...
    ["float","fixed"],'Notional',100,'StartDate',datetime(2022,3,15),'Name',"swap_instrument")

Swap = 
  Swap with properties:

                     LegRate: [0 0]
                     LegType: ["float"    "fixed"]
                       Reset: [2 2]
                       Basis: [0 0]
                    Notional: 100
          LatestFloatingRate: [NaN NaN]
                 ResetOffset: [0 0]
    DaycountAdjustedCashFlow: [0 0]
             ProjectionCurve: [0x0 ratecurve]
       BusinessDayConvention: ["actual"    "actual"]
                    Holidays: NaT
                EndMonthRule: [1 1]
                   StartDate: 15-Mar-2022
                    Maturity: 15-Mar-2027
                        Name: "swap_instrument"

Create Swaption Instrument Object

Use fininstrument to create a Swaption instrument object.

Swaption = fininstrument("Swaption",'Strike',0.02,'ExerciseDate',datetime(2022,3,15),'Swap',Swap,'Name',"swaption_option")

Swaption = 
  Swaption with properties:

       OptionType: "call"
    ExerciseStyle: "european"
     ExerciseDate: 15-Mar-2022
           Strike: 0.0200
             Swap: [1x1 fininstrument.Swap]
             Name: "swaption_option"

Create Black Model Object

Use finmodel to create a Black model object.

BlackModel = finmodel("Black",'Volatility',0.032,'Shift',0.002)

BlackModel = 
  Black with properties:

    Volatility: 0.0320
         Shift: 0.0020

Create Black Pricer Object

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

outPricer = finpricer("analytic",'Model',BlackModel,'DiscountCurve',myRC)

outPricer = 
  Black with properties:

            Model: [1x1 finmodel.Black]
    DiscountCurve: [1x1 ratecurve]

Price Swaption Instrument

Use price to compute the price for the Swaption instrument.

Price = price(outPricer,Swaption)

Price = 3.3116

Price Swaption Instrument Using Hull-White Model and IRTree Pricer

This example shows the workflow to price a Swaption instrument when you use a HullWhite model and an IRTree pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018,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;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10x1 datetime]
                Rates: [10x1 double]
               Settle: 15-Sep-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Swap Instrument Object

Use fininstrument to create the underlying Swap instrument object.

Swap = fininstrument("Swap",'Maturity',datetime(2027,3,15),'LegRate',[0 0],'LegType',...
    ["float","fixed"],'Notional',100,'StartDate',datetime(2022,3,15),'Name',"swap_instrument")

Swap = 
  Swap with properties:

                     LegRate: [0 0]
                     LegType: ["float"    "fixed"]
                       Reset: [2 2]
                       Basis: [0 0]
                    Notional: 100
          LatestFloatingRate: [NaN NaN]
                 ResetOffset: [0 0]
    DaycountAdjustedCashFlow: [0 0]
             ProjectionCurve: [0x0 ratecurve]
       BusinessDayConvention: ["actual"    "actual"]
                    Holidays: NaT
                EndMonthRule: [1 1]
                   StartDate: 15-Mar-2022
                    Maturity: 15-Mar-2027
                        Name: "swap_instrument"

Create Swaption Instrument Object

Use fininstrument to create a Swaption instrument object.

Swaption = fininstrument("Swaption",'Strike',0.02,'ExerciseDate',datetime(2022,3,15),'Swap',Swap,'Name',"swaption_option")

Swaption = 
  Swaption with properties:

       OptionType: "call"
    ExerciseStyle: "european"
     ExerciseDate: 15-Mar-2022
           Strike: 0.0200
             Swap: [1x1 fininstrument.Swap]
             Name: "swaption_option"

Create HullWhite Model Object

Use finmodel to create a HullWhite model object.

HullWhiteModel = finmodel("HullWhite",'Alpha',0.032,'Sigma',0.04)

HullWhiteModel = 
  HullWhite with properties:

    Alpha: 0.0320
    Sigma: 0.0400

Create IRTree Pricer Object

Use finpricer to create an IRTree pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

outPricer = finpricer("IRTree",'Model',HullWhiteModel,'DiscountCurve',myRC,'TreeDates',ZeroDates)

outPricer = 
  HWBKTree with properties:

             Tree: [1x1 struct]
        TreeDates: [10x1 datetime]
            Model: [1x1 finmodel.HullWhite]
    DiscountCurve: [1x1 ratecurve]

Price Swaption Instrument

Use price to compute the price and sensitivities for the Swaption instrument.

[Price, outPR] = price(outPricer,Swaption,["all"])

Price = 14.6581

outPR = 
  priceresult with properties:

       Results: [1x4 table]
    PricerData: [1x1 struct]

outPR.Results

ans=1×4 table
    Price      Vega      Gamma     Delta
    ______    ______    _______    _____

    14.658    321.44    -2261.6    142.2

Calibrate Shifted SABR Model Parameters for Swaption Instrument

This example shows how to calibrate the shifted SABR model parameters for a Swaption instrument when you use a SABR pricing method.

Load Market Data

% Zero curve
ValuationDate = datetime("5-Mar-2016", 'Locale', 'en_US');
ZeroDates = datemnth(ValuationDate,[1 2 3 6 9 12*[1 2 3 4 5 6 7 8 9 10 12]])';
ZeroRates = [-0.33 -0.28 -0.24 -0.12 -0.08 -0.03 0.015 0.028 ...
    0.033 0.042 0.056 0.095 0.194 0.299 0.415 0.525]'/100;
Compounding = 1;
ZeroCurve = ratecurve("zero",ValuationDate,ZeroDates,ZeroRates,'Compounding',Compounding)

ZeroCurve = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: 1
                Basis: 0
                Dates: [16x1 datetime]
                Rates: [16x1 double]
               Settle: 05-Mar-2016
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

% Define the swaptions
SwaptionSettle = datetime("5-Mar-2016", 'Locale', 'en_US');
SwaptionExerciseDate = datetime("5-Mar-2017", 'Locale', 'en_US');
SwaptionStrikes = (-0.6:0.01:1.6)'/100; % Include negative strikes
SwapMaturity = datetime("5-Mar-2022", 'Locale', 'en_US'); % Maturity of underlying swap
OptSpec = 'call';

Compute Forward Swap Rate by Creating Swap Instrument

Use fininstrument to create a Swap instrument object.

LegRate = [0 0];
Swap = fininstrument("Swap", 'Maturity', SwapMaturity, 'LegRate', LegRate, "LegType",["fixed" "float"],...
    "ProjectionCurve", ZeroCurve, "StartDate", SwaptionExerciseDate)

Swap = 
  Swap with properties:

                     LegRate: [0 0]
                     LegType: ["fixed"    "float"]
                       Reset: [2 2]
                       Basis: [0 0]
                    Notional: 100
          LatestFloatingRate: [NaN NaN]
                 ResetOffset: [0 0]
    DaycountAdjustedCashFlow: [0 0]
             ProjectionCurve: [1x2 ratecurve]
       BusinessDayConvention: ["actual"    "actual"]
                    Holidays: NaT
                EndMonthRule: [1 1]
                   StartDate: 05-Mar-2017
                    Maturity: 05-Mar-2022
                        Name: ""

ForwardValue = parswaprate(Swap,ZeroCurve)

ForwardValue = 7.3271e-04

Load the Market Implied Volatility Data

The market swaption volatilities are quoted in terms of shifted Black volatilities with a 0.8 percent shift.

StrikeGrid = [-0.5; -0.25; -0.125; 0; 0.125; 0.25; 0.5; 1.0; 1.5]/100;
MarketStrikes = ForwardValue + StrikeGrid;
Shift = 0.008;  % 0.8 percent shift
MarketShiftedBlackVolatilities = [21.1; 15.3; 14.0; 14.6; 16.0; 17.7; 19.8; 23.9; 26.2]/100;
ATMShiftedBlackVolatility = MarketShiftedBlackVolatilities(StrikeGrid==0);

Calibrate Shifted SABR Model Parameters

The Beta parameter is predetermined at 0.5. Use volatilities to compute the implied volatility.

Beta = 0.5;

% Calibrate Alpha, Rho, and Nu
objFun = @(X) MarketShiftedBlackVolatilities - volatilities(finpricer("Analytic", 'Model', ...
    finmodel("SABR", 'Alpha', X(1), 'Beta', Beta, 'Rho', X(2), 'Nu', X(3), 'Shift', Shift), ...
    'DiscountCurve', ZeroCurve), SwaptionExerciseDate, ForwardValue, MarketStrikes);

X = lsqnonlin(objFun, [0.5 0 0.5], [0 -1 0], [Inf 1 Inf]);

Local minimum possible.

lsqnonlin stopped because the final change in the sum of squares relative to 
its initial value is less than the value of the function tolerance.

Alpha = X(1);
Rho = X(2);
Nu = X(3);

Create SABR Model Using the Calibrated Parameters

Use finmodel to create a SABR model object.

SABRModel = finmodel("SABR",'Alpha',Alpha,'Beta',Beta,'Rho',Rho,'Nu',Nu,'Shift',Shift)

SABRModel = 
  SABR with properties:

             Alpha: 0.0135
              Beta: 0.5000
               Rho: 0.4654
                Nu: 0.4957
             Shift: 0.0080
    VolatilityType: "black"

Create SABR Pricer Using Calibrated SABR Model and Compute Volatilities

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

SABRPricer = finpricer("Analytic", 'Model', SABRModel, 'DiscountCurve', ZeroCurve)

SABRPricer = 
  SABR with properties:

    DiscountCurve: [1x1 ratecurve]
            Model: [1x1 finmodel.SABR]

SABRShiftedBlackVolatilities = volatilities(SABRPricer, SwaptionExerciseDate, ForwardValue, SwaptionStrikes)

SABRShiftedBlackVolatilities = 221×1

    0.2978
    0.2911
    0.2848
    0.2787
    0.2729
    0.2673
    0.2620
    0.2568
    0.2518
    0.2470
      ⋮

figure;
plot(MarketStrikes, MarketShiftedBlackVolatilities, 'o', ...
    SwaptionStrikes, SABRShiftedBlackVolatilities);
h = gca;
line([0,0],[min(h.YLim),max(h.YLim)],'LineStyle','--');
ylim([0.13 0.31])
xlabel('Strike');
legend('Market quotes','Shifted SABR', 'location', 'southeast');
title (['Shifted Black Volatility (',num2str(Shift*100),' percent shift)']);

Price Swaption Instruments Using Calibrated SABR Model and SABR Pricer

% Create swaption instruments
NumInst = length(SwaptionStrikes);
Swaptions(NumInst, 1) = fininstrument("Swaption", ...
    'Strike', SwaptionStrikes(1), 'ExerciseDate', SwaptionExerciseDate(1), 'Swap', Swap);
for k = 1:NumInst
    Swaptions(k) = fininstrument("Swaption", 'Strike', SwaptionStrikes(k), ...
        'ExerciseDate', SwaptionExerciseDate, 'Swap', Swap, 'OptionType', OptSpec);
end
Swaptions

Swaptions=221×1 object
  16x1 Swaption array with properties:

    OptionType
    ExerciseStyle
    ExerciseDate
    Strike
    Swap
    Name
      ⋮

% Price swaptions using the SABR pricer
SwaptionPrices = price(SABRPricer,Swaptions);

figure;
plot(SwaptionStrikes, SwaptionPrices, 'r');
h = gca;
line([0,0],[min(h.YLim),max(h.YLim)],'LineStyle','--');
xlabel('Strike');
title ('Swaption Price');

More About

Call Swaption

A call swaption or payer swaption allows the option buyer to enter into an interest-rate swap in which the buyer of the option pays the fixed rate and receives the floating rate.

Put Swaption

A put swaption or receiver swaption allows the option buyer to enter into an interest-rate swap in which the buyer of the option receives the fixed rate and pays the floating rate.