bndkrdur

Bond key rate duration given zero curve

Syntax

KeyRateDuration = bndkrdur(ZeroData,CouponRate,Settle,Maturity)

KeyRateDuration = bndkrdur(___,Name,Value)

Description

KeyRateDuration = bndkrdur(ZeroData,CouponRate,Settle,Maturity) computes the key rate durations for one or more bonds given a zero curve and a set of key rates.

KeyRateDuration = bndkrdur(___,Name,Value) adds optional name-value pair arguments.

Examples

Find the Bond Key Rate Duration Given the Zero Curve

This example shows how to compute the key rate duration of a bond for key rate times of 2, 5, 10, and 30 years.

ZeroRates = [0.0476 .0466 .0465 .0468 .0473 .0478 ...
.0493 .0539 .0572 .0553 .0530]';

ZeroDates = daysadd('31-Dec-1998',[30 360 360*2 360*3 360*5 ...
360*7 360*10 360*15 360*20 360*25 360*30],1);

ZeroData = [ZeroDates ZeroRates];

krdur = bndkrdur(ZeroData,.0525,'12/31/1998',...
'11/15/2028','KeyRates',[2 5 10 30])

krdur = 1×4

    0.2986    0.8791    4.1353    9.5814

Find the Bond Key Rate Duration Given the Zero Curve Using datetime Inputs

This example shows how to use datetime inputs for Settle and Maturity and also use a table for ZeroData to compute the key rate duration of a bond for key rate times of 2, 5, 10, and 30 years.

ZeroRates = [0.0476 .0466 .0465 .0468 .0473 .0478 ...
.0493 .0539 .0572 .0553 .0530]';

ZeroDates = daysadd('31-Dec-1998',[30 360 360*2 360*3 360*5 ...
360*7 360*10 360*15 360*20 360*25 360*30],1);

ZeroData = table(datetime(ZeroDates,'ConvertFrom','datenum','Locale','en_US'), ZeroRates);

krdur = bndkrdur(ZeroData,.0525,datetime('12/31/1998','Locale','en_US'),...
datetime('11/15/2028','Locale','en_US'),'KeyRates',[2 5 10 30])

krdur = 1×4

    0.2986    0.8791    4.1353    9.5814

Input Arguments

ZeroData — Zero curve

matrix | table

Zero Curve, specified as a numRates-by-2 matrix or a numRates-by-2 table.

If ZeroData is represented as a numRates-by-2 matrix, the first column is a MATLAB^® serial date number and the second column is the accompanying zero rates.

If ZeroData is a table, the first column can be a datetime array, string array, or date character vectors. The second column must be numeric data corresponding to the zero rates.

Data Types: double | datetime | char | string | table

CouponRate — Annual percentage rate used to determine coupons payable on a bond

decimal

Annual percentage rate used to determine the coupons payable on a bond, specified as decimal value using a scalar or a NUMBONDS-by-1 vector.

Data Types: double

Settle — Settlement date for all bonds and zero curve

datetime scalar | string scalar | date character vector

Settlement date for all bonds and zero curve, specified as a scalar datetime, string, or date character vector. Settle must be the same settlement date for all the bonds and the zero curve.

To support existing code, bndkrdur also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | datetime

Maturity — Maturity date for bonds

datetime array | string array | date character vector

Maturity date for bonds, specified as a scalar or a NUMBONDS-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, bndkrdur also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | datetime

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: KeyRateDuration = bndkrdur(ZeroData,.0525,'12/31/1998','11/15/2028','KeyRates',[2 5 10 30])

InterpMethod — Interpolation method used to obtain points from zero curve

'linear' (default) | 'cubic', 'pchip'

Interpolation method used to obtain points from the zero curve, specified as the comma-separated pair consisting of 'InterpMethod' and a character vector using one of the following values:

• 'linear' (default)

• 'cubic'

• 'pchip'

Data Types: char

ShiftValue — Value that zero curve is shifted up and down to compute duration

.01 (100 basis points) (default) | numeric

Value that zero curve is shifted up and down to compute duration, specified as the comma-separated pair consisting of 'ShiftValue' and a scalar numeric value.

Data Types: double

KeyRates — Rates to perform the duration calculation

set to each of the zero dates (default) | numeric

Rates to perform the duration calculation, specified as the comma-separated pair consisting of 'KeyRates' and a time to maturity using a scalar or a NUMBONDS-by-1 vector.

Data Types: double

CurveCompounding — Compounding frequency of curve

2 (default) | integer with value of 1, 2, 3, 4, 6, or 12

Compounding frequency of the curve, specified as the comma-separated pair consisting of 'CurveCompounding' and a scalar using one of the following values:

• 1 — Annual compounding

• 2 — Semiannual compounding

• 3 — Compounding three times per year

• 4 — Quarterly compounding

