bondbyhjm - Price bond from Heath-Jarrow-Morton interest-rate tree

Syntax

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

Input Arguments

`HJMTree`	Forward rate tree structure created by `hjmtree`.
`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`.
`Maturity`	Maturity date. A vector of serial date numbers or date strings.

The Settle date for every bond is set to the ValuationDate of the HJM tree. The bond argument Settle is ignored.

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/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) 13 = BUS/252 For 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, where 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
follow
modifiedfollow
previous
modifiedprevious

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] = bondbyhjm(HJMTree, CouponRate, Settle, Maturity) computes the price of a bond from an HJM forward-rate tree.

[Price, PriceTree] = bondbyhjm(HJMTree, CouponRate, Settle,Maturity, Period, Basis, EndMonthRule, IssueDate,FirstCouponDate, LastCouponDate, StartDate, Face,Options) computes the price of a bond from an HJM forward-rate tree with optional input arguments.

[Price, PriceTree] = bondbyhjm(HJMTree, CouponRate,Settle, Maturity, Name,Value) computes the price of a bond from an HJM forward-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.PBush contains the clean prices.
PriceTree.AIBush contains the accrued interest.
PriceTree.tObs contains the observation times.

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

Definitions

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.

Examples

Price a Bond Using an HJM Tree

Price a 4% bond using an HJM interest-rate tree.

Load deriv.mat, which provides HJMTree. The HJMTree 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-2000';
Maturity = '01-Jan-2004';

Use bondbyhjm to compute the price of the bond.

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

Price =

  97.5280

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 HJM tree using the following market data:

Volatility = [.2; .19; .18; .17];
CurveTerm = [ 1;  2;   3;   4];
HJMTimeSpec = hjmtimespec(ValuationDate, EndDates);
HJMVolSpec = hjmvolspec('Proportional', Volatility, CurveTerm, 1e6);
HJMT = hjmtree(HJMVolSpec,RS,HJMTimeSpec);

Compute the price of the stepped coupon bonds.

PHJM= bondbyhjm(HJMT, CouponRate, Settle,Maturity , Period)

Price a Bond with an Amortization Schedule

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