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). Financial Instruments Toolbox™supports additional functionality for pricing fixed-income securities. For more information, see Price Interest-Rate Instruments (Financial Instruments Toolbox).

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)

Price = 113.5977 AccruedInt = 0.5855

`bndprice`

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

function

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

Yield = 0.0659

The function returns a `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; Settle = '12-Jan-2000'; Maturity = '01-Oct-2001'; [ModDuration, YearDuration, PerDuration] = bnddury(Yield,... CouponRate, Settle, Maturity)

ModDuration = 1.6107 YearDuration = 1.6470 PerDuration = 3.2940

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.treasury.gov/resource-center/data-chart-center/interest-rates/Pages/TextView.aspx?data=yield:

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