• 6 — Bimonthly compounding

• 12 — Monthly compounding

.

Data Types: double

CurveBasis — Basis of the curve

0 (default) | numeric values: 0,1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13

Basis of the curve, specified as the comma-separated pair consisting of 'CurveBasis' and a scalar using one of the following values:

• 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 (ICMA)

• 9 = actual/360 (ICMA)

• 10 = actual/365 (ICMA)

• 11 = 30/360E (ICMA)

• 12 = actual/365 (ISDA)

• 13 = BUS/252

For more information, see Basis.

Data Types: double

Period — Number of coupon payments per year

2 (default) | numeric with values 0, 1, 2, 3, 4, 6 or 12

Number of coupon payments per year, specified as the comma-separated pair consisting of 'Period' and a scalar or a NUMBONDS-by-1 vector using the values: 0, 1, 2, 3, 4, 6, or 12.

Data Types: double

Basis — Day-count basis of instrument

0 (default) | numeric values: 0,1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13

Day-count of the instrument, specified as the comma-separated pair consisting of 'Basis' and a scalar or a NUMBONDS-by-1 vector using a supported value:

• 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 (ICMA)

• 9 = actual/360 (ICMA)

• 10 = actual/365 (ICMA)

• 11 = 30/360E (ICMA)

• 12 = actual/365 (ISDA)

• 13 = BUS/252

For more information, see Basis.

Data Types: double

EndMonthRule — End-of-month rule flag

1 (in effect) (default) | nonnegative integer 0 or 1

End-of-month rule flag, specified as the comma-separated pair consisting of 'EndMonthRule' and a scalar or a NUMBONDS-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.

Data Types: logical

IssueDate — Bond issue date

datetime array | string array | date character vector

Bond Issue date, specified as the comma-separated pair consisting of 'IssueDate' and a scalar or a NUMBONDS-by-1 vector using a datetime array, string array, or date character vectors.

If you do not specify an IssueDate, the cash flow payment dates are determined from other inputs.

To support existing code, bndkrdur also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | datetime

FirstCouponDate — Irregular or normal first coupon date

datetime array | string array | date character vector

Irregular or normal first coupon date, specified as the comma-separated pair consisting of 'FirstCouponDate' and a scalar or a NUMBONDS-by-1 vector using a datetime array, string array, or date character vectors.

If you do not specify a FirstCouponDate, the cash flow payment dates are determined from other inputs.

To support existing code, bndkrdur also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | datetime

LastCouponDate — Irregular or normal last coupon date

datetime array | string array | date character vector

Irregular or normal last coupon date, specified as the comma-separated pair consisting of 'LastCouponDate' and a scalar or a NUMBONDS-by-1 vector using a datetime array, string array, or date character vectors.

If you do not specify a LastCouponDate, the cash flow payment dates are determined from other inputs.

To support existing code, bndkrdur also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | datetime

StartDate — Forward starting date of payments

datetime array | string array | date character vector

Forward starting date of payments, specified as the comma-separated pair consisting of 'StartDate' and a scalar or a NUMBONDS-by-1 vector using a datetime array, string array, or date character vectors. The StartDate is 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 a StartDate, the effective start date is the Settle date.

To support existing code, bndkrdur also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | datetime

Face — Face value of bond

100 (default) | numeric

Face value of the bond, specified as the comma-separated pair consisting of 'Face' and a scalar or a NUMBONDS-by-1 vector.

Data Types: double

Output Arguments

KeyRateDuration — Key rate durations

matrix

Key rate durations, returned as a numBonds-by-numRates matrix.

Algorithms

bndkrdur computes the key rate durations for one or more bonds given a zero curve and a set of key rates. By default, the key rates are each of the zero curve rates. For each key rate, the duration is computed by shifting the zero curve up and down by a specified amount (ShiftValue) at that particular key rate, computing the present value of the bond in each case with the new zero curves, and then evaluating the following:

$$krdu{r}_i=\frac{(P{V}_{down}-P{V}_{up})}{(PV\times ShiftValue\times 2)}$$

Note

The shift to the curve is computed by shifting the particular key rate by the ShiftValue and then interpolating the values of the curve in the interval between the previous and next key rates. For the first key rate, any curve values before the date are equal to the ShiftValue; likewise, for the last key rate, any curve values after the date are equal to the ShiftValue.

References

[1] Golub, B., Tilman, L. Risk Management: Approaches for Fixed Income Markets. Wiley, 2000.

[2] Tuckman, B. Fixed Income Securities: Tools for Today's Markets. Wiley, 2002.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although bndkrdur supports serial date numbers, datetime values are recommended instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

To convert serial date numbers or text to datetime values, use the datetime function. For example:

t = datetime(738427.656845093,"ConvertFrom","datenum");
y = year(t)

y =

        2021

There are no plans to remove support for serial date number inputs.