instcap

Construct cap instrument

Syntax

InstSet = instcap(Strike,Settle,Maturity)

InstSet = instcap(InstSet,Strike,Settle,Maturity)

InstSet = instcap(___,CapReset,Basis,Principal)

[FieldList,ClassList,TypeString] = instcap

Description

InstSet = instcap(Strike,Settle,Maturity) creates a new instrument set containing Cap instruments.

InstSet = instcap(InstSet,Strike,Settle,Maturity) adds Cap instruments to an existing instrument set.

InstSet = instcap(___,CapReset,Basis,Principal) adds optional arguments.

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

Examples

Create Two Cap Instruments

Create a new instrument variable with the following information:

Strike = [0.035; 0.045];
Settle= datetime(2013,1,1); 
Maturity = datetime(2043,1,1); 
Reset = 1;
Basis = 1;
Principal = 1000;

Create the new cap instruments.

InstSet = instcap(Strike, Settle, Maturity, Reset, Basis, Principal)

InstSet = struct with fields:
        FinObj: 'Instruments'
    IndexTable: [1×1 struct]
          Type: {'Cap'}
     FieldName: {{6×1 cell}}
    FieldClass: {{6×1 cell}}
     FieldData: {{6×1 cell}}

Display the cap instruments.

instdisp(InstSet)

Index Type Strike Settle         Maturity       CapReset Basis Principal
1     Cap  0.035  01-Jan-2013    01-Jan-2043    1        1     1000     
2     Cap  0.045  01-Jan-2013    01-Jan-2043    1        1     1000     
 

Input Arguments

InstSet — Instrument variable

structure

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

Data Types: struct

Strike — Rate at which cap is exercised

decimal

Rate at which the Cap is exercised, specified as a scalar or an NINST-by-1 vector of decimal values.

Data Types: double

Settle — Settlement dates

datetime array | string array | date character vector

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

Note

Settle must be earlier than Maturity.

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

Maturity — Maturity dates

datetime array | string array | date character vector

Maturity dates, specified as scalar or an NINST-by-1 vector using a datetime array, string array, or date character vectors.

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

CapReset — Reset frequency payment per year

1 (default) | numeric

(Optional) Reset frequency payment per year, specified as a scalar or an NINST-by-1 vector.

Data Types: double

Basis — Day-count basis

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

(Optional) Day-count basis, specified as scalar or an NINST-by-1 vector.

• 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 scalar or an NINST-by-1 of notional principal amounts, or an NINST-by-1 cell array, where each element is a NumDates-by-2 cell array where the first column is dates and the second column is associated principal amount. The date indicates the last day that the principal value is valid.

Use Principal to pass a schedule to compute the price for an amortizing Cap.

Data Types: double | cell

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 Cap instrument

cell array of character vectors

Name of each data field for a Cap 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 Cap option instrument, TypeString = 'Cap'.

More About

Cap

A cap is a contract that includes a guarantee that sets the maximum interest rate to be paid by the holder, based on an otherwise floating interest rate.

The payoff for a cap is:

$$\max (CurrentRate-CapRate,0)$$

For more information, see Cap.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

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