Main Content

The Financial Toolbox™ product provides functions for computing accrued interest, price, yield, convexity, and duration of fixed-income securities. Various conventions exist for determining the details of these computations. The Financial Toolbox software supports conventions specified by the Securities Industry and Financial Markets Association (SIFMA), used in the US markets, the International Capital Market Association (ICMA), used mainly in the European markets, and the International Swaps and Derivatives Association (ISDA). For historical reasons, SIFMA is referred to in Financial Toolbox documentation as SIA and ISMA is referred to as International Capital Market Association (ICMA).

Since terminology varies among texts on this subject, here are some basic definitions that apply to these Financial Toolbox functions.

The *settlement date* of a bond is the date when money first changes hands; that is, when a buyer pays for a bond. It need not coincide with the *issue date*, which is the date a bond is first offered for sale.

The *first coupon date* and *last coupon date* are the dates when the first and last coupons are paid, respectively. Although bonds typically pay periodic annual or semiannual coupons, the length of the first and last coupon periods may differ from the standard coupon period. The toolbox includes price and yield functions that handle these odd first and/or last periods.

Successive *quasi-coupon dates* determine the length of the standard coupon period for the fixed income security of interest, and do not necessarily coincide with actual coupon payment dates. The toolbox includes functions that calculate both actual and quasi-coupon dates for bonds with odd first and/or last periods.

Fixed-income securities can be purchased on dates that do not coincide with coupon payment dates. In this case, the bond owner is not entitled to the full value of the coupon for that period. When a bond is purchased between coupon dates, the buyer must compensate the seller for the pro-rata share of the coupon interest earned from the previous coupon payment date. This pro-rata share of the coupon payment is called *accrued interest*. The *purchase price*, the price paid for a bond, is the quoted market price plus accrued interest.

The *maturity date* of a bond is the date when the issuer returns the final face value, also known as the *redemption value* or *par value*, to the buyer. The *yield-to-maturity* of a bond is the nominal compound rate of return that equates the present value of all future cash flows (coupons and principal) to the current market price of the bond.

The *period* of a bond refers to the frequency with which the issuer of a bond makes coupon payments to the holder.

**Period of a Bond **

Period Value | Payment Schedule |
---|---|

| No coupons (Zero coupon bond) |

| Annual |

| Semiannual |

| Tri-annual |

| Quarterly |

| Bi-monthly |

| Monthly |

The *basis* of a bond refers to the basis or day-count convention for a bond. Day count basis determines how interest accrues over time for various instruments and the amount transferred on interest payment dates. Basis is normally expressed as a fraction in which the numerator determines the number of days between two dates, and the denominator determines the number of days in the year.

For example, the numerator of *actual/actual* means that when determining the number of days between two dates, count the actual number of days; the denominator means that you use the actual number of days in the given year in any calculations (either 365 or 366 days depending on whether the given year is a leap year). The calculation of accrued interest for dates between payments also uses day count basis. Day count basis is a fraction of `Number of interest accrual days`

/ `Days in the relevant coupon period`

.

Supported day count conventions and basis values are:

Basis Value | Day Count Convention |
---|---|

| actual/actual (default) — Number of days in both a period and
a year is the actual number of days. Also, another common actual/actual basis
is basis |

| 30/360 SIA — Year fraction is calculated based on a 360 day year with 30-day months, after applying the following rules: If the first date and the second date are the last day of February, the second date is changed to the 30th. If the first date falls on the 31st or is the last day of February, it is changed to the 30th. If after the preceding test, the first day is the 30th and the second day is the 31st, then the second day is changed to the 30th. |

| actual/360 — Number of days in a period is equal to the actual number of days, however the number of days in a year is 360. |

| actual/365 — Number of days in a period is equal to the actual number of days, however the number of days in a year is 365 (even in a leap year). |

