Modeling the Interest-Rate Term Structure

Financial Instruments Toolbox™ 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

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 name-value pairs. The name-value pair arguments that can be specified or modified are:

Basis
Compounding
Disc
EndDates
EndMonthRule
Rates
StartDates
ValuationDate

For more information on Basis, see Basis.

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')

To obtain Disc, the values for the discount factors that were calculated automatically by intenvset, type:

Disc = intenvget(rs, 'Disc')

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 six months is represented with a value of 0.5, and a period of one 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 six-month periods. Since the redefined value of compounding is 1, EndTimes becomes a sequence of numbers separated by increments of 0.5.

Documentation