instswaption

Construct swaption instrument

Syntax

InstSet = instswaption(OptSpec,Strike,ExerciseDates,Spread,Settle,Maturity)

InstSet = instswaption(___,AmericanOpt,SwapReset,Basis,Principal)

InstSet = instswaption(InstSetOld,___)

[FieldList,ClassList,TypeString] = instswaption

Description

InstSet = instswaption(OptSpec,Strike,ExerciseDates,Spread,Settle,Maturity) to specify a European swaption.

Fill in unspecified entries vectors with the value NaN. Only one data argument is required to create the instruments; the others may be omitted or passed as empty matrices [].

InstSet = instswaption(___,AmericanOpt,SwapReset,Basis,Principal) to specify an American swaption.

InstSet = instswaption(InstSetOld,___) to add swaption instruments to an instrument variable.

[FieldList,ClassList,TypeString] = instswaption to list field metadata for the swaption instrument.

Examples

Create Two Swaption Instruments

This example shows how to create two European swaption instruments using the following data.

OptSpec = {'Call'; 'Put'};
Strike = .05;
ExerciseDates = datetime(2011,1,1);
Spread=0;
Settle = datetime(2007,1,1);
Maturity = datetime(2012,1,1);
AmericanOpt = 0;

InstSet = instswaption(OptSpec, Strike, ExerciseDates, Spread, Settle, Maturity, ...
 AmericanOpt);

% view the European swaption instruments using instdisp
instdisp(InstSet)

Index Type     OptSpec Strike ExerciseDates  Spread Settle         Maturity       AmericanOpt SwapReset Basis Principal FloatBasis FixedBasis FloatReset FixedReset
1     Swaption Call    0.05   01-Jan-2011    0      01-Jan-2007    01-Jan-2012    0           1         0     100       NaN        NaN        NaN        NaN       
2     Swaption Put     0.05   01-Jan-2011    0      01-Jan-2007    01-Jan-2012    0           1         0     100       NaN        NaN        NaN        NaN       
 

Create Two European Swaption Instruments with Receiving and Paying Legs

This example shows how to create two European swaption instruments with receiving and paying legs using the following data.

OptSpec = {'Call'; 'Put'};
Strike = .05;
ExerciseDates = datetime(2011,1,1);
Spread=0;
Settle = datetime(2007,1,1);
Maturity = datetime(2012,1,1);
AmericanOpt = 0;
SwapReset = [2 4]; % 1st column represents receiving leg, 2nd column represents paying leg
Basis = [1 3];     % 1st column represents receiving leg, 2nd column represents paying leg

InstSet = instswaption(OptSpec,Strike,ExerciseDates,AmericanOpt,Spread,Settle,Maturity, ...
SwapReset,Basis);

View the European swaption instruments using instdisp.

instdisp(InstSet)

Index Type     OptSpec Strike ExerciseDates  Spread Settle Maturity       AmericanOpt SwapReset Basis Principal FloatBasis FixedBasis FloatReset FixedReset
1     Swaption Call    0.05   01-Jan-2011    0      0      01-Jan-2007    NaN         2  4      1  3  100       NaN        NaN        NaN        NaN       
2     Swaption Put     0.05   01-Jan-2011    0      0      01-Jan-2007    NaN         2  4      1  3  100       NaN        NaN        NaN        NaN       
 

Input Arguments

OptSpec — Definition of option

cell array of character vectors with values 'call' or 'put'

Definition of the option as 'call' or 'put', specified as a NINST-by-1 cell array of character vectors with values 'call' or 'put'. A 'call' swaption entitles the buyer to pay the fixed rate. A 'put' swaption entitles the buyer to receive the fixed rate.

Data Types: char | cell

Strike — Strike swap rate values

vector

Strike swap rate values, specified as a NINST-by-1 vector.

Data Types: double

ExerciseDates — Option exercise dates

datetime array | string array | date character vector

Option exercise dates, specified as a vector using a datetime array, string array, or date character vectors, where each row is the schedule for one option and the last element of each row must be the same as the maturity of the tree.

• For a European option, use a NINST-by-1 vector of exercise dates. Each row is the schedule for one option. For a European option, there is only one ExerciseDate on the option expiry date.

• For an American option, use a NINST-by-2 vector of exercise dates. For each instrument, the option can be exercised on any coupon date between or including the pair of dates on that row. If only one non-NaN date is listed, or if ExerciseDates is NINST-by-1, the option can be exercised between the underlying swap Settle and the single listed ExerciseDate.

To support existing code, instswaption also accepts serial date numbers as inputs, but they are not recommended.

Spread — Number of basis points over the reference rate

nonnegative integer | vector of nonnegative integers

Number of basis points over the reference rate, specified as a vector of nonnegative integers for the number of instruments (NINST)-by-1).

Data Types: double

Settle — Settle date for each swap

datetime array | string array | date character vector

Settle date for each swap, specified as a NINST-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, instswaption also accepts serial date numbers as inputs, but they are not recommended.

Maturity — Maturity date for each swap

datetime array | string array | date character vector

Maturity date for each swap, specified as a NINST-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, instswaption also accepts serial date numbers as inputs, but they are not recommended.

AmericanOpt — Option type

0 European (default) | integer with values 0 or 1

(Optional) Option type, specified as NINST-by-1 integer flags with values:

• 0 — European

• 1 — American

The AmericanOpt argument is required to invoke American exercise rules.

Data Types: double

SwapReset — Reset frequency per year for each leg

1 (default) | numeric

(Optional) Reset frequency per year for each leg, specified as a NINST-by-1 vector or NINST-by-2 matrix. If SwapReset is NINST-by-2, the first column represents the receiving leg, while the second column represents the paying leg.

Data Types: double

Basis — Day-count basis of instrument

0 (actual/actual) (default) | integer from 0 to 13

(Optional) Day-count basis of the instrument, specified as a NINST-by-1 vector or NINST-by-2 matrix representing the basis for each leg. If Basis is NINST-by-2, the first column represents the receiving leg, while the second column represents the paying leg.

• 0 = actual/actual

• 1 = 30/360 (SIA)

• 2 = actual/360

• 3 = actual/365

• 4 = 30/360 (PSA)

• 5 = 30/360 (ISDA)

• 6 = 30/360 (European)

• 7 = actual/365 (Japanese)

• 8 = actual/actual (ICMA)

• 9 = actual/360 (ICMA)

• 10 = actual/365 (ICMA)

• 11 = 30/360E (ICMA)

• 12 = actual/365 (ISDA)

• 13 = BUS/252

For more information, see Basis.

Data Types: double

Principal — Notional principal amount

100 (default) | numeric

(Optional) Notional principal amount, specified as a NINST-by-1 vector.

Data Types: double

InstSetOld — Variable containing an existing collection of instruments

struct

Variable containing an existing collection of instruments, specified as a struct. Instruments are classified by type; each type can have different data fields. The stored data field is a row vector or character vector for each instrument. The InstSetOld argument is specified only when adding swaption instruments to an existing instrument set. For more information on the InstSet variable, see instget.

Data Types: struct

Output Arguments

InstSet — Variable containing collection of instruments

vector

(Optional) Variable containing a collection of instruments. Instruments are broken down by type and each type can have different data fields. Each stored data field has a row vector or character vector for each instrument. For more information on the InstSet variable, see instget.

Data Types: double

FieldList — Name of each data field for this instrument type

cell array of character vectors

Name of each data field for this instrument type, returned as a NFIELDS-by-1 cell array of character vectors.

Data Types: char | cell

ClassList — Data class of each field

character vector with value: 'dble', 'date', or 'char'.

Data class of each field, returned as a NFIELDS-by-1 cell array of character vectors. Valid character vectors are 'dble', 'date', and 'char'.

Data Types: char | cell

TypeString — Type of instrument added

character vector

Type of instrument added, returned as a character vector (for a swaption, TypeString = 'Swaption').

Data Types: char

More About

Swaption

A swaption (swap option) is a financial derivative that gives the holder the right, but not the obligation, to enter into an interest-rate swap agreement at a specified future date and under predetermined terms.

Swaptions are used by investors and institutions to hedge against interest rate fluctuations or to speculate on future changes in interest rates.

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.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although instswaption supports serial date numbers, datetime values are recommended instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

To convert serial date numbers or text to datetime values, use the datetime function. For example:

t = datetime(738427.656845093,"ConvertFrom","datenum");
y = year(t)

y =

        2021

There are no plans to remove support for serial date number inputs.