Financial Derivatives Toolbox™

optembndbybk

Price bonds with embedded options by Black-Karasinski interest-rate tree

Syntax

[Price, PriceTree] = optembndybk(BKTree, CouponRate, Settle, Maturity, OptSpec, Strike, Strike, ExerciseDates, 'Name1', Value1, 'Name2', Value2, ...)

Arguments

`BKTree`	Interest-rate tree structure created by `bktree`.
`CouponRate`	`NINST`-by-`1` matrix for the decimal annual rate.
`Settle`	`NINST`-by-`1` matrix for the settlement date. A vector of serial date numbers or date strings. `Settle` must be earlier than `Maturity`.
`Maturity`	`NINST`-by-`1` matrix for the maturity date. A vector of serial date numbers or date strings.
`OptSpec`	`NINST`-by-`1` cell array of strings `'call'` or `'put`'.
`Strike`	`NINST`-by-`NSTRIKES` of strike price values.
`ExerciseDates`	`NINST`-by-`NSTRIKES` or `NINST`-by-`2` matrix for exercise callable/puttable dates.
`'Name1', Value1, 'Name2', Value2 ...`	(Optional) The name/value pairs are a variable length list of parameters. All optional inputs are specified as matching parameter name/value pairs. The parameter name is specified as a character string, followed by the corresponding parameter value. Parameter name/value pairs may be specified in any order; names are case insensitive and partial string matches are allowed provided no ambiguities exist. Valid parameter names are as follows: `AmericanOpt` is a `NINST`-by-`1` matrix for flags options: `0` (European/Bermuda) or `1` (American). Default is `0`. `Period` is a `NINST`-by-`1` matrix for coupons per year. Default is `2`. `Basis` is a day-count basis of the instrument. `Basis` is a vector of integers with the following supported values: 0 = actual/actual (default) 1 = 30/360 (SIA) 2 = actual/360 3 = actual/365 4 = 30/360 (PSA) 5 = 30/360 (ISDA) 6 = 30/360 (European) 7 = actual/365 (Japanese) 8 = actual/actual (ISMA) 9 = actual/360 (ISMA) 10 = actual/365 (ISMA) 11 = 30/360E (ISMA) 12 = actual/365 (ISDA) `EndMonthRule` is a `NINST`-by-`1` matrix for the end-of-month rule. This rule applies only when `Maturity` is an end-of-month date for a month having 30 or fewer days. When the value is `0`, the end-of-month rule is ignored, meaning that a bond's coupon payment date is always the same numerical day of the month. When the value is `1`, the end-of-month rule is set on (default), meaning that a bond's coupon payment date is always the last actual day of the month. `IssueDate` is a `NINST`-by-`1` matrix for the bond issue date. `FirstCouponDate` is a `NINST`-by-`1` matrix for an irregular first coupon date. Date when a bond makes its first coupon payment. When `FirstCouponDate` and `LastCouponDate` are both specified, `FirstCouponDate` takes precedence in determining the coupon payment structure. `LastCouponDate` is a `NINST`-by-`1` matrix for an irregular last coupon date. Last coupon date of a bond before the maturity date. In the absence of a specified `FirstCouponDate`, a specified `LastCouponDate` determines the coupon structure of the bond. The coupon structure of a bond is truncated at the `LastCouponDate` regardless of where it falls and will be followed only by the bond's maturity cash flow date. `StartDate` is a `NINST`-by-`1` matrix (reserved input argument, currently unused) for date when a bond actually starts (the date from which a bond's cash flows can be considered). To make an instrument forward starting, specify this date as a future date. If `StartDate` is not explicitly specified, the effective start date is the settlement date. `Face` is a `NINST`-by-`1` matrix for the face value. The default value is `100`. `Options` is a derivatives pricing options structure created with `derivset`.

Note The Settle date for every bond with embedded option is set to the ValuationDate of the BK tree; the bond's argument for Settle date is ignored.

Description

[Price, PriceTree] = optembndybk(BKTree, CouponRate,Settle, Maturity, OptSpec, Strike, Strike, ExerciseDates,'Name1', Value1, 'Name2', Value2, ...) prices bonds with embedded options by a BK interest-rate tree.

Price is a number of instruments (NINST)-by-1 matrix of expected prices at time 0.

PriceTree is a 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.

Examples

Create a BKTree with the following data:

ZeroRates = [ 0.035;0.04;0.045];
Compounding = 1;
StartDates = ['jan-1-2007';'jan-1-2008';'jan-1-2009'];
EndDates   = ['jan-1-2008';'jan-1-2009';'jan-1-2010'];
ValuationDate = 'jan-1-2007';

Create a RateSpec:

RateSpec = intenvset('Rates', ZeroRates, 'StartDates', ValuationDate, 'EndDates', ...
EndDates, 'Compounding', Compounding, 'ValuationDate', ValuationDate);

Specify a TimeSpec:

BKTimeSpec = bktimespec(ValuationDate, EndDates, Compounding);

Specify a VolSpec:

VolDates = ['jan-1-2008';'jan-1-2009';'jan-1-2010'];
VolCurve = 0.01;
AlphaDates = 'jan-1-2010';
AlphaCurve = 0.1;
BKVolSpec = bkvolspec(ValuationDate, VolDates, VolCurve, AlphaDates, AlphaCurve);

Build a BKTree:

BKTree = bktree(BKVolSpec, RateSpec, BKTimeSpec);

To compute the price of an American puttable bond that pays an annual coupon of 5.25% , matures in Jan-1-2010, and is callable on Jan-1-2008 and 01-Jan-2010:

BondSettlement = 'jan-1-2007';
BondMaturity   = 'jan-1-2010'; 
CouponRate = 0.0525;
Period = 1;
OptSpec = 'put'; 
Strike = [100];  
ExerciseDates = {'jan-1-2008' '01-Jan-2010'}; 
AmericanOpt = 1;

PricePutBondBK = optembndbybk(BKTree, CouponRate, BondSettlement, BondMaturity,...
OptSpec, Strike, ExerciseDates,'Period', 1, 'AmericanOpt', 1)

PricePutBondBK =

102.3820

optembndbybk

Syntax

Arguments

Description

Examples

See Also