Accelerating the pace of engineering and science

bondbybk

Price bond from Black-Karasinski interest-rate tree

Syntax

[Price, PriceTree] = bondbybk(BKTree, CouponRate,
Settle, Maturity)
[Price, PriceTree] = bondbybk(BKTree, CouponRate,
Settle, Maturity, Period, Basis, EndMonthRule, IssueDate,
FirstCouponDate, LastCouponDate, StartDate, Face,
Options)
[Price, PriceTree] = bondbybk(BKTree, CouponRate,
Settle, Maturity, Name,Value)

Input Arguments

 BKTree Forward rate tree structure created by bktree. CouponRate Decimal annual rate. CouponRate is a NINST-by-1 vector or NINST-by-1 cell array of decimal annual rates, or decimal annual rate schedules. For the latter case of a variable coupon schedule, each element of the cell array is a NumDates-by-2 cell array, where the first column is dates and the second column is its associated rate. The date indicates the last day that the coupon rate is valid. Settle Settlement date. A vector of serial date numbers or date strings. Settle must be earlier than Maturity. The Settle date for every bond is set to the ValuationDate of the BK Tree. The bond argument, Settle, is ignored. Maturity Maturity date. A vector of serial date numbers or date strings.

Ordered Input or Name-Value Pair Arguments

Enter the following optional inputs using an ordered syntax or as name-value pair arguments. You cannot mix ordered syntax with name-value pair arguments.

 Period Coupons per year of the bond. A vector of integers. Values are 1, 2, 3, 4, 6, and 12. Default: 2 Basis Day-count basis of the instrument. A vector of integers. 0 = actual/actual 1 = 30/360 (SIA)2 = actual/3603 = actual/3654 = 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)13 = BUS/252For more information, see basis. Default: 0 (actual/actual) EndMonthRule End-of-month rule. A NINST-by-1 vector. This rule applies only when Maturity is an end-of-month date for a month having 30 or fewer days.0 = Ignore rule, meaning that a bond coupon payment date is always the same numerical day of the month.1 = Set rule on, meaning that a bond coupon payment date is always the last actual day of the month. Default: 1 IssueDate Date when a bond was issued. FirstCouponDateDate Date when a bond makes its first coupon payment; used when bond has an irregular first coupon period. When FirstCouponDate and LastCouponDate are both specified, FirstCouponDate takes precedence in determining the coupon payment structure. If you do not specify a FirstCouponDate, the cash flow payment dates are determined from other inputs. LastCouponDateDate Last coupon date of a bond before the maturity date; used when bond has an irregular last coupon period. 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 is followed only by the bond's maturity cash flow date. If you do not specify a LastCouponDate, the cash flow payment dates are determined from other inputs. StartDate Date when a bond actually starts (the date from which a bond cash flow is considered). To make an instrument forward-starting, specify this date as a future date. If you do not specify StartDate, the effective start date is the Settle date. Face Face or par value. Face is a NINST-by-1 vector or NINST-by-1 cell array of face values, or face value schedules. For the latter case, each element of the cell array is a NumDates-by-2 cell array, where the first column is dates and the second column is its associated face value. The date indicates the last day that the face value is valid. Default: 100 Options Derivatives pricing options structure created with derivset.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

 AdjustCashFlowsBasis Adjust the cash flows based on the actual period day count. NINST-by-1 of logicals. Default: false BusinessDayConvention Require payment dates to be business dates. NINST-by-1 cell array with possible choices of business day convention:actual followmodifiedfollowpreviousmodifiedprevious Default: actual Holidays Holidays used for business day convention. NHOLIDAYS-by-1 of MATLAB® date numbers. Default: If no dates are specified, holidays.m is used.

Description

[Price, PriceTree] = bondbybk(BKTree, CouponRate,
Settle, Maturity)
computes the price of a bond from a Black-Karasinski interest-rate tree.

[Price, PriceTree] = bondbybk(BKTree, CouponRate,
Settle, Maturity, Period, Basis, EndMonthRule, IssueDate,
FirstCouponDate, LastCouponDate, StartDate, Face,
Options)
computes the price of a bond from a Black-Karasinski interest-rate tree using optional input arguments.

