Main Content

hwprice

Instrument prices from Hull-White interest-rate tree

collapse all in page

Syntax

[Price,PriceTree] = hwprice(HWTree,InstSet)
[Price,PriceTree] = hwprice(___,Options)

Description

[Price,PriceTree] = hwprice(HWTree,InstSet) computes arbitrage-free prices for instruments using an interest-rate tree created with hwtree. All instruments contained in a financial instrument variable, InstSet, are priced.

hwprice handles instrument types: 'Bond', 'CashFlow', 'OptBond', 'OptEmBond', 'OptEmBond', 'OptFloat', 'OptEmFloat', 'Fixed', 'Float', 'Cap', 'Floor', 'RangeFloat', 'Swap'. See instadd to construct defined types.

example

[Price,PriceTree] = hwprice(___,Options) adds an optional input argument for Options.

example

Examples

collapse all

Load the HW tree and instruments from the data file deriv.mat.

load deriv.mat; 
HWSubSet = instselect(HWInstSet,'Type', {'Bond', 'Cap'}); 

instdisp(HWSubSet)
instdisp(HWSubSet)
Index Type CouponRate Settle         Maturity       Period Basis EndMonthRule IssueDate FirstCouponDate LastCouponDate StartDate Face Name    Quantity
1     Bond 0.04       01-Jan-2004    01-Jan-2007    1      0     1            NaN       NaN             NaN            NaN       100  4% bond 20      
2     Bond 0.04       01-Jan-2004    01-Jan-2008    1      0     1            NaN       NaN             NaN            NaN       100  4% bond 15      
 
Index Type Strike Settle         Maturity       CapReset Basis Principal Name   Quantity
3     Cap  0.06   01-Jan-2004    01-Jan-2008    1        0     100       6% Cap 10

Price the cap and bond instruments.

[Price, PriceTree] = hwprice(HWTree, HWSubSet);
100.9188
 99.3296
  0.5837

You can use treeviewer to see the prices of these three instruments along the price tree.

Open Live Script

The data for the interest-rate term structure is as follows: 

Rates = [0.035; 0.042147; 0.047345; 0.052707];
ValuationDate = 'Jan-1-2010';
StartDates = ValuationDate;
EndDates = {'Jan-1-2011'; 'Jan-1-2012'; 'Jan-1-2013'; 'Jan-1-2014'};
Compounding = 1;

Create the RateSpec. 

RS = intenvset('ValuationDate', ValuationDate, 'StartDates', StartDates,...
'EndDates', EndDates,'Rates', Rates, 'Compounding', Compounding)
RS = struct with fields:
           FinObj: 'RateSpec'
      Compounding: 1
             Disc: [4x1 double]
            Rates: [4x1 double]
         EndTimes: [4x1 double]
       StartTimes: [4x1 double]
         EndDates: [4x1 double]
       StartDates: 734139
    ValuationDate: 734139
            Basis: 0
     EndMonthRule: 1

Create a portfolio of stepped coupon bonds with different maturities. 

Settle = '01-Jan-2010';
Maturity = {'01-Jan-2011';'01-Jan-2012';'01-Jan-2013';'01-Jan-2014'};
CouponRate = {{'01-Jan-2011' .042;'01-Jan-2012' .05; '01-Jan-2013' .06; '01-Jan-2014' .07}};

ISet = instbond(CouponRate, Settle, Maturity, 1);
instdisp(ISet)
Index Type CouponRate Settle         Maturity       Period Basis EndMonthRule IssueDate FirstCouponDate LastCouponDate StartDate Face
1     Bond [Cell]     01-Jan-2010    01-Jan-2011    1      0     1            NaN       NaN             NaN            NaN       100 
2     Bond [Cell]     01-Jan-2010    01-Jan-2012    1      0     1            NaN       NaN             NaN            NaN       100 
3     Bond [Cell]     01-Jan-2010    01-Jan-2013    1      0     1            NaN       NaN             NaN            NaN       100 
4     Bond [Cell]     01-Jan-2010    01-Jan-2014    1      0     1            NaN       NaN             NaN            NaN       100

Build the tree with the following data: 

VolDates = ['1-Jan-2011'; '1-Jan-2012'; '1-Jan-2013'; '1-Jan-2014'];
VolCurve = 0.01;
AlphaDates = '01-01-2014';
AlphaCurve = 0.1;

