Main Content

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.

See Also

| | | | | | | | | | | | | |

Related Examples

More About