| Financial Derivatives Toolbox | |
Pricing and Sensitivity from HJM
This section explains how to use the Financial Derivatives Toolbox to compute prices and sensitivities of several financial instruments using the Heath-Jarrow-Morton (HJM) model. For information, see:
hjmprice function to compute prices for a portfolio of instruments.hjmsens function to compute delta, gamma, and vega portfolio sensitivities.Pricing and the Price Tree
Using the HJM model, the function that calculates the price of any set of supported instruments, based on an interest rate tree, is hjmprice. The function is capable of pricing these instrument types:
The syntax used for calling hjmprice is
[Price, PriceTree] = hjmprice(HJMTree, InstSet, Options)
This function requires two input arguments: the interest rate tree, HJMTree, and the set of instruments, InstSet. An optional argument Options further controls the pricing and the output displayed.
HJMTree is the Heath-Jarrow-Morton tree sampling of a forward rate process, created using hjmtree. See Building an HJM Forward Rate Tree to learn how to create this structure based on the volatility model, the interest rate term structure, and the time layout.
InstSet is the set of instruments to be priced. This structure represents the set of instruments to be priced independently using the HJM model. The section Creating and Managing Instrument Portfolios explains how to create this variable.
Options is an options structure created with the function derivset. This structure defines how the HJM tree is used to find the price of instruments in the portfolio, and how much additional information is displayed in the command window when the pricing function is called. If this input argument is not specified in the call to hjmprice, a default Options structure is used.
In actuality, hjmprice is a wrapper function that classifies the instruments and calls appropriate pricing functions for each one of the instrument types. The calculation functions are bondbyhjm, cfbyhjm, fixedbyhjm, floatbyhjm, optbndbyhjm, and swapbyhjm. These functions may also be used directly to calculate the price of sets of instruments of the same type. See the documentation for these individual functions for further information.
Consider the following example, which uses the data in the MAT-file deriv.mat included in the toolbox. Load the data into the MATLAB workspace.
load deriv.mat
Use the MATLAB whos command to display a list of the variables loaded from the MAT-file.
whosName Size Bytes ClassHJMInstSet 1x1 22700 struct array HJMTree 1x1 6302 struct array ZeroInstSet 1x1 14442 struct array ZeroRateSpec 1x1 1588 struct array
HJMTree and HJMInstSet are the input arguments needed to call the function hjmprice.
Use the function instdisp to examine the set of instruments contained in the variable HJMInstSet.
instdisp(HJMInstSet)
Note that there are eight instruments in this portfolio set: two bonds, one bond option, one fixed rate note, one floating rate note, one cap, one floor, and one swap. Each instrument has a corresponding index that identifies the instrument prices in the price vector returned by hjmprice.
Now use hjmprice to calculate the price of each instrument in the instrument set.
[Price, PriceTree] = hjmprice(HJMTree, HJMInstSet)
Warning: Not all cash flows are aligned with the tree. Result will
be approximated.
Price =
105.7678
107.6773
7.3217
105.7678
100.5768
15.4367
15.3938
5.1910
PriceTree =
FinObj: 'HJMPriceTree'
PBush: {1x5 cell}
AIBush: {1x5 cell}
tObs: [0 1 2 3 4]
| Note The warning shown above appears because some of the cash flows for the second bond do not fall exactly on a tree node. This situation is discussed further in HJM Pricing Options Structure. |
Price Vector
The prices in the vector Price correspond to the prices at observation time zero (tObs = 0), which is defined as the valuation date of the interest rate tree. The instrument indexing within the Price vector is the same as the indexing within InstSet. In this example, the prices in the Price vector correspond to the instruments in the following order.
InstNames = instget(HJMInstSet, 'FieldName','Name') InstNames = 4% bond 4% bond Option 101 4% Fixed 20BP Float 3% Cap 1% Floor 4%/20BP Swap
Consequently, the price of the 3% cap is $15.4367, and the price for the 4% fixed-rate note is $105.7678
Price Tree Structure
The price tree structure holds all the pricing information. The first field of this structure, FinObj, indicates that this structure represents a price tree. The second field, PBush is the tree holding the price of the instruments in each node of the tree. The third field, AIBush is the tree holding the accrued interest of the instruments in each node of the tree. Finally, the fourth field, tObs, represents the observation time of each level of PBush and AIBush, with units in terms of compounding periods.
The function treeviewer can obtain a graphical representation of the tree, allowing you to examine interactively the values on the nodes of the tree.
treeviewer(PriceTree, HJMInstSet)
Alternatively, you can directly examine the field within the PriceTree structure, which contains the price tree with the price vectors at every state. The first node represents tObs = 0, corresponding to the valuation date.
PriceTree.PBush{1}
ans =
105.7678
107.6773
7.3217
105.7678
100.5768
15.4367
15.3938
5.1910
You can also use treeviewer instrument-by-instrument to observe instrument prices. For the first 4% bond in the instrument portfolio, treeviewer indicates a valuation date price of 105.8, the same value obtained by accessing the PriceTree structure directly.
The second node represents the first rate observation time, tObs = 1. This node displays two states, one representing the branch going up and the other one representing the branch going down.
Examine the prices of the node corresponding to the up branch.
PriceTree.PBush{2}(:,:,1)
ans =
124.0039
135.2375
13.5026
124.0039
100.4458
3.8042
30.4092
23.5581
As before, you can use treeviewer, this time to examine the price for the 4% bond on the up branch. treeviewer displays a price of 124 for the first node of the up branch, as expected.
Now examine the corresponding down branch
PriceTree.PBush{2}(:,:,2)
ans =
83.7623
76.3844
1.4337
83.7623
100.3308
27.6867
0.9941
-16.5685
Use treeviewer once again, now to observe the price of the 4% bond on the down branch. The displayed price of 83.76 conforms to the price obtained from direct access of the PriceTree structure. You may continue this process as far along the price tree as you want.
HJM Pricing Options Structure
Default Structure. The HJM pricing Options structure defines how the HJM tree is used to find the price of instruments in the portfolio, and how much additional information is displayed in the command window when the pricing function is called. If this input argument is not specified in the call to hjmprice, a default Options structure is used.
To observe the default structure, use the derivset function without any arguments.
Options = derivset
Options =
Diagnostics: 'off'
Warnings: 'on'
ConstRate: 'on'
As seen, the Options structure is composed of three fields: Diagnostics, Warnings, and ConstRate.
Diagnostics indicates whether additional information is displayed if the HJM tree is modified. The default value for this option is 'off'. If Diagnostics is set to 'on' and ConstRate is set to 'off', the pricing functions display information such as the number of nodes in the last level of the HJM tree generated for pricing purposes.
Warnings indicates whether to display warning messages when the input tree is not adequate for accurately pricing the instruments. The default value for this option is 'on'. If both ConstRate and Warnings are 'on', a warning is displayed if any of the instruments in the input portfolio has a cash flow date between tree dates. If ConstRate is 'off', and Warnings is 'on', a warning is displayed if the tree is modified to match the cash flow dates on the instruments in the portfolio.
ConstRate indicates whether the interest rates should be assumed constant between tree dates. By default this option is 'on', which is not an arbitrage-free assumption. Consequently the pricing functions return an approximate price for instruments featuring cash flows between tree dates. Instruments featuring cash flows only on tree nodes are not affected by this option and return exact (arbitrage-free) prices. When ConstRate is 'off', the HJM pricing function finds the cash flow dates for all instruments in the portfolio. If these cash flows do not align exactly with the tree dates, a new tree is generated and used for pricing. This new tree features the same volatility and initial rate specifications of the input HJM tree but contains tree nodes for each date in which at least one instrument in the portfolio has a cash flow. Keep in mind that the number of nodes in an HJM tree grows exponentially with the number of tree dates. Consequently, setting ConstRate 'off' dramatically increases the memory and CPU demands on the computer.
Customizing the Structure. The Options structure is customized by passing property name/property value pairs to the derivset function.
As an example, consider an Options structure with ConstRate 'off' and Diagonistics 'on'.
Options = derivset('ConstRate', 'off', 'Diagnostics', 'on')
Options =
Diagnostics: 'on'
Warnings: 'on'
ConstRate: 'off'
To obtain the value of a specific property from the Options structure, use derivget.
CR = derivget(Options, 'ConstRate') CR = Off
Note
Use derivset and derivget to construct the Options structure. These
functions are guaranteed to remain unchanged, while the implementation of
the structure itself may be modified in the future.
|
Now observe the effects of setting ConstRate 'off'. Obtain the tree dates from the HJM tree.
TreeDates = [HJMTree.TimeSpec.ValuationDate;... HJMTree.TimeSpec.Maturity] TreeDates = 730486 730852 731217 731582 731947 datedisp(TreeDates) 01-Jan-2000 01-Jan-2001 01-Jan-2002 01-Jan-2003 01-Jan-2004
All instruments in HJMInstSet settle on Jan 1st, 2000, and all have cash flows once a year, with the exception of the second bond, which features a period of 2. This bond has cash flows twice a year, with every other cash flow consequently falling between tree dates. You can extract this bond from the portfolio to compare how its price differs by setting ConstRate to 'on' and 'off'.
BondPort = instselect(HJMInstSet, 'Index', 2); instdisp(BondPort) Index Type CouponRate Settle Maturity Period Basis... 1 Bond 0.04 01-Jan-2000 01-Jan-2004 2 NaN...
First price the bond with ConstRate 'on' (default).
format long
[BondPrice, BondPriceTree] = hjmprice(HJMTree, BondPort)
Warning: Not all cash flows are aligned with the tree. Result will
be approximated.
BondPrice =
1.076773391800875e+002
BondPriceTree =
FinObj: 'HJMPriceTree'
PBush: {1x5 cell}
AIBush: {1x5 cell}
tObs: [0 1 2 3 4]
Now recalculate the price of the bond setting ConstRate 'off'.
OptionsNoCR = derivset('ConstR', 'off')
OptionsNoCR =
Diagnostics: 'off'
Warnings: 'on'
ConstRate: 'off'
[BondPriceNoCR, BondPriceTreeNoCR] = hjmprice(HJMTree,...
BondPort, OptionsNoCR)
Warning: Not all cash flows are aligned with the tree. Rebuilding
tree.
BondPriceNoCR =
1.076912349592409e+002
BondPriceTreeNoCR =
FinObj: 'HJMPriceTree'
PBush: {1x9 cell}
AIBush: {1x9 cell}
tObs: [1x9 double]
As indicated in the last warning, because the cash flows of the bond did not align with the tree dates, a new tree was generated for pricing the bond. This pricing method returns more accurate results since it guarantees that the process is arbitrage-free. It also takes longer to calculate and requires more memory. The tObs field of the price tree structure indicates the increased memory usage. BondPriceTree.tObs has only five elements, while BondPriceTreeNoCR has nine. While this may not seem like a large difference, it has a dramatic effect on the number of states in the last node.
size(BondPriceTree.PBush{end})
ans =
1 8
size(BondPriceTreeNoCR.PBush{end})
ans =
1 128
The differences become more obvious by examining the price trees with treeviewer.
treeviewer(BondPriceTree, BondPort) treeviewer(BondPriceTreeNoCR, BondPort)
| | Using HJM Trees in MATLAB | Calculating Prices and Sensitivities | |