HWVolSpec = hwvolspec(RS.ValuationDate, VolDates, VolCurve,... 
AlphaDates, AlphaCurve);
HWTimeSpec = hwtimespec(RS.ValuationDate, VolDates, Compounding);
HWT = hwtree(HWVolSpec, RS, HWTimeSpec)
HWT = struct with fields:
      FinObj: 'HWFwdTree'
     VolSpec: [1x1 struct]
    TimeSpec: [1x1 struct]
    RateSpec: [1x1 struct]
        tObs: [0 1 2 3]
        dObs: [734139 734504 734869 735235]
      CFlowT: {[4x1 double]  [3x1 double]  [2x1 double]  [4]}
       Probs: {[3x1 double]  [3x3 double]  [3x5 double]}
     Connect: {[2]  [2 3 4]  [2 3 4 5 6]}
     FwdTree: {[1.0350]  [1.0677 1.0494 1.0314]  [1.0953 1.0765 1.0580 1.0398 1.0220]  [1.1264 1.1070 1.0880 1.0694 1.0510 1.0329 1.0152]}

Compute the price of the stepped coupon bonds. 

PHW = hwprice(HWT, ISet)
PHW = 4×1

  100.6763
  100.7368
  100.9266
  101.0115
Open Live Script

The data for the interest-rate term structure is as follows: 

Rates = [0.035; 0.042147; 0.047345; 0.052707];
ValuationDate = 'Jan-1-2010';
StartDates = ValuationDate;
EndDates = {'Jan-1-2011'; 'Jan-1-2012'; 'Jan-1-2013'; 'Jan-1-2014'};
Compounding = 1;

Create a RateSpec. 

RS = intenvset('ValuationDate', ValuationDate, 'StartDates', StartDates,...
'EndDates', EndDates,'Rates', Rates, 'Compounding', Compounding)
RS = struct with fields:
           FinObj: 'RateSpec'
      Compounding: 1
             Disc: [4x1 double]
            Rates: [4x1 double]
         EndTimes: [4x1 double]
       StartTimes: [4x1 double]
         EndDates: [4x1 double]
       StartDates: 734139
    ValuationDate: 734139
            Basis: 0
     EndMonthRule: 1

Create an instrument portfolio of three stepped callable bonds and three stepped vanilla bonds. 

Settle = '01-Jan-2010';
Maturity = {'01-Jan-2012';'01-Jan-2013';'01-Jan-2014'};
CouponRate = {{'01-Jan-2011' .042;'01-Jan-2012' .05; '01-Jan-2013' .06; '01-Jan-2014' .07}};
OptSpec='call';
Strike=100;
ExerciseDates='01-Jan-2011'; %Callable in one year

Bonds with embedded option. 

ISet = instoptembnd(CouponRate, Settle, Maturity, OptSpec, Strike,...
ExerciseDates, 'Period', 1);

Vanilla bonds. 

ISet = instbond(ISet, CouponRate, Settle, Maturity, 1);

Display the instrument portfolio. 

instdisp(ISet)
Index Type      CouponRate Settle         Maturity       OptSpec Strike ExerciseDates  Period Basis EndMonthRule IssueDate FirstCouponDate LastCouponDate StartDate Face AmericanOpt
1     OptEmBond [Cell]     01-Jan-2010    01-Jan-2012    call    100    01-Jan-2011    1      0     1            NaN       NaN             NaN            NaN       100  0          
2     OptEmBond [Cell]     01-Jan-2010    01-Jan-2013    call    100    01-Jan-2011    1      0     1            NaN       NaN             NaN            NaN       100  0          
3     OptEmBond [Cell]     01-Jan-2010    01-Jan-2014    call    100    01-Jan-2011    1      0     1            NaN       NaN             NaN            NaN       100  0          
 
Index Type CouponRate Settle         Maturity       Period Basis EndMonthRule IssueDate FirstCouponDate LastCouponDate StartDate Face
4     Bond [Cell]     01-Jan-2010    01-Jan-2012    1      0     1            NaN       NaN             NaN            NaN       100 
5     Bond [Cell]     01-Jan-2010    01-Jan-2013    1      0     1            NaN       NaN             NaN            NaN       100 
6     Bond [Cell]     01-Jan-2010    01-Jan-2014    1      0     1            NaN       NaN             NaN            NaN       100

Build the tree with the following data: 

VolDates = ['1-Jan-2011'; '1-Jan-2012'; '1-Jan-2013'; '1-Jan-2014'];
VolCurve = 0.01;
AlphaDates = '01-01-2014';
AlphaCurve = 0.1;

HWVolSpec = hwvolspec(RS.ValuationDate, VolDates, VolCurve,... 
AlphaDates, AlphaCurve);
HWTimeSpec = hwtimespec(RS.ValuationDate, VolDates, Compounding);
HWT = hwtree(HWVolSpec, RS, HWTimeSpec)
HWT = struct with fields:
      FinObj: 'HWFwdTree'
     VolSpec: [1x1 struct]
    TimeSpec: [1x1 struct]
    RateSpec: [1x1 struct]
        tObs: [0 1 2 3]
        dObs: [734139 734504 734869 735235]
      CFlowT: {[4x1 double]  [3x1 double]  [2x1 double]  [4]}
       Probs: {[3x1 double]  [3x3 double]  [3x5 double]}
     Connect: {[2]  [2 3 4]  [2 3 4 5 6]}
     FwdTree: {[1.0350]  [1.0677 1.0494 1.0314]  [1.0953 1.0765 1.0580 1.0398 1.0220]  [1.1264 1.1070 1.0880 1.0694 1.0510 1.0329 1.0152]}

Compute the price of the stepped callable bonds and the stepped vanilla bonds. 

PHW = hwprice(HWT, ISet)
PHW = 6×1

  100.4089
  100.2043
  100.0197
  100.7368
  100.9266
  101.0115

The first three rows correspond to the price of the stepped callable bonds and the last three rows correspond to the price of the stepped vanilla bonds.

Open Live Script

The data for the interest-rate term structure is as follows: 

Rates = [0.035; 0.042147; 0.047345; 0.052707];
ValuationDate = 'Jan-1-2011';
StartDates = ValuationDate;
EndDates = {'Jan-1-2012'; 'Jan-1-2013'; 'Jan-1-2014'; 'Jan-1-2015'};
Compounding = 1;

Create a RateSpec. 

RS = intenvset('ValuationDate', ValuationDate, 'StartDates',...
StartDates, 'EndDates', EndDates,'Rates', Rates, 'Compounding', Compounding)
RS = struct with fields:
           FinObj: 'RateSpec'
      Compounding: 1
             Disc: [4x1 double]
            Rates: [4x1 double]
         EndTimes: [4x1 double]
       StartTimes: [4x1 double]
         EndDates: [4x1 double]
       StartDates: 734504
    ValuationDate: 734504
            Basis: 0
     EndMonthRule: 1

Create an instrument portfolio with two range notes and a floating rate note with the following data: 

Spread = 200;
Settle = 'Jan-1-2011';
Maturity = 'Jan-1-2014';

% First Range Note
RateSched(1).Dates = {'Jan-1-2012'; 'Jan-1-2013'  ; 'Jan-1-2014'};
RateSched(1).Rates  = [0.045 0.055; 0.0525  0.0675; 0.06 0.08];

% Second Range Note
RateSched(2).Dates = {'Jan-1-2012'; 'Jan-1-2013' ; 'Jan-1-2014'};
RateSched(2).Rates  = [0.048 0.059; 0.055  0.068 ; 0.07 0.09];

Create InstSet, add a floating-rate note, and display the portfolio instruments. 

InstSet = instadd('RangeFloat', Spread, Settle, Maturity, RateSched);

% Add a floating-rate note
InstSet = instadd(InstSet, 'Float', Spread, Settle, Maturity);

% Display the portfolio instrument
instdisp(InstSet)
Index Type       Spread Settle         Maturity       RateSched FloatReset Basis Principal EndMonthRule
1     RangeFloat 200    01-Jan-2011    01-Jan-2014    [Struct]  1          0     100       1           
2     RangeFloat 200    01-Jan-2011    01-Jan-2014    [Struct]  1          0     100       1           
 
Index Type  Spread Settle         Maturity       FloatReset Basis Principal EndMonthRule CapRate FloorRate
3     Float 200    01-Jan-2011    01-Jan-2014    1          0     100       1            Inf     -Inf

The data to build the tree is as follows: 

VolDates = ['1-Jan-2012'; '1-Jan-2013'; '1-Jan-2014';'1-Jan-2015'];
VolCurve = 0.01;
AlphaDates = '01-01-2015';
AlphaCurve = 0.1;

HWVS = hwvolspec(RS.ValuationDate, VolDates, VolCurve,... 
AlphaDates, AlphaCurve);
HWTS = hwtimespec(RS.ValuationDate, VolDates, Compounding);
HWT = hwtree(HWVS, RS, HWTS)
HWT = struct with fields:
      FinObj: 'HWFwdTree'
     VolSpec: [1x1 struct]
    TimeSpec: [1x1 struct]
    RateSpec: [1x1 struct]
        tObs: [0 1 2 3]
        dObs: [734504 734869 735235 735600]
      CFlowT: {[4x1 double]  [3x1 double]  [2x1 double]  [4]}
       Probs: {[3x1 double]  [3x3 double]  [3x5 double]}
     Connect: {[2]  [2 3 4]  [2 3 4 5 6]}
     FwdTree: {[1.0350]  [1.0677 1.0494 1.0314]  [1.0953 1.0765 1.0580 1.0398 1.0220]  [1.1264 1.1070 1.0880 1.0694 1.0510 1.0329 1.0152]}

Price the portfolio. 

Price = hwprice(HWT, InstSet)
Price = 3×1

   99.3327
   98.1580
  105.5147
Open Live Script

Use instswap to create a float-float swap and price the swap with hwprice. 

RateSpec = intenvset('Rates',.05,'StartDate',today,'EndDate',datemnth(today,60));
IS = instswap([.02 .03],today,datemnth(today,60),[], [], [], [1 1]);
VolSpec = hwvolspec(today,datemnth(today,60),.01,datemnth(today,60),.1);
TimeSpec = hwtimespec(today,cfdates(today,datemnth(today,60),1));
HWTree = hwtree(VolSpec,RateSpec,TimeSpec);
hwprice(HWTree,IS)
ans = 
-4.3220
Open Live Script

Use instswap to create multiple swaps and price the swaps with hwprice. 

RateSpec = intenvset('Rates',.05,'StartDate',today,'EndDate',datemnth(today,60));
IS = instswap([.03 .02],today,datemnth(today,60),[], [], [], [1 1]);
IS = instswap(IS,[200 300],today,datemnth(today,60),[], [], [], [0 0]);
IS = instswap(IS,[.08 300],today,datemnth(today,60),[], [], [], [1 0]);
VolSpec = hwvolspec(today,datemnth(today,60),.01,datemnth(today,60),.1);
TimeSpec = hwtimespec(today,cfdates(today,datemnth(today,60),1));
HWTree = hwtree(VolSpec,RateSpec,TimeSpec);
hwprice(HWTree,IS)
ans = 3×1

    4.3220
   -4.3220
   -0.2701

Input Arguments

collapse all

Interest-rate tree structure, specified by using hwtree.

Data Types: struct

Instrument variable containing a collection of NINST instruments, specified using instadd. Instruments are categorized by type; each type can have different data fields. The stored data field is a row vector or character vector for each instrument.

Data Types: struct

(Optional) Derivatives pricing options structure, created using derivset.

Data Types: struct

Output Arguments

collapse all

Price for each instrument, returned as a NINST-by-1 vector. The prices are computed by backward dynamic programming on the interest-rate tree. If an instrument cannot be priced, a NaN is returned in that entry.

Related single-type pricing functions are:

  • bondbyhw: Price a bond from a Hull-White tree.

  • capbyhw: Price a cap from a Hull-White tree.

  • cfbyhw: Price an arbitrary set of cash flows from a Hull-White tree.

  • fixedbyhw: Price a fixed-rate note from a Hull-White tree.

  • floatbyhw: Price a floating-rate note from a Hull-White tree.

  • floorbyhw: Price a floor from a Hull-White tree.

  • optbndbyhw: Price a bond option from a Hull-White tree.

  • optembndbyhw: Price a bond with embedded option by a Hull-White tree.

  • optfloatbybdt: Price a floating-rate note with an option from a Hull-White tree.

  • optemfloatbybdt: Price a floating-rate note with an embedded option from a Hull-White tree.

  • rangefloatbyhw: Price range floating note using a Hull-White tree.

  • swapbyhw: Price a swap from a Hull-White tree.

  • swaptionbyhw: Price a swaption from a Hull-White tree.

Tree structure of instrument prices, returned as a MATLAB® structure of trees containing vectors of instrument prices and accrued interest, and a vector of observation times for each node. Within PriceTree:

  • PriceTree.PTree contains the clean prices.

  • PriceTree.AITree contains the accrued interest.

  • PriceTree.tObs contains the observation times.

  • PriceTree.Connect contains the connectivity vectors. Each element in the cell array describes how nodes in that level connect to the next. For a given tree level, there are NumNodes elements in the vector, and they contain the index of the node at the next level that the middle branch connects to. Subtracting 1 from that value indicates where the up-branch connects to, and adding 1 indicated where the down branch connects to.

  • PriceTree.Probs contains the probability arrays. Each element of the cell array contains the up, middle, and down transition probabilities for each node of the level.

Version History

Introduced before R2006a

See Also

| | | |

Topics