instswap

Construct swap instrument

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.

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

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

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

Examples

Create a Vanilla Swap Instrument

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

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

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

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

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

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

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.