[Price, PriceTree] = bondbybk(BKTree, CouponRate,
Settle, Maturity, Name,Value)
computes the price of a bond from a Black-Karasinski interest-rate tree with additional options specified by one or more Name,Value pair arguments.

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.

bondbybk computes prices of vanilla bonds, stepped coupon bonds, and amortizing bonds with no market purchase option and no call provisions.

Examples

expand all

Price a Bond Using a BK Tree

Price a 4% bond using a Black-Karasinski interest-rate tree.

Load deriv.mat, which provides BKTree. The BKTree structure contains the time and interest-rate information needed to price the bond.

```load deriv.mat;
```

Define the bond using the required arguments. Other arguments use defaults.

```CouponRate = 0.04;
Settle = '01-Jan-2004';
Maturity = '31-Dec-2008';
```

Use bondbybk to compute the price of the bond.

```Price = bondbybk(BKTree, CouponRate, Settle, Maturity)
```
```Warning: Not all cash flows are aligned with the tree. Result will be
approximated.

Price =

98.0300

```

Price a Stepped Coupon Bond

Price single stepped coupon bonds using market data.

Define the interest-rate term structure.

```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 =

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 the stepped bond instrument.

```Settle = '01-Jan-2010';
Maturity = {'01-Jan-2011';'01-Jan-2012';'01-Jan-2013';'01-Jan-2014'};
CouponRate = {{'01-Jan-2012' .0425;'01-Jan-2014' .0750}};
Period = 1;
```

Build the BK tree using the following market data:

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

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

Compute the price of the stepped coupon bonds.

```PBK= bondbybk(BKT, CouponRate, Settle,Maturity , Period)
```
```PBK =

100.7246
100.0945
101.5900
102.0820

```

Price a Bond with an Amortization Schedule

Price a bond with an amortization schedule using the Face input argument to define the schedule.

Define the interest-rate term structure.

```Rates = 0.065;
ValuationDate = '1-Jan-2011';
StartDates = ValuationDate;
EndDates=  '1-Jan-2017';
Compounding = 1;
```

Create the RateSpec.

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

FinObj: 'RateSpec'
Compounding: 1
Disc: 0.6853
Rates: 0.0650
EndTimes: 6
StartTimes: 0
EndDates: 736696
StartDates: 734504
ValuationDate: 734504
Basis: 0
EndMonthRule: 1

```

Create the bond instrument. The bond has a coupon rate of 7%, a period of one year, and matures on 1-Jan-2017.

```CouponRate = 0.07;
Settle ='1-Jan-2011';
Maturity = '1-Jan-2017';
Period = 1;
Face = {{'1-Jan-2015' 100;'1-Jan-2016' 90;'1-Jan-2017' 80}};
```

Build the BK tree with the following market data:

```VolDates = ['1-Jan-2012'; '1-Jan-2013';...
'1-Jan-2014';'1-Jan-2015';'1-Jan-2016';'1-Jan-2017'];
VolCurve = 0.01;
AlphaCurve = 0.1;

BKVolSpec = bkvolspec(RateSpec.ValuationDate, VolDates, VolCurve,...
BKTimeSpec = bktimespec(RateSpec.ValuationDate, VolDates, Compounding);
BKT = bktree(BKVolSpec, RateSpec, BKTimeSpec);
```

Compute the price of the amortizing bond.

```Price = bondbybk(BKT, CouponRate, Settle, Maturity, 'Period', Period,...
'Face', Face)
```
```Price =

102.3155

```

Compare the results with price of a vanilla bond.

```PriceVanilla = bondbybk(BKT, CouponRate, Settle, Maturity, Period)
```
```PriceVanilla =

102.4205

```

expand all

Vanilla Bond

A vanilla coupon bond is a security representing an obligation to repay a borrowed amount at a designated time and to make periodic interest payments until that time. The issuer of a bond makes the periodic interest payments until the bond matures. At maturity, the issuer pays to the holder of the bond the principal amount owed (face value) and the last interest payment.

Stepped Coupon Bond

A step-up and step-down bond is a debt security with a predetermined coupon structure over time. With these instruments, coupons increase (step up) or decrease (step down) at specific times during the life of the bond.

Bond with an Amortization Schedule

An amortized bond is treated as an asset, with the discount amount being amortized to interest expense over the life of the bond.