Instrument Construction and Portfolio Management Using Functions

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.

Instrument	Constructor Function
Asian option	instasian
Barrier option	instbarrier
Bond	instbond
Bond option	instoptbnd
Arbitrary cash flow	instcf
Compound option	instcompound
Convertible bond	instcbond
Fixed-rate note	instfixed
Floating-rate note	instfloat
Cap	instcap
Floor	instfloor
Lookback option	instlookback
Stock option	instoptstock
Swap	instswap
Swaption	instswaption

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

• Create an instrument or portfolio of instruments.

• Enumerate stored instrument types and information fields.

• Enumerate instrument field data.

• Search and select instruments.

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

• FieldName

• Data

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:

• Type: Future

• Field names: Delivery and Price

• Data: Delivery is July 15, 2000, and price is $104.40.

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:

• Find specific instruments within a portfolio.

• Create a subset portfolio consisting of instruments selected from a larger portfolio.

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.

instfind

The general syntax for instfind is

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

InstSet is the instrument set to search. Within InstSet instruments categorized by type, each type can have different data fields. The stored data field is a row vector or character vector for each instrument.

The FieldList, DataList, and TypeList arguments indicate values to search for in the FieldName, Data, and Type data fields of the instrument set. FieldList is a cell array of field names specific to the instruments. DataList is a cell array or matrix of acceptable values for one or more parameters specified in FieldList. FieldName and Data (therefore, FieldList and DataList) parameters must appear together or not at all.

IndexSet is a vector of integer indexes designating positions of instruments in the instrument set to check for matches; the default is all indices available in the instrument set. TypeList is a character vector or cell array of character vectors restricting instruments to match one of the TypeList types; the default is all types in the instrument set.

IndexMatch is a vector of positions of instruments matching the input criteria. Instruments are returned in IndexMatch if all the FieldName, Data, Index, and Type conditions are met. An instrument meets an individual field condition if the stored FieldName data matches any of the rows listed in the DataList for that FieldName.

instfind Examples.  The examples use the provided MAT-file deriv.mat.

The MAT-file contains an instrument set, HJMInstSet, that contains eight instruments of seven types.

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

Find all instruments with a maturity date of January 01, 2003.

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

Mat2003 =

     1
     4
     5
     8

Find all cap and floor instruments with a maturity date of January 01, 2004.

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

CapFloor =

     6
     7

Find all instruments where the portfolio is long or short a quantity of 50.

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

Pos50 =

     2
     3

instselect

The syntax for instselect is the same syntax as for instfind. instselect returns a full portfolio instead of indexes into the original portfolio. Compare the values returned by both functions by calling them equivalently.

Previously you used instfind to find all instruments in HJMInstSet with a maturity date of January 01, 2003.

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

Mat2003 =

     1
     4
     5
     8

Now use the same instrument set as a starting point, but execute the instselect function instead, to produce a new instrument set matching the identical search criteria.

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      

instselect Examples.  These examples use the portfolio ExampleInst provided with the MAT-file InstSetExamples.mat.

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        

The instrument set contains three instrument types: Option, Futures, and TBill. Use instselect to make a new instrument set containing only options struck at 95. In other words, select all instruments containing the field Strike and with the data value for that field equal to 95.

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    

You can use all the various forms of instselect and instfind to locate specific instruments within this instrument set.