| 30/360 PSA — Number of days in every month is set to 30 (including February). If the start date of the period is either the 31st of a month or the last day of February, the start date is set to the 30th, while if the start date is the 30th of a month and the end date is the 31st, the end date is set to the 30th. The number of days in a year is 360. |

| 30/360 ISDA — Number of days in every month is set to 30, except for February where it is the actual number of days. If the start date of the period is the 31st of a month, the start date is set to the 30th while if the start date is the 30th of a month and the end date is the 31st, the end date is set to the 30th. The number of days in a year is 360. |

| 30E /360 — Number of days in every month is set to 30 except for February where it is equal to the actual number of days. If the start date or the end date of the period is the 31st of a month, that date is set to the 30th. The number of days in a year is 360. |

| actual/365 Japanese — Number of days in a period is equal to the actual number of days, except for leap days (29th February) which are ignored. The number of days in a year is 365 (even in a leap year). |

| actual/actual ICMA — Number of days in both a period and a year is the actual number of days and the compounding frequency is annual. |

| actual/360 ICMA — Number of days in a period is equal to the actual number of days, however the number of days in a year is 360 and the compounding frequency is annual. |

| actual/365 ICMA — Number of days in a period is equal to the actual number of days, however the number of days in a year is 365 (even in a leap year) and the compounding frequency is annual. |

| 30/360 ICMA — Number of days in every month is set to 30, except for February where it is equal to the actual number of days. If the start date or the end date of the period is the 31st of a month, that date is set to the 30th. The number of days in a year is 360 and the compounding frequency is annual. |

| actual/365 ISDA — The day count fraction is calculated using
the following formula: |

| bus/252 — The number of days in a period is equal to the actual number of business days. The number of business days in a year is 252. |

**Note**

Although the concept of day count sounds deceptively simple, the actual calculation of day counts can be complex. You can find a good discussion of day counts and the formulas for calculating them in Chapter 5 of Stigum and Robinson, *Money Market and Bond Calculations* in Bibliography.

The *end-of-month rule* affects a bond's coupon payment structure. When the rule is in effect, a security that pays a coupon on the last actual day of a month will always pay coupons on the last day of the month. This means, for example, that a semiannual bond that pays a coupon on February 28 in nonleap years will pay coupons on August 31 in all years and on February 29 in leap years.

**End-of-Month Rule**

End-of-Month Rule Value | Meaning |
---|---|

| Rule in effect. |

| Rule not in effect. |

Although not all Financial Toolbox functions require the same input arguments, they all accept the following common set of input arguments.

**Common Input Arguments**

Input | Meaning |
---|---|

| Settlement date |

| Maturity date |

| Coupon payment period |

| Day-count basis |

| End-of-month payment rule |

| Bond issue date |

| First coupon payment date |

| Last coupon payment date |

Of the common input arguments, only `Settle`

and `Maturity`

are required. All others are optional. They are set to the default values if you do not explicitly set them. By default, the `FirstCouponDate`

and `LastCouponDate`

are nonapplicable. In other words, if you do not specify `FirstCouponDate`

and `LastCouponDate`

, the bond is assumed to have no odd first or last coupon periods. In this case, the bond is a standard bond with a coupon payment structure based solely on the maturity date.

To illustrate the use of default values in Financial Toolbox functions, consider the `cfdates`

function, which computes actual cash flow payment dates for a portfolio of fixed income securities regardless of whether the first and/or last coupon periods are normal, long, or short.

The complete calling syntax with the full input argument list is

CFlowDates = cfdates(Settle, Maturity, Period, Basis, ... EndMonthRule, IssueDate, FirstCouponDate, LastCouponDate)

while the minimal calling syntax requires only settlement and maturity dates

CFlowDates = cfdates(Settle, Maturity)

As an example, suppose that you have a bond with these characteristics:

Settle = '20-Sep-1999' Maturity = '15-Oct-2007' Period = 2 Basis = 0 EndMonthRule = 1 IssueDate = NaN FirstCouponDate = NaN LastCouponDate = NaN

