Financial Derivatives Toolbox

Portfolio Management

The portfolio management capabilities provided by the Financial Derivatives toolbox include:

• Constructors for the most common financial instruments. (See Instrument Constructors.)
• The ability to create new instruments or to add new fields to existing instruments. (See Creating New Instruments or Properties.)
• The ability to search or subset a portfolio. See Searching or Subsetting a Portfolio.)

Instrument Constructors

The toolbox provides constructors for the most common financial instruments.

Note    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 constructors in this toolbox are listed below.

Instrument	Constructor
Bond	instbond
Bond option	instoptbnd
Arbitrary cash flow	instcf
Fixed rate note	instfixed
Floating rate note	instfloat
Cap	instcap
Floor	instfloor
Swap	instswap

Each instrument has parameters (fields) that describe the instrument. The toolbox functions enable you to:

• 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, etc. Additionally, each instrument has a field that identifies the investment type (bond, cap, floor, etc.).

In reality the set of parameters for each instrument is not fixed. Users have the ability to add additional parameters. These additional fields will be 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 the CouponRate in a bond.

Creating New Instruments or Properties

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

To create a new kind of instrument with instaddfield, you need to specify three arguments: 'Type', 'FieldName', and '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 parameter is 'ClassList'. 'ClassList' specifies the data types of the contents of each unique field for the new instrument.

Here are the syntaxes to create a new 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 the Financial Derivatives Toolbox does not directly support this instrument, you must create it using the function instaddfield. The parameters used for the creation of the instruments are:

• Type: Future
• Field names: Delivery and Price
• Data: Delivery is July 15, 2000, and Price is $104.40.

Enter the data into MATLAB.

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

Optionally, you can also specify the data types of the data cell array by creating another cell array containing this information.

• FieldClass = {'date','dble'};
  

Finally, create the portfolio with a single instrument.

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

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

• instdisp(Port)
  
  Index   Type   Delivery      Price
  1       Future 15-Jul-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 Pricip
  al
  2     Cap  0.06   08-Feb-2000 15-Jan-2003 NaN       NaN   NaN      
  3     Cap  0.07   08-Feb-2000 15-Jan-2003 NaN       NaN   NaN  
  

Searching or Subsetting a Portfolio

The Financial Derivatives 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 are categorized by type, and each type can have different data fields. The stored data field is a row vector or string 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 name(s) specific to the instruments. DataList is a cell array or matrix of acceptable values for the parameter(s) specified in FieldList. 'FieldName' and 'Data' (consequently, FieldList and DataList) parameters must appear together or not at all.

IndexSet is a vector of integer index(es) 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 string or cell array of strings 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 exactly 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 .........            Name      Quantity 1     Bond 0.04       01-Jan-2000  01-Jan-2003  1      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.04 20] 01-Jan-2000   01-Jan-2003  [1 1]   NaN NaN [NaN]   4%/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.

Portfolio Creation

Using Financial Derivatives