Financial Derivatives Toolbox™

optembndbyhjm

Price bonds with embedded options by Heath-Jarrow-Morton interest-rate tree

Syntax

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

Arguments

`HJMTree`	Interest-rate tree structure created by `hjmtree`.
`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` – `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 HJM tree; the bond's argument for Settle date is ignored.

Description

[Price, PriceTree] = optembndbyhjm(HJMTree, CouponRate, Settle,Maturity, OptSpec, Strike, ExerciseDates,'Name1', Value1, 'Name2', Value2, ...) prices bonds with embedded options by an HJM 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.PBush contains the clean prices.
PriceTree.AIBush contains the accrued interest.
PriceTree.tObs contains the observation times.

Examples

Create a HJMTree with the following data:

Rates = [0.05;0.06;0.07];
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', Rates, 'StartDates', ValuationDate, 'EndDates', ...
EndDates, 'Compounding', Compounding, 'ValuationDate', ValuationDate);

Specify a VolSpec:

VolSpec = hjmvolspec('Constant', 0.01);

Specify a TimeSpec:

TimeSpec = hjmtimespec(ValuationDate, EndDates, Compounding);

Build a HJMTree:

HJMTree = hjmtree(VolSpec, RateSpec, TimeSpec);

To compute the price of an American callable bond that pays a 6% annual coupon and matures and is callable on Jan-1-2010:

BondSettlement = 'jan-1-2007';
BondMaturity   = 'jan-1-2010'; 
CouponRate = 0.06;
Period = 1;
OptSpec = 'call'; 
Strike = [98];  
ExerciseDates = '01-Jan-2010'; 
AmericanOpt = 1;

[PriceCallBond,PT] = optembndbyhjm(HJMTree, CouponRate, BondSettlement, BondMaturity,...
OptSpec, Strike, ExerciseDates, 'Period', 1,'AmericanOp',1)

PriceCallBond =

95.9492

PT = 

FinObj: 'HJMPriceTree'
      tObs: [0 1 2 3]
     PBush: {[95.9492]  [1x1x2 double]  [1x2x2 double]  [98 98 98 98]}

optembndbyhjm

Syntax

Arguments

Description

Examples

See Also