`Period`

, `Basis`

, and `EndMonthRule`

are set to their default values, and `IssueDate`

, `FirstCouponDate`

, and `LastCouponDate`

are set to `NaN`

.

Formally, a `NaN`

is an IEEE^{®} arithmetic standard for *Not-a-Number* and is used to indicate the result of an undefined operation (for example, zero divided by zero). However, `NaN`

is also a convenient placeholder. In the SIA functions of Financial Toolbox software, `NaN`

indicates the presence of a nonapplicable value. It tells the Financial Toolbox functions to ignore the input value and apply the default. Setting `IssueDate`

, `FirstCouponDate`

, and `LastCouponDate`

to `NaN`

in this example tells `cfdates`

to assume that the bond has been issued before settlement and that no odd first or last coupon periods exist.

Having set these values, all these calls to `cfdates`

produce the same result.

cfdates(Settle, Maturity) cfdates(Settle, Maturity, Period) cfdates(Settle, Maturity, Period, []) cfdates(Settle, Maturity, [], Basis) cfdates(Settle, Maturity, [], []) cfdates(Settle, Maturity, Period, [], EndMonthRule) cfdates(Settle, Maturity, Period, [], NaN) cfdates(Settle, Maturity, Period, [], [], IssueDate) cfdates(Settle, Maturity, Period, [], [], IssueDate, [], []) cfdates(Settle, Maturity, Period, [], [], [], [],LastCouponDate) cfdates(Settle, Maturity, Period, Basis, EndMonthRule, ... IssueDate, FirstCouponDate, LastCouponDate)

Thus, leaving a particular input unspecified has the same effect as passing an empty matrix (`[]`

) or passing a `NaN`

– all three tell `cfdates`

(and other Financial Toolbox functions) to use the default value for a particular input parameter.

Since the previous example included only a single bond, there was no difference between passing an empty matrix or passing a `NaN`

for an optional input argument. For a portfolio of bonds, however, using `NaN`

as a placeholder is the only way to specify default acceptance for some bonds while explicitly setting nondefault values for the remaining bonds in the portfolio.

Now suppose that you have a portfolio of two bonds.

Settle = '20-Sep-1999' Maturity = ['15-Oct-2007'; '15-Oct-2010']

These calls to `cfdates`

all set the coupon period to its default value (`Period = 2`

) for both bonds.

cfdates(Settle, Maturity, 2) cfdates(Settle, Maturity, [2 2]) cfdates(Settle, Maturity, []) cfdates(Settle, Maturity, NaN) cfdates(Settle, Maturity, [NaN NaN]) cfdates(Settle, Maturity)

The first two calls explicitly set `Period = 2`

. Since `Maturity`

is a `2`

-by-`1`

vector of maturity dates, `cfdates`

knows that you have a two-bond portfolio.

The first call specifies a single (that is, scalar) 2 for `Period`

. Passing a scalar tells `cfdates`

to apply the scalar-valued input to all bonds in the portfolio. This is an example of implicit scalar-expansion. The settlement date has been implicit scalar-expanded as well.

The second call also applies the default coupon period by explicitly passing a two-element vector of 2's. The third call passes an empty matrix, which `cfdates`

interprets as an invalid period, for which the default value is used. The fourth call is similar, except that a `NaN`

has been passed. The fifth call passes two `NaN`

's, and has the same effect as the third. The last call passes the minimal input set.

Finally, consider the following calls to `cfdates`

for the same two-bond portfolio.

cfdates(Settle, Maturity, [4 NaN]) cfdates(Settle, Maturity, [4 2])

The first call explicitly sets `Period = 4`

for the first bond and implicitly sets the default `Period = 2`

for the second bond. The second call has the same effect as the first but explicitly sets the periodicity for both bonds.

The optional input `Period`

has been used for illustrative purpose only. The default-handling process illustrated in the examples applies to any of the optional input arguments.

Calculating coupon dates, either actual or quasi dates, is notoriously complicated. Financial Toolbox software follows the SIA conventions in coupon date calculations.

The first step in finding the coupon dates associated with a bond is to determine the reference, or synchronization date (the *sync date*). Within the SIA framework, the order of precedence for determining the sync date is:

The first coupon date

The last coupon date

The maturity date

In other words, a Financial Toolbox function first examines the `FirstCouponDate`

input. If `FirstCouponDate`

is specified, coupon payment dates and quasi-coupon dates are computed with respect to `FirstCouponDate`

; if `FirstCouponDate`

is unspecified, empty (`[]`

), or `NaN`

, then the `LastCouponDate`

is examined. If `LastCouponDate`

is specified, coupon payment dates and quasi-coupon dates are computed with respect to `LastCouponDate`

. If both `FirstCouponDate`

and `LastCouponDate`

are unspecified, empty (`[]`

), or `NaN`

, the `Maturity`

(a required input argument) serves as the synchronization date.

There are two yield and time factor conventions that are used in the Financial Toolbox software – these are determined by the input `basis`

. Specifically, bases `0`

to `7`

are assumed to have semiannual compounding, while bases `8`

to `12`

are assumed to have annual compounding regardless of the period of the bond's coupon payments (including zero-coupon bonds). In addition, any yield-related sensitivity (that is, duration and convexity), when quoted on a periodic basis, follows this same convention. (See `bndconvp`

, `bndconvy`

, `bnddurp`

, `bnddury`

, and `bndkrdur`

.)

This example shows how easily you can compute the price of a bond with an odd first period using the function `bndprice`

. Assume that you have a bond with these characteristics:

Settle = '11-Nov-1992'; Maturity = '01-Mar-2005'; IssueDate = '15-Oct-1992'; FirstCouponDate = '01-Mar-1993'; CouponRate = 0.0785; Yield = 0.0625;

Allow coupon payment period (`Period = 2`

), day-count basis (`Basis = 0`

), and end-of-month rule (`EndMonthRule = 1`

) to assume the default values. Also, assume that there is no odd last coupon date and that the face value of the bond is $100. Calling the function

[Price, AccruedInt] = bndprice(Yield, CouponRate, Settle, ... Maturity, [], [], [], IssueDate, FirstCouponDate)

returns a price of $113.60 and accrued interest of $0.59.

Similar functions compute prices with regular payments, odd first and last periods, and prices of Treasury bills and discounted securities such as zero-coupon bonds.

**Note**

`bndprice`

and other functions use nonlinear formulas to compute the price of a security. For this reason, Financial Toolbox software uses Newton's method when solving for an independent variable within a formula. See any elementary numerical methods textbook for the mathematics underlying Newton's method.

To illustrate toolbox yield functions, compute the yield of a bond that has odd first and last periods and settlement in the first period. First set up variables for settlement, maturity date, issue, first coupon, and a last coupon date.

Settle = '12-Jan-2000'; Maturity = '01-Oct-2001'; IssueDate = '01-Jan-2000'; FirstCouponDate = '15-Jan-2000'; LastCouponDate = '15-Apr-2000';

Assume a face value of $100. Specify a purchase price of $95.70, a coupon rate of 4%, quarterly coupon payments, and a 30/360 day-count convention (`Basis = 1`

).

Price = 95.7; CouponRate = 0.04; Period = 4; Basis = 1; EndMonthRule = 1;

Calling the function

Yield = bndyield(Price, CouponRate, Settle, Maturity, Period,... Basis, EndMonthRule, IssueDate, FirstCouponDate, LastCouponDate)

returns

`Yield = 0.0659`

(6.60%).

Financial Toolbox software supports the following options for managing interest-rate risk for one or more bonds:

The toolbox includes functions to perform sensitivity analysis such as convexity and the Macaulay and modified durations for fixed-income securities. The Macaulay duration of an income stream, such as a coupon bond, measures how long, on average, the owner waits before receiving a payment. It is the weighted average of the times payments are made, with the weights at time `T`

equal to the present value of the money received at time `T`

. The modified duration is the Macaulay duration discounted by the per-period interest rate; that is, divided by (1+rate/frequency). The *Macaulay duration* is a measure of price sensitivity to yield changes. This duration is measured in years and is a weighted average-time-to-maturity of an instrument.

To illustrate, the following example computes the annualized Macaulay and modified durations, and the periodic Macaulay duration for a bond with settlement (12-Jan-2000) and maturity (01-Oct-2001) dates as above, a 5% coupon rate, and a 4.5% yield to maturity. For simplicity, any optional input arguments assume default values (that is, semiannual coupons, and day-count `basis`

= 0 (actual/actual), coupon payment structure synchronized to the maturity date, and end-of-month payment rule in effect).

CouponRate = 0.05; Yield = 0.045; [ModDuration, YearDuration, PerDuration] = bnddury(Yield,... CouponRate, Settle, Maturity)

The durations are

ModDuration = 1.6107 (years) YearDuration = 1.6470 (years) PerDuration = 3.2940 (semiannual periods)

Note that the semiannual periodic Macaulay duration (`PerDuratio`

n) is twice the annualized Macaulay duration (`YearDuration`

).

Key rate duration enables you to evaluate the sensitivity and price of a bond to nonparallel changes in the spot or zero curve by decomposing the interest rate risk along the spot or zero curve. Key rate duration refers to the process of choosing a set of key rates and computing a duration for each rate. Specifically, for each key rate, while the other rates are held constant, the key rate is shifted up and down (and intermediate cash flow dates are interpolated), and then the present value of the security given the shifted curves is computed.

The calculation of `bndkrdur`

supports:

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

Where *PV* is the current value of the instrument, *PV_up* and *PV_down* are the new values after the discount curve has been shocked, and *ShiftValue* is the change in interest rate. For example, if key rates of 3 months, 1, 2, 3, 5, 7, 10, 15, 20, 25, 30 years were chosen, then a 30-year bond might have corresponding key rate durations of:

3M | 1Y | 2Y | 3Y | 5Y | 7Y | 10Y | 15Y | 20Y | 25Y | 30Y |

.01 | .04 | .09 | .21 | .4 | .65 | 1.27 | 1.71 | 1.68 | 1.83 | 7.03 |

The key rate durations add up to approximately equal the duration of the bond.

For example, compute the key rate duration of the US Treasury Bond with maturity date of August 15, 2028 and coupon rate of 5.5%.

Settle = datenum('18-Nov-2008'); CouponRate = 5.500/100; Maturity = datenum('15-Aug-2028'); Price = 114.83;

For the `ZeroData`

information on the current spot curve for this bond, refer to https://www.treas.gov/offices/domestic-finance/debt-management/interest-rate/yield.shtml:

```
ZeroDates = daysadd(Settle ,[30 90 180 360 360*2 360*3 360*5 ...
360*7 360*10 360*20 360*30]);
ZeroRates = ([0.06 0.12 0.81 1.08 1.22 1.53 2.32 2.92 3.68 4.42 4.20]/100)';
```

Compute the key rate duration for a specific set of rates (choose this based on the maturities of the available hedging instruments):

`krd = bndkrdur([ZeroDates ZeroRates],CouponRate,Settle,Maturity,'keyrates',[2 5 10 20])`

krd = 0.2865 0.8729 2.6451 8.5778

Note, the sum of the key rate durations approximately equals the duration of the bond:

[sum(krd) bnddurp(Price,CouponRate,Settle,Maturity)]

ans = 12.3823 12.3919

`bndconvp`

| `bndconvy`

| `bnddurp`

| `bnddury`

| `bndkrdur`