bkprice

Instrument prices from Black-Karasinski interest-rate tree

Syntax

[Price,PriceTree] = bkprice(BKTree,InstSet)

[Price,PriceTree] = bkprice(___,Options)

Description

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

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

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

Examples

Price Cap and Bond Instruments in the Instrument Set

Load the BK tree and instruments from the data file deriv.mat. Price the cap and bond instruments contained in the instrument set.

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

instdisp(BKSubSet)

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

[Price, PriceTree] = bkprice(BKTree, BKSubSet)

Price = 3×1

   98.1096
   95.6734
    2.2706

PriceTree = struct with fields:
     FinObj: 'BKPriceTree'
      PTree: {1x5 cell}
     AITree: {1x5 cell}
       tObs: [0 1 2 3 4]
    Connect: {[2]  [2 3 4]  [2 2 3 4 4]}
      Probs: {[3x1 double]  [3x3 double]  [3x5 double]}

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

Price Multi-Stepped Coupon Bonds

Price the following multi-stepped coupon bonds using the following data:

% 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 RateSpec
RS = intenvset('ValuationDate', ValuationDate, 'StartDates', StartDates,...
'EndDates', EndDates,'Rates', Rates, 'Compounding', Compounding);

% 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 BKTree 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;

BKVolSpec = bkvolspec(RS.ValuationDate, VolDates, VolCurve,... 
AlphaDates, AlphaCurve);
BKTimeSpec = bktimespec(RS.ValuationDate, VolDates, Compounding);
BKT = bktree(BKVolSpec, RS, BKTimeSpec);

Compute the price of the stepped coupon bonds.

PBK = bkprice(BKT, ISet)

PBK = 4×1

  100.6763
  100.7368
  100.9266
  101.0115

Price a Portfolio of Stepped Callable Bonds and Stepped Vanilla Bonds

Price a portfolio of stepped callable bonds and stepped vanilla bonds using the following data:

% 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 RateSpec
RS = intenvset('ValuationDate', ValuationDate, 'StartDates', StartDates,...
'EndDates', EndDates,'Rates', Rates, 'Compounding', Compounding);

% Create an instrument portfolio of 3 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 BKTree 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;

BKVolSpec = bkvolspec(RS.ValuationDate, VolDates, VolCurve,... 
AlphaDates, AlphaCurve);
BKTimeSpec = bktimespec(RS.ValuationDate, VolDates, Compounding);
BKT = bktree(BKVolSpec, RS, BKTimeSpec);

Compute the price, where the first three rows of the output corresponds to the price of the stepped callable bonds and the last three rows corresponds to the price of the stepped vanilla bonds.

PBK = bkprice(BKT, ISet)

PBK = 6×1

  100.6729
  100.6763
  100.6763
  100.7368
  100.9266
  101.0115

Price a Portfolio of Range Notes and Floating-Rate Notes

Price a portfolio of range notes and floating-rate notes using the following data:

% 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 RateSpec
RS = intenvset('ValuationDate', ValuationDate, 'StartDates',...
StartDates, 'EndDates', EndDates,'Rates', Rates, 'Compounding', Compounding);

% 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
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     
 

Build the BKTree with the following data:

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

BKVS = bkvolspec(RS.ValuationDate, VolDates, VolCurve,... 
AlphaDates, AlphaCurve);
BKTS = bktimespec(RS.ValuationDate, VolDates, Compounding);
BKT = bktree(BKVS, RS, BKTS);

Price the portfolio.

Price = bkprice(BKT, InstSet)

Price = 3×1

  105.5147
  101.4805
  105.5147

Input Arguments

BKTree — Interest-rate tree structure

structure

Interest-rate tree structure, specified by using bktree.

Data Types: struct

InstSet — Instrument variable

structure

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

Options — Derivatives pricing options structure

structure

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

Data Types: struct

Output Arguments

Price — Price for each instrument at time 0

vector

Price for each instrument at time 0, 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:

• bondbybk — Price a bond from a Black-Karasinski tree.

• capbybk — Price a cap from a Black-Karasinski tree.

• cfbybk — Price an arbitrary set of cash flows from a Black-Karasinski tree.

• fixedbybk — Price a fixed-rate note from a Black-Karasinski tree.

• floatbybk — Price a floating-rate note from a Black-Karasinski tree.

• floorbybk — Price a floor from a Black-Karasinski tree.

• optbndbybk — Price a bond option from a Black-Karasinski tree.

• optembndbybk — Price a bond with embedded option by a Black-Karasinski tree.

• optfloatbybk — Price a floating-rate note with an option from a Black-Karasinski tree.

• optemfloatbybk — Price a floating-rate note with an embedded option from a Black-Karasinski tree.

• rangefloatbybk — Price range floating note from a Black-Karasinski tree.

• swapbybk — Price a swap from a Black-Karasinski tree.

• swaptionbybk — Price a swaption from a Black-Karasinski tree.

PriceTree — Tree structure of instrument prices

structure

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.