Instrument Constructors

The toolbox provides constructors for the most common financial instruments. A constructor is a function that builds a structure dedicated to a certain type of object; in this toolbox, an object is a type of market instrument.

The instruments and their constructor functions are listed below.

Each instrument has parameters (fields) that describe the instrument. The toolbox functions let you do the following:

The instrument structure consists of various fields according to instrument type. A field is an element of data associated with the instrument. For example, a bond instrument contains the fields: CouponRate, Settle, Maturity. Also, each instrument has a field that identifies the investment type (bond, cap, floor, and so on).

In reality, the set of parameters for each instrument is not fixed. You have the ability to add additional parameters. These additional fields are ignored by the toolbox functions. They may be used to attach additional information to each instrument, such as an internal code describing the bond.

Parameters not specified when creating an instrument default to NaN, which, in general, means that the functions using the instrument set (such as intenvprice or hjmprice) will use default values. At the time of pricing, an error occurs if any of the required fields is missing, such as Strike in a cap or CouponRate in a bond.

Creating Instruments or Properties

Use the instaddfield function to create a kind of instrument or to add new properties to the instruments in an existing instrument collection.

To create a kind of instrument with instaddfield, you must specify three arguments:

Type defines the type of the new instrument, for example, Future. FieldName names the fields uniquely associated with the new type of instrument. Data contains the data for the fields of the new instrument.

An optional fourth argument is ClassList. ClassList specifies the data types of the contents of each unique field for the new instrument.

Use either syntax to create a kind of instrument using instaddfield:

InstSet = instaddfield('FieldName', FieldList, 'Data', DataList,...
'Type', TypeString)
InstSet = instaddfield('FieldName', FieldList, 'FieldClass',...
ClassList, 'Data' , DataList, 'Type', TypeString)

To add new instruments to an existing set, use:

InstSetNew = instaddfield(InstSetOld, 'FieldName', FieldList,...
'Data', DataList, 'Type', TypeString)

As an example, consider a futures contract with a delivery date of July 15, 2000, and a quoted price of $104.40. Since Financial Instruments Toolbox™ software does not directly support this instrument, you must create it using the function instaddfield. Use these parameters to create instruments:

Enter the data into MATLAB^® software:

Type = 'Future';
FieldName = {'Delivery', 'Price'};
Data = {'Jul-15-2000', 104.4};

Finally, create the portfolio with a single instrument:

Port = instaddfield('Type', Type, 'FieldName', FieldName,... 
'Data', Data);

Now use the function instdisp to examine the resulting single-instrument portfolio:

instdisp(Port)

Index Type   Delivery    Price
1     Future Jul-15-2000 104.4

Because your portfolio Port has the same structure as those created using the function instadd, you can combine portfolios created using instadd with portfolios created using instaddfield. For example, you can now add two cap instruments to Port with instadd.

Strike = [0.06; 0.07];
Settle = '08-Feb-2000';
Maturity = '15-Jan-2003';
 
Port = instadd(Port, 'Cap', Strike, Settle, Maturity);

View the resulting portfolio using instdisp.

instdisp(Port)

Index   Type   Delivery      Price
1       Future 15-Jul-2000   104.4
 
Index Type Strike Settle      Maturity    CapReset  Basis Principal
2     Cap  0.06   08-Feb-2000 15-Jan-2003 1         0     100 
3     Cap  0.07   08-Feb-2000 15-Jan-2003 1         0     100 

Searching or Subsetting a Portfolio

Financial Instruments Toolbox provides functions that enable you to:

The instfind function finds instruments with a specific parameter value; it returns an instrument index (position) in a large instrument set. The instselect function, on the other hand, subsets a large instrument set into a portfolio of instruments with designated parameter values; it returns an instrument set (portfolio) rather than an index.

IndexMatch = instfind(InstSet, 'FieldName', FieldList, 'Data',...
DataList, 'Index', IndexSet, 'Type', TypeList)

load deriv.mat
instdisp(HJMInstSet)

Index Type CouponRate Settle       Maturity     Period Basis ...  Name      Quantity
1    Bond 0.04       01-Jan-2000  01-Jan-2003    1     NaN   ... 4% bond     100 
2    Bond 0.04       01-Jan-2000  01-Jan-2004    2     NaN   ... 4% bond      50 

Index Type    UnderInd OptSpec Strike ExerciseDates  AmericanOpt Name        Quantity
3     OptBond 2        call    101    01-Jan-2003    NaN         Option 101   -50     
 
Index Type  CouponRate Settle      Maturity     FixedReset Basis Principal Name     Quantity
4     Fixed 0.04       01-Jan-2000 01-Jan-2003    1        NaN    NaN     4% Fixed   80 
 
Index Type  Spread Settle      Maturity   FloatReset  Basis Principal Name        Quantity
5     Float 20     01-Jan-2000 01-Jan-2003 1           NaN   NaN       20BP Float   8  
 
Index Type Strike Settle         Maturity      CapReset Basis Principal Name     Quantity
6     Cap  0.03   01-Jan-2000    01-Jan-2004    1        NaN   NaN       3% Cap   30  
 
Index Type  Strike Settle      Maturity     FloorReset Basis Principal Name       Quantity
7     Floor 0.03 01-Jan-2000 01-Jan-2004    1          NaN   NaN         3% Floor   40 
 
Index Type LegRate   Settle     Maturity     LegReset Basis Principal LegType  Name   Quantity

8     Swap [0.06 20] 01-Jan-2000  01-Jan-2003  [1  1]   NaN   NaN     [NaN]  6%/20BP Swap  10

Mat2003 = ... 
instfind(HJMInstSet,'FieldName','Maturity','Data','01-Jan-2003')

Mat2003 =

     1
     4
     5
     8

CapFloor = instfind(HJMInstSet,... 
'FieldName','Maturity','Data','01-Jan-2004', 'Type',... 
{'Cap';'Floor'})

CapFloor =

     6
     7

Pos50 = instfind(HJMInstSet,'FieldName',... 
'Quantity','Data',{'50';'-50'})

Pos50 =

     2
     3

Mat2003 = ... 
instfind(HJMInstSet,'FieldName','Maturity','Data','01-Jan-2003')

Mat2003 =

     1
     4
     5
     8

Select2003 = ... 
instselect(HJMInstSet,'FieldName','Maturity','Data',... 
'01-Jan-2003')

instdisp(Select2003)

Index Type CouponRate Settle         Maturity       Period Basis EndMonthRule IssueDate FirstCouponDate LastCouponDate StartDate Face Name    Quantity
1     Bond 0.04       01-Jan-2000    01-Jan-2003    1      NaN   NaN          NaN       NaN             NaN            NaN       NaN  4% bond 100     
 
Index Type  CouponRate Settle         Maturity       FixedReset Basis Principal Name     Quantity
2     Fixed 0.04       01-Jan-2000    01-Jan-2003    1          NaN   NaN       4% Fixed 80      
 
Index Type  Spread Settle         Maturity       FloatReset Basis Principal Name       Quantity
3     Float 20     01-Jan-2000    01-Jan-2003    1          NaN   NaN       20BP Float 8       
 
Index Type LegRate    Settle         Maturity       LegReset Basis Principal LegType Name         Quantity
4     Swap [0.06  20] 01-Jan-2000    01-Jan-2003    [1  1]   NaN   NaN       [NaN]   6%/20BP Swap 10      

load InstSetExamples.mat
instdisp(ExampleInst)

Index Type   Strike Price Opt  Contracts
1     Option  95    12.2  Call     0    
2     Option 100     9.2  Call     0    
3     Option 105     6.8  Call  1000    
 
Index Type    Delivery       F     Contracts
4     Futures 01-Jul-1999    104.4 -1000    
 
Index Type   Strike Price Opt  Contracts
5     Option 105     7.4  Put  -1000    
6     Option  95     2.9  Put      0    
 
Index Type  Price Maturity       Contracts
7     TBill 99    01-Jul-1999    6        

InstSet = instselect(ExampleInst,'FieldName','Strike','Data',95);

instdisp(InstSet)

Index Type   Strike Price Opt  Contracts
1     Option  95    12.2  Call     0    
2     Option  95     2.9  Put      0