Accelerating the pace of engineering and science

# Documentation

## Understanding the Interest-Rate Term Structure

### Introduction

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.

### Interest Rates Versus Discount Factors

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.

#### Calculating Discount Factors from Rates

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

#### Optional Time Factor Outputs

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.

#### Alternative Syntax (rate2disc)

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

#### Calculating Rates from Discounts

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

#### Alternative Syntax (disc2rate)

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 Term Conversions

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.

#### Spot Curve to Forward Curve Conversion

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

#### Alternative Syntax (ratetimes)

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

### Modeling the Interest-Rate Term Structure

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)

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.

#### Obtaining Specific Properties (intenvget)

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.