Documentation |
On this page… |
---|
Interest Rates Versus Discount Factors |
The interest-rate term structure represents the evolution of interest rates through time. In MATLAB^{®} software, the interest-rate environment is encapsulated in a structure called RateSpec (rate specification). This structure holds all information required to completely identify the evolution of interest rates. Several functions included in Financial Instruments Toolbox™ software are dedicated to the creating and managing of the RateSpec structure. Many others take this structure as an input argument representing the evolution of interest rates.
Before looking further at the RateSpec structure, examine three functions that provide key functionality for working with interest rates: disc2rate, its opposite, rate2disc, and ratetimes. The first two functions map between discount factors and interest rates. The third function, ratetimes, calculates the effect of term changes on the interest rates.
Discount factors are coefficients commonly used to find the current value of future cash flows. As such, there is a direct mapping between the rate applicable to a period of time, and the corresponding discount factor. The function disc2rate converts discount factors for a given term (period) into interest rates. The function rate2disc does the opposite; it converts interest rates applicable to a given term (period) into the corresponding discount factors.
As an example, consider these annualized zero-coupon bond rates.
From | To | Rate |
---|---|---|
15 Feb 2000 | 15 Aug 2000 | 0.05 |
15 Feb 2000 | 15 Feb 2001 | 0.056 |
15 Feb 2000 | 15 Aug 2001 | 0.06 |
15 Feb 2000 | 15 Feb 2002 | 0.065 |
15 Feb 2000 | 15 Aug 2002 | 0.075 |
To calculate the discount factors corresponding to these interest rates, call rate2disc using the syntax
Disc = rate2disc(Compounding, Rates, EndDates, StartDates, ValuationDate)
where:
Compounding represents the frequency at which the zero rates are compounded when annualized. For this example, assume this value to be 2.
Rates is a vector of annualized percentage rates representing the interest rate applicable to each time interval.
EndDates is a vector of dates representing the end of each interest-rate term (period).
StartDates is a vector of dates representing the beginning of each interest-rate term.
ValuationDate is the date of observation for which the discount factors are calculated. In this particular example, use February 15, 2000 as the beginning date for all interest-rate terms.
Next, set the variables in MATLAB.
StartDates = ['15-Feb-2000']; EndDates = ['15-Aug-2000'; '15-Feb-2001'; '15-Aug-2001';... '15-Feb-2002'; '15-Aug-2002']; Compounding = 2; ValuationDate = ['15-Feb-2000']; Rates = [0.05; 0.056; 0.06; 0.065; 0.075];
Finally, compute the discount factors.
Disc = rate2disc(Compounding, Rates, EndDates, StartDates,... ValuationDate)
Disc = 0.9756 0.9463 0.9151 0.8799 0.8319
By adding a fourth column to the rates table (see Calculating Discount Factors from Rates) to include the corresponding discounts, you can see the evolution of the discount factors.
From | To | Rate | Discount |
---|---|---|---|
15 Feb 2000 | 15 Aug 2000 | 0.05 | 0.9756 |
15 Feb 2000 | 15 Feb 2001 | 0.056 | 0.9463 |
15 Feb 2000 | 15 Aug 2001 | 0.06 | 0.9151 |
15 Feb 2000 | 15 Feb 2002 | 0.065 | 0.8799 |
15 Feb 2000 | 15 Aug 2002 | 0.075 | 0.8319 |
The function rate2disc optionally returns two additional output arguments: EndTimes and StartTimes. These vectors of time factors represent the start dates and end dates in discount periodic units. The scale of these units is determined by the value of the input variable Compounding.
To examine the time factor outputs, find the corresponding values in the previous example.
[Disc, EndTimes, StartTimes] = rate2disc(Compounding, Rates,... EndDates, StartDates, ValuationDate);
Arrange the two vectors into a single array for easier visualization.
Times = [StartTimes, EndTimes]
Times = 0 1 0 2 0 3 0 4 0 5
Because the valuation date is equal to the start date for all periods, the StartTimes vector is composed of 0s. Also, since the value of Compounding is 2, the rates are compounded semiannually, which sets the units of periodic discount to 6 months. The vector EndDates is composed of dates separated by intervals of 6 months from the valuation date. This explains why the EndTimes vector is a progression of integers from 1 to 5.
The function rate2disc also accommodates an alternative syntax that uses periodic discount units instead of dates. Since the relationship between discount factors and interest rates is based on time periods and not on absolute dates, this form of rate2disc allows you to work directly with time periods. In this mode, the valuation date corresponds to 0, and the vectors StartTimes and EndTimes are used as input arguments instead of their date equivalents, StartDates and EndDates. This syntax for rate2disc is:
Disc = rate2disc(Compounding, Rates, EndTimes, StartTimes)
Using as input the StartTimes and EndTimes vectors computed previously, you should obtain the previous results for the discount factors.
Disc = rate2disc(Compounding, Rates, EndTimes, StartTimes)
Disc = 0.9756 0.9463 0.9151 0.8799 0.8319
The function disc2rate is the complement to rate2disc. It finds the rates applicable to a set of compounding periods, given the discount factor in those periods. The syntax for calling this function is:
Rates = disc2rate(Compounding, Disc, EndDates, StartDates, ValuationDate)
Each argument to this function has the same meaning as in rate2disc. Use the results found in the previous example to return the rate values you started with.
Rates = disc2rate(Compounding, Disc, EndDates, StartDates,... ValuationDate)
Rates = 0.0500 0.0560 0.0600 0.0650 0.0750
As in the case of rate2disc, disc2rate optionally returns StartTimes and EndTimes vectors representing the start and end times measured in discount periodic units. Again, working with the same values as before, you should obtain the same numbers.
[Rates, EndTimes, StartTimes] = disc2rate(Compounding, Disc,... EndDates, StartDates, ValuationDate);
Arrange the results in a matrix convenient to display.
Result = [StartTimes, EndTimes, Rates]
Result = 0 1.0000 0.0500 0 2.0000 0.0560 0 3.0000 0.0600 0 4.0000 0.0650 0 5.0000 0.0750
As with rate2disc, the relationship between rates and discount factors is determined by time periods and not by absolute dates. Consequently, the alternate syntax for disc2rate uses time vectors instead of dates, and it assumes that the valuation date corresponds to time = 0. The time-based calling syntax is:
Rates = disc2rate(Compounding, Disc, EndTimes, StartTimes);
Using this syntax, you again obtain the original values for the interest rates.
Rates = disc2rate(Compounding, Disc, EndTimes, StartTimes)
Rates = 0.0500 0.0560 0.0600 0.0650 0.0750
Interest rate evolution is typically represented by a set of interest rates, including the beginning and end of the periods the rates apply to. For zero rates, the start dates are typically at the valuation date, with the rates extending from that valuation date until their respective maturity dates.
Frequently, given a set of rates including their start and end dates, you may be interested in finding the rates applicable to different terms (periods). This problem is addressed by the function ratetimes. This function interpolates the interest rates given a change in the original terms. The syntax for calling ratetimes is
[Rates, EndTimes, StartTimes] = ratetimes(Compounding, RefRates, RefEndDates, RefStartDates, EndDates, StartDates, ValuationDate);
where:
Compounding represents the frequency at which the zero rates are compounded when annualized.
RefRates is a vector of initial interest rates representing the interest rates applicable to the initial time intervals.
RefEndDates is a vector of dates representing the end of the interest rate terms (period) applicable to RefRates.
RefStartDates is a vector of dates representing the beginning of the interest rate terms applicable to RefRates.
EndDates represent the maturity dates for which the interest rates are interpolated.
StartDates represent the starting dates for which the interest rates are interpolated.
ValuationDate is the date of observation, from which the StartTimes and EndTimes are calculated. This date represents time = 0.
The input arguments to this function can be separated into two groups:
The initial or reference interest rates, including the terms for which they are valid
Terms for which the new interest rates are calculated
As an example, consider the rate table specified in Calculating Discount Factors from Rates.
From | To | Rate |
---|---|---|
15 Feb 2000 | 15 Aug 2000 | 0.05 |
15 Feb 2000 | 15 Feb 2001 | 0.056 |
15 Feb 2000 | 15 Aug 2001 | 0.06 |
15 Feb 2000 | 15 Feb 2002 | 0.065 |
15 Feb 2000 | 15 Aug 2002 | 0.075 |
Assuming that the valuation date is February 15, 2000, these rates represent zero-coupon bond rates with maturities specified in the second column. Use the function ratetimes to calculate the forward rates at the beginning of all periods implied in the table. Assume a compounding value of 2.
% Reference Rates. RefStartDates = ['15-Feb-2000']; RefEndDates = ['15-Aug-2000'; '15-Feb-2001'; '15-Aug-2001';... '15-Feb-2002'; '15-Aug-2002']; Compounding = 2; ValuationDate = ['15-Feb-2000']; RefRates = [0.05; 0.056; 0.06; 0.065; 0.075]; % New Terms. StartDates = ['15-Feb-2000'; '15-Aug-2000'; '15-Feb-2001';... '15-Aug-2001'; '15-Feb-2002']; EndDates = ['15-Aug-2000'; '15-Feb-2001'; '15-Aug-2001';... '15-Feb-2002'; '15-Aug-2002']; % Find the new rates. Rates = ratetimes(Compounding, RefRates, RefEndDates,... RefStartDates, EndDates, StartDates, ValuationDate)
Rates = 0.0500 0.0620 0.0680 0.0801 0.1155
Place these values in a table like the previous one. Observe the evolution of the forward rates based on the initial zero-coupon rates.
From | To | Rate |
---|---|---|
15 Feb 2000 | 15 Aug 2000 | 0.0500 |
15 Aug 2000 | 15 Feb 2001 | 0.0620 |
15 Feb 2001 | 15 Aug 2001 | 0.0680 |
15 Aug 2001 | 15 Feb 2002 | 0.0801 |
15 Feb 2002 | 15 Aug 2002 | 0.1155 |
The ratetimes function can provide the additional output arguments StartTimes and EndTimes, which represent the time factor equivalents to the StartDates and EndDates vectors. The ratetimes function uses time factors for interpolating the rates. These time factors are calculated from the start and end dates, and the valuation date, which are passed as input arguments. ratetimes can also use time factors directly, assuming time = 0 as the valuation date. This alternate syntax is:
[Rates, EndTimes, StartTimes] = ratetimes(Compounding, RefRates, RefEndTimes, RefStartTimes, EndTimes, StartTimes);
Use this alternate version of ratetimes to find the forward rates again. In this case, you must first find the time factors of the reference curve. Use date2time for this.
RefEndTimes = date2time(ValuationDate, RefEndDates, Compounding)
RefEndTimes = 1 2 3 4 5
RefStartTimes = date2time(ValuationDate, RefStartDates,... Compounding)
RefStartTimes = 0
These are the expected values, given semiannual discounts (as denoted by a value of 2 in the variable Compounding), end dates separated by 6-month periods, and the valuation date equal to the date marking beginning of the first period (time factor = 0).
Now call ratetimes with the alternate syntax.
[Rates, EndTimes, StartTimes] = ratetimes(Compounding,... RefRates, RefEndTimes, RefStartTimes, EndTimes, StartTimes);
Rates = 0.0500 0.0620 0.0680 0.0801 0.1155
EndTimes and StartTimes have, as expected, the same values they had as input arguments.
Times = [StartTimes, EndTimes]
Times = 0 1 1 2 2 3 3 4 4 5
Financial Instruments Toolbox software includes a set of functions to encapsulate interest-rate term information into a single structure. These functions present a convenient way to package all information related to interest-rate terms into a common format, and to resolve interdependencies when one or more of the parameters is modified. For information, see:
Creating or Modifying (intenvset) for a discussion of how to create or modify an interest-rate term structure (RateSpec) using the intenvset function
Obtaining Specific Properties (intenvget) for a discussion of how to extract specific properties from a RateSpec
The main function to create or modify an interest-rate term structure RateSpec (rates specification) is intenvset. If the first argument to this function is a previously created RateSpec, the function modifies the existing rate specification and returns a new one. Otherwise, it creates a RateSpec.
When using RateSpec to specify the rate term structure to price instruments based on yields (zero coupon rates) or forward rates, specify zero rates or forward rates as the input argument. However, the RateSpec structure is not limited or specific to this problem domain. RateSpec is an encapsulation of rates-times relationships; intenvset acts as either a constructor or a modifier, and intenvget as an accessor. The interest rate models supported by the Financial Instruments Toolbox software work either with zero coupon rates or forward rates.
The other intenvset arguments are property-value pairs, indicating the new value for these properties. The properties that can be specified or modified are:
Basis
Compounding
Disc
EndDates
EndMonthRule
Rates
StartDates
ValuationDate
To learn about the properties EndMonthRule and Basis, type help ftbEndMonthRule and help ftbBasis or see the Financial Toolbox™ documentation.
Consider again the original table of interest rates (see Calculating Discount Factors from Rates).
From | To | Rate |
---|---|---|
15 Feb 2000 | 15 Aug 2000 | 0.05 |
15 Feb 2000 | 15 Feb 2001 | 0.056 |
15 Feb 2000 | 15 Aug 2001 | 0.06 |
15 Feb 2000 | 15 Feb 2002 | 0.065 |
15 Feb 2000 | 15 Aug 2002 | 0.075 |
Use the information in this table to populate the RateSpec structure.
StartDates = ['15-Feb-2000']; EndDates = ['15-Aug-2000'; '15-Feb-2001'; '15-Aug-2001'; '15-Feb-2002'; '15-Aug-2002']; Compounding = 2; ValuationDate = ['15-Feb-2000']; Rates = [0.05; 0.056; 0.06; 0.065; 0.075]; rs = intenvset('Compounding',Compounding,'StartDates',... StartDates, 'EndDates', EndDates, 'Rates', Rates,... 'ValuationDate', ValuationDate)
rs = FinObj: 'RateSpec' Compounding: 2 Disc: [5x1 double] Rates: [5x1 double] EndTimes: [5x1 double] StartTimes: [5x1 double] EndDates: [5x1 double] StartDates: 730531 ValuationDate: 730531 Basis: 0 EndMonthRule: 1
Some of the properties filled in the structure were not passed explicitly in the call to RateSpec. The values of the automatically completed properties depend on the properties that are explicitly passed. Consider for example the StartTimes and EndTimes vectors. Since the StartDates and EndDates vectors are passed in, and the ValuationDate, intenvset has all the information required to calculate StartTimes and EndTimes. Hence, these two properties are read-only.
The complementary function to intenvset is intenvget, which gets function specific properties from the interest-rate term structure. Its syntax is:
ParameterValue = intenvget(RateSpec, 'ParameterName')
To obtain the vector EndTimes from the RateSpec structure, enter:
EndTimes = intenvget(rs, 'EndTimes')
EndTimes = 1 2 3 4 5
To obtain Disc, the values for the discount factors that were calculated automatically by intenvset, type:
Disc = intenvget(rs, 'Disc')
Disc = 0.9756 0.9463 0.9151 0.8799 0.8319
These discount factors correspond to the periods starting from StartDates and ending in EndDates.
Caution Although you can directly access these fields within the structure instead of using intenvget, it is advised not to do so. The format of the interest-rate term structure could change in future versions of the toolbox. Should that happen, any code accessing the RateSpec fields directly would stop working. |
Now use the RateSpec structure with its functions to examine how changes in specific properties of the interest-rate term structure affect those depending on it. As an exercise, change the value of Compounding from 2 (semiannual) to 1 (annual).
rs = intenvset(rs, 'Compounding', 1);
Since StartTimes and EndTimes are measured in units of periodic discount, a change in Compounding from 2 to 1 redefines the basic unit from semiannual to annual. This means that a period of 6 months is represented with a value of 0.5, and a period of 1 year is represented by 1. To obtain the vectors StartTimes and EndTimes, enter:
StartTimes = intenvget(rs, 'StartTimes'); EndTimes = intenvget(rs, 'EndTimes'); Times = [StartTimes, EndTimes]
Times = 0 0.5000 0 1.0000 0 1.5000 0 2.0000 0 2.5000
Since all the values in StartDates are the same as the valuation date, all StartTimes values are 0. On the other hand, the values in the EndDates vector are dates separated by 6-month periods. Since the redefined value of compounding is 1, EndTimes becomes a sequence of numbers separated by increments of 0.5.