Documentation |
On this page… |
---|
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). Note that for historical reasons, SIFMA is referred to in Financial Toolbox documentation as SIA and ICMA is referred to as International Securities Market Association (ISMA).
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 actually 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 |
---|---|
0 | No coupons (Zero coupon bond) |
1 | Annual |
2 | Semiannual |
3 | Tri-annual |
4 | Quarterly |
6 | Bi-monthly |
12 | 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, thereby 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 |
---|---|---|
0 (default) | actual/actual | Actual days held over actual days in coupon period. Denominator is 365 in most years and 366 in a leap year. |
1 | 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. |
2 | actual/360 | Actual days held over 360. |
3 | actual/365 | Actual days held over 365, even in leap years. |
4 | 30/360 BMA (Bond Market Association) | Each month contains 30 days; a year contains 360 days. If the last date of the period is the last day of February, the month is extended to 30 days. |
5 | 30/360 ISDA (International Swap Dealers Association) | Variant of 30/360 with slight differences for calculating number of days in a month. |
6 | 30/360 European | Variant of 30/360 used primarily in Europe. |
7 | actual/365 Japanese | All years contain 365 days. Leap days are ignored. |
8 | 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. |
9 | actual/360 (ICMA) | Actual days held over 360. This basis assumes an annual compounding period. |
10 | actual/365 (ICMA) | Actual days held over 365, even in leap years. This basis assumes an annual compounding period. |
11 | 30/360E (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. |
12 | 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. |
13 | 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 holidays.m file defines holidays. |
Note Although the concept of day count sounds deceptively simple, the actual calculation of day counts can be quite 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 |
---|---|
1 (default) | Rule in effect. |
0 | 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 |
---|---|
Settle | Settlement date |
Maturity | Maturity date |
Period | Coupon payment period |
Basis | Day-count basis |
EndMonthRule | End-of-month payment rule |
IssueDate | Bond issue date |
FirstCouponDate | First coupon payment date |
LastCouponDate | Last coupon payment date |
Of the common input arguments, only Settle and Maturity are required. All others are optional. They will be set to the default values if you do not explicitly set them. Note that, 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 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
Note that 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 very 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 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 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. Note that 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 will be 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 sync 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 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 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.
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:
bnddurp and bnddury support duration and convexity analysis based on market quotes and assume parallel shifts in the bond yield curve.
bndkrdur supports key rate duration based on a market yield curve and can model nonparallel shifts in the bond yield curve.
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 (PerDuration) 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 U.S. 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 http://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