instrangefloat

Construct range note instrument

Syntax

InstSet = instrangefloat(Spread,Settle,Maturity,RateSched,Reset,Basis,Principal,EndMonthRule)

InstSet = instrangefloat(___,Reset,Basis,Principal,EndMonthRule)

InstSet = instrangefloat(InstSet,___)

Description

InstSet = instrangefloat(Spread,Settle,Maturity,RateSched,Reset,Basis,Principal,EndMonthRule) creates a range instrument from data arrays.

InstSet = instrangefloat(___,Reset,Basis,Principal,EndMonthRule) creates a range instrument from data arrays using optional arguments.

InstSet = instrangefloat(InstSet,___) adds new range set instrument to an existing instrument set.

Examples

Create a Range Note Instrument

Create an instrument portfolio with a range note.

Spread = 100;
Settle = datetime(2011,1,1);
Maturity = datetime(2014,1,1);

RateSched.Dates = [datetime(2012,1,1) ; datetime(2013,1,1) ; datetime(2014,1,1)];
RateSched.Rates  = [0.045 0.055; 0.0525  0.0675; 0.06 0.08];

% Create InstSet
InstSet = instrangefloat(Spread, Settle, Maturity, RateSched);

% Display the portfolio instrument
instdisp(InstSet)

Index Type       Spread Settle         Maturity       RateSched FloatReset Basis Principal EndMonthRule
1     RangeFloat 100    01-Jan-2011    01-Jan-2014    [Struct]  1          0     100       1           
 

Add a second range note instrument to the portfolio. Second Range Note:

Spread2 = 200;
Settle2 = datetime(2011,1,1);
Maturity2 = datetime(2013,1,1);
RateSched2.Dates = [datetime(2012,1,1) ; datetime(2013,1,1)];
RateSched2.Rates  = [0.048 0.059; 0.055  0.068];

InstSet = instrangefloat(InstSet, Spread2, Settle2, Maturity2, RateSched2);

% Display the portfolio instrument
instdisp(InstSet)

Index Type       Spread Settle         Maturity       RateSched FloatReset Basis Principal EndMonthRule
1     RangeFloat 100    01-Jan-2011    01-Jan-2014    [Struct]  1          0     100       1           
2     RangeFloat 200    01-Jan-2011    01-Jan-2013    [Struct]  1          0     100       1           
 

Input Arguments

InstSet — Instrument variable

structure

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

Data Types: struct

Spread — Number of basis points over the reference rate

numeric

Number of basis points over the reference rate, specified as a scalar numeric.

Data Types: double

Settle — Settlement date of floating-rate note

datetime array | string array | date character vector

Settlement date of floating-rate note, specified as an NINST-by-1 vector using a datetime array, string array, or date character vectors.

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

Maturity — Maturity date of floating-rate note

datetime array | string array | date character vector

Maturity date of floating-rate note, specified as an NINST-by-1 vector using a datetime array, string array, or date character vectors.

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

RateSched — Range of dates within which cash flows are nonzero

date character vector

Range of dates within which cash flows are nonzero, specified as an NINST-by-1 structure where each element of the structure array contains two fields:

• RateSched.Dates — NDates-by-1 cell array of dates corresponding to the range schedule.

• RateSched.Rates —NDates-by-2 array with the first column containing the lower bound of the range and the second column containing the upper bound of the range. Cash flow for date RateSched.Dates(n) is nonzero for rates in the range RateSched.Rates(n,1) < Rate < RateSched.Rate (n,2).

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

Reset — Frequency of payments per year

1 (default) | integer

(Optional) Frequency of payments per year, specified as 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 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 amounts, specified and an NINST-by-1 vector.

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 an NINST-by-1 vector.

• 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

Output Arguments

InstSet — Variable containing a collection of instruments

structure

Variable containing a collection of instruments, returned as a structure. Instruments are divided by type and each type can have different data fields. Each stored data field has a row vector or character vector for each instrument. Values are:

• FieldList — NFIELDS-by-1 cell array of character vectors listing the name of each data field for this instrument type.

• ClassList — NFIELDS-by-1 cell array of character vectors listing the data class of each field. The class determines how arguments are parsed. Valid character vectors are'dble', 'date', and 'char'.

• TypeString — Character vector specifying the type of instrument added. TypeString = 'RangeFloat'.

For more information on the InstSet variable, see instget.

More About

Range Note Instrument

A range note is a structured (market-linked) security whose coupon rate is equal to the reference rate as long as the reference rate is within a certain range.

If the reference rate is outside of the range, the coupon rate is 0 for that period. This type of instrument entitles the holder to cash flows that depend on the level of some reference interest rate and are floored to be positive. The note holder gets direct exposure to the reference rate. In return for the drawback that no interest is paid for the time the range is left, they offer higher coupon rates than comparable standard products, like vanilla floating notes.

References

[1] Jarrow, Robert. “Modelling Fixed Income Securities and Interest Rate Options.” Stanford Economics and Finance. 2nd Edition. 2002.

Version History

Introduced in R2012a

R2022b: Serial date numbers not recommended

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