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 Glossary contains additional definitions.

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. 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 day count convention determines how accrued interest is calculated and determines how cash flows for the bond are discounted, by that means effecting price and yield calculations. Furthermore, the SIA convention is to use the actual/actual day count convention for discounting cash flows in all cases.

**Basis of a Bond**

Basis Value | Meaning | Description |
---|---|---|

| actual/actual | Actual days held over actual days in coupon period. Denominator is 365 in most years and 366 in a leap year. |

| 30/360 (SIA) | Each month contains 30 days; a year contains 360 days. Payments are adjusted for bonds that pay coupons on the last day of February. |

| actual/360 | Actual days held over 360. |

| actual/365 | Actual days held over 365, even in leap years. |

| 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. 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 (International Swap Dealers Association) | Variant of 30/360 with slight differences for calculating number of days in a month. |

| 30E/360 European | Variant of 30/360 used primarily in Europe. |

| actual/365 Japanese | All years contain 365 days. Leap days are ignored. |

| actual/actual (ICMA) | Actual days held over actual days in coupon period. Denominator is 365 in most years and 366 in a leap year. This basis assumes an annual compounding period. |

| actual/360 (ICMA) | Actual days held over 360. This basis assumes an annual compounding period. |

| actual/365 (ICMA) | Actual days held over 365, even in leap years. This basis assumes an annual compounding period. |

| 30/360 (ICMA) | The number of days in every month is set to 30. 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 (ISDA) | This day count fraction is equal to the sum of number of interest accrual days falling with a leap year divided by 366 and the number of interest accrual days not falling within a leap year divided by 365. |

| BUS/252 | The number of business days between the previous coupon
payment and the settlement data divided by 252. BUS/252 business days
are non-weekend, non-holiday days. The |

For more information, see **basis**.

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.

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

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`