instswap

Construct swap instrument

collapse all in page

Syntax

InstSet = instswap(LegRate,Settle,Maturity)

InstSet = instswap(InstSet,LegRate,Settle,Maturity)

InstSet = instswap(___,LegReset,Basis,Principal,LegType,EndMonthRule,StartDate)

[FieldList,ClassList,TypeString] = instswap

Description

InstSet = instswap(LegRate,Settle,Maturity) creates a new instrument set containing Swap instruments.

example

InstSet = instswap(InstSet,LegRate,Settle,Maturity) adds Swap instruments to an existing instrument set.

example

InstSet = instswap(___,LegReset,Basis,Principal,LegType,EndMonthRule,StartDate) adds optional arguments for LegReset, Basis, Principal, LegType, EndMonthRule, and StartDate.

example

[FieldList,ClassList,TypeString] = instswap lists field meta-data for the Swap instrument.

example

Examples

collapse all

Create a Vanilla Swap Instrument

Open Live Script

Create a vanilla swap using market data.

Use the following market data to create a swap instrument.

LegRate = [0.065, 0]

LegRate = 1×2

    0.0650         0

Settle = datetime(2007,1,1);    
Maturity = datetime(2012,1,1);
LegReset = [1, 1];
Basis = 0

Basis = 
0

Principal = 100

Principal = 
100

LegType = [1, 0]

LegType = 1×2

     1     0

InstSet = instswap(LegRate, Settle, Maturity, LegReset, Basis, Principal, LegType)

InstSet = struct with fields:
        FinObj: 'Instruments'
    IndexTable: [1x1 struct]
          Type: {'Swap'}
     FieldName: {{9x1 cell}}
    FieldClass: {{9x1 cell}}
     FieldData: {{9x1 cell}}

View the swap instrument using instdisp.

instdisp(InstSet)

Index Type LegRate    Settle         Maturity       LegReset Basis Principal LegType EndMonthRule StartDate
1     Swap [0.065  0] 01-Jan-2007    01-Jan-2012    [1  1]   0     100       [1  0]  1            NaN

Create a Float-Float Swap and Price with `intenvprice`

Open Live Script

Use instswap to create a float-float swap and price the swap with intenvprice.

RateSpec = intenvset('Rates',.05,'StartDate',today,'EndDate',datemnth(today,60));
IS = instswap([40 20],today,datemnth(today,60),[], [], [], [0 0]);
intenvprice(RateSpec,IS)

ans = 
0.8644

Create Float-Float, Fixed-Fixed, and Float-Fixed Swaps and Price with `intenvprice`

Open Live Script

Use instswap to create swaps and price the swaps with intenvprice.

RateSpec = intenvset('Rates',.05,'StartDate',today,'EndDate',datemnth(today,60));
IS = instswap([.03 .02],today,datemnth(today,60),[], [], [], [1 1]);
IS = instswap(IS,[200 300],today,datemnth(today,60),[], [], [], [0 0]);
IS = instswap(IS,[300 .07],today,datemnth(today,60),[], [], [], [0 1]);
intenvprice(RateSpec,IS)

ans = 3×1

    4.3220
   -4.3220
    4.5921

Input Arguments

collapse all

`InstSet` — Instrument variable
structure

Instrument variable, specified only when adding Swap instruments to an existing instrument set. For more information on the InstSet variable, see instget.

Data Types: struct

`LegRate` — Leg rate
matrix

Leg rate, specified as a scalar or an NINST-by-2 matrix, with each row defined as one of the following:

[CouponRate Spread] (fixed-float)
[Spread CouponRate] (float-fixed)
[CouponRate CouponRate] (fixed-fixed)
[Spread Spread] (float-float)

CouponRate is the decimal annual rate. Spread is the number of basis points over the reference rate. The first column represents the receiving leg, while the second column represents the paying leg.

Data Types: double

`Settle` — Settlement date
datetime array | string array | date character vector

Settlement date, specified either as a scalar or NINST-by-1 vector using a datetime array, string array, or date character vectors.

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

`Maturity` — Maturity date
datetime array | string array | date character vector

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

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

`LegReset` — Reset frequency per year for each swap
`[1 1]` (default) | vector

(Optional) Reset frequency per year for each swap, specified as an NINST-by-2 vector.

Data Types: double

`Basis` — Day-count basis representing the basis for each leg
`0` (actual/actual) (default) | integer from `0` to `13`

(Optional) Day-count basis representing the basis for each leg, specified as an NINST-by-1 array (or NINST-by-2 if Basis is different for each 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 amounts or principal value schedules
`100` (default) | vector or cell array

(Optional) Notional principal amounts or principal value schedules, specified as a vector or cell array.

Principal accepts an NINST-by-1 vector or an NINST-by-1 cell array (or NINST-by-2 if Principal is different for each leg) of the notional principal amounts or principal value schedules. For schedules, each element of the cell array is a NumDates-by-2 array where the first column is dates and the second column is its associated notional principal value. The date indicates the last day that the principal value is valid.

Data Types: cell | double

`LegType` — Leg type
`[1 0]` for each instrument (default) | matrix with values `[1 1]` (fixed-fixed), `[1 0]` (fixed-float), `[0 1]` (float-fixed), or `[0 0]` (float-float)

(Optional) Leg type, specified as an NINST-by-2 matrix with values [1 1] (fixed-fixed), [1 0] (fixed-float), [0 1] (float-fixed), or [0 0] (float-float). Each row represents an instrument. Each column indicates if the corresponding leg is fixed (1) or floating (0). This matrix defines the interpretation of the values entered in LegRate. LegType allows [1 1] (fixed-fixed), [1 0] (fixed-float), [0 1] (float-fixed), or [0 0] (float-float) swaps

Data Types: double

`EndMonthRule` — End-of-month rule flag for generating dates when `Maturity` is end-of-month date for month having 30 or fewer days
`1` (in effect) (default) | nonnegative integer `[0,1]`

(Optional) End-of-month rule flag for generating dates when Maturity is an end-of-month date for a month having 30 or fewer days, specified as a nonnegative integer 0 or 1using an NINST-by-1 (or NINST-by-2 if EndMonthRule is different for each leg).

0 = Ignore rule, meaning that a payment date is always the same numerical day of the month.
1 = Set rule on, meaning that a payment date is always the last actual day of the month.

Data Types: logical

`StartDate` — Date swap actually starts
`Settle` date (default) | datetime array | string array | date character vector

(Optional) Date swap actually starts, specified as an NINST-by-1 vector using a datetime array, string array, or date character vectors.

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

Use this argument to price forward swaps, that is, swaps that start in a future date

Output Arguments

collapse all

`InstSet` — Variable containing a collection of instruments
structure

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

`FieldList` — Name of each data field for Swap instrument
cell array of character vectors

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

`ClassList` — Data class for each field
cell array of character vectors

Data class for each field, returned as an NFIELDS-by-1 cell array of character vectors. The class determines how arguments are parsed. Valid character vectors are 'dble', 'date', and 'char'.

`TypeString` — Type of instrument
character vector

Type of instrument, returned as a character vector. For a Swap instrument, TypeString = 'Swap'.

More About

collapse all

Amortizing Swap

In an amortizing swap, the notional principal decreases periodically because it is tied to an underlying financial instrument with a declining (amortizing) principal balance, such as a mortgage.

Forward Swap

Agreement to enter into an interest-rate swap arrangement on a fixed date in future.

Version History

Introduced before R2006a

expand all

R2022b: Serial date numbers not recommended

Although instswap 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.

instswap

Syntax

Description

Examples

Create a Vanilla Swap Instrument

Create a Float-Float Swap and Price with `intenvprice`

Create Float-Float, Fixed-Fixed, and Float-Fixed Swaps and Price with `intenvprice`

Input Arguments

`InstSet` — Instrument variable
structure

`LegRate` — Leg rate
matrix

`Settle` — Settlement date
datetime array | string array | date character vector

`Maturity` — Maturity date
datetime array | string array | date character vector

`LegReset` — Reset frequency per year for each swap
`[1 1]` (default) | vector

`Basis` — Day-count basis representing the basis for each leg
`0` (actual/actual) (default) | integer from `0` to `13`

`Principal` — Notional principal amounts or principal value schedules
`100` (default) | vector or cell array

`LegType` — Leg type
`[1 0]` for each instrument (default) | matrix with values `[1 1]` (fixed-fixed), `[1 0]` (fixed-float), `[0 1]` (float-fixed), or `[0 0]` (float-float)

`EndMonthRule` — End-of-month rule flag for generating dates when `Maturity` is end-of-month date for month having 30 or fewer days
`1` (in effect) (default) | nonnegative integer `[0,1]`

`StartDate` — Date swap actually starts
`Settle` date (default) | datetime array | string array | date character vector

Output Arguments

`InstSet` — Variable containing a collection of instruments
structure

`FieldList` — Name of each data field for Swap instrument
cell array of character vectors

`ClassList` — Data class for each field
cell array of character vectors

`TypeString` — Type of instrument
character vector

More About

Amortizing Swap

Forward Swap

Version History

R2022b: Serial date numbers not recommended

See Also

Topics

instswap

Syntax

Description

Examples

Create a Vanilla Swap Instrument

Create a Float-Float Swap and Price with intenvprice

Create Float-Float, Fixed-Fixed, and Float-Fixed Swaps and Price with intenvprice

Input Arguments

InstSet — Instrument variable structure

LegRate — Leg rate matrix

Settle — Settlement date datetime array | string array | date character vector

Maturity — Maturity date datetime array | string array | date character vector

LegReset — Reset frequency per year for each swap [1 1] (default) | vector

Basis — Day-count basis representing the basis for each leg 0 (actual/actual) (default) | integer from 0 to 13

Principal — Notional principal amounts or principal value schedules 100 (default) | vector or cell array

LegType — Leg type [1 0] for each instrument (default) | matrix with values [1 1] (fixed-fixed), [1 0] (fixed-float), [0 1] (float-fixed), or [0 0] (float-float)

EndMonthRule — End-of-month rule flag for generating dates when Maturity is end-of-month date for month having 30 or fewer days 1 (in effect) (default) | nonnegative integer [0,1]

StartDate — Date swap actually starts Settle date (default) | datetime array | string array | date character vector

Output Arguments

InstSet — Variable containing a collection of instruments structure

FieldList — Name of each data field for Swap instrument cell array of character vectors

ClassList — Data class for each field cell array of character vectors

TypeString — Type of instrument character vector

More About

Amortizing Swap

Forward Swap

Version History

R2022b: Serial date numbers not recommended

See Also

Topics

Create a Float-Float Swap and Price with `intenvprice`

Create Float-Float, Fixed-Fixed, and Float-Fixed Swaps and Price with `intenvprice`

`InstSet` — Instrument variable
structure

`LegRate` — Leg rate
matrix

`Settle` — Settlement date
datetime array | string array | date character vector

`Maturity` — Maturity date
datetime array | string array | date character vector

`LegReset` — Reset frequency per year for each swap
`[1 1]` (default) | vector

`Basis` — Day-count basis representing the basis for each leg
`0` (actual/actual) (default) | integer from `0` to `13`

`Principal` — Notional principal amounts or principal value schedules
`100` (default) | vector or cell array

`LegType` — Leg type
`[1 0]` for each instrument (default) | matrix with values `[1 1]` (fixed-fixed), `[1 0]` (fixed-float), `[0 1]` (float-fixed), or `[0 0]` (float-float)

`EndMonthRule` — End-of-month rule flag for generating dates when `Maturity` is end-of-month date for month having 30 or fewer days
`1` (in effect) (default) | nonnegative integer `[0,1]`

`StartDate` — Date swap actually starts
`Settle` date (default) | datetime array | string array | date character vector

`InstSet` — Variable containing a collection of instruments
structure

`FieldList` — Name of each data field for Swap instrument
cell array of character vectors

`ClassList` — Data class for each field
cell array of character vectors

`TypeString` — Type of instrument
character vector