intenvset

Set properties of interest-rate structure

Syntax

RateSpec = intenvset(Name,Value)

[RateSpec,RateSpecOld] = intenvset(RateSpec,Name,Value)

[RateSpec,RateSpecOld] = intenvset

Description

RateSpec = intenvset(Name,Value) creates an interest-rate term structure (RateSpec) where the input argument list is specified as name-value pairs.

Note

When creating a new RateSpec, the set of arguments passed to intenvset must include StartDates, EndDates, and either Rates or Disc.

Alternatively, you can create a RateSpec using the Financial Instruments Toolbox™ object framework to construct a ratecurve object. For more information on converting a RateSpec object to a ratecurve object, see Convert RateSpec to a ratecurve Object.

[RateSpec,RateSpecOld] = intenvset(RateSpec,Name,Value) creates an interest-rate term structure (RateSpec) where the input argument list is specified as name-value pairs along with the optional argument RateSpec. If the optional argument RateSpec is specified, intenvset modifies the existing interest-rate term structure RateSpec by changing the named argument to the specified values and recalculating the arguments dependent on the new values.

[RateSpec,RateSpecOld] = intenvset creates an interest-rate term structure RateSpec with all fields set to [ ].

Examples

Create a RateSpec for a Zero Curve

Use intenvset to create a RateSpec for a zero curve.

RateSpec = intenvset('Rates', 0.05, 'StartDates',... 
datetime(2000,1,20), 'EndDates', datetime(2021,1,20))

RateSpec = struct with fields:
           FinObj: 'RateSpec'
      Compounding: 2
             Disc: 0.3545
            Rates: 0.0500
         EndTimes: 42
       StartTimes: 0
         EndDates: 738176
       StartDates: 730505
    ValuationDate: 730505
            Basis: 0
     EndMonthRule: 1

Now change the Compounding argument to 1 (annual).

RateSpec = intenvset(RateSpec, 'Compounding', 1)

RateSpec = struct with fields:
           FinObj: 'RateSpec'
      Compounding: 1
             Disc: 0.3545
            Rates: 0.0506
         EndTimes: 21
       StartTimes: 0
         EndDates: 738176
       StartDates: 730505
    ValuationDate: 730505
            Basis: 0
     EndMonthRule: 1

Calling intenvset with no input or output arguments displays a list of argument names and possible values.

intenvset

            Compounding: [ 0 | 1 | {2} | 3 | 4 | 6 | 12 | 365 | -1 ]
                   Disc: [ scalar | vector (NPOINTS x 1) ]
                  Rates: [ scalar | vector (NPOINTS x 1) ]
               EndDates: [ scalar | vector (NPOINTS x 1) ]
             StartDates: [ scalar | vector (NPOINTS x 1) ]
          ValuationDate: [ scalar ]
                  Basis: [ {0} | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 ]
           EndMonthRule: [ 0 | {1} ]

Create a RateSpec for a Forward Curve

Use intenvset to create a RateSpec for a forward curve.

RateSpec = intenvset('Rates', 0.05, 'StartDates',... 
datetime(2001,1,20), 'EndDates', datetime(2022,1,20), 'ValuationDate',datetime(2000,1,20))

RateSpec = struct with fields:
           FinObj: 'RateSpec'
      Compounding: 2
             Disc: 0.3545
            Rates: 0.0500
         EndTimes: 44
       StartTimes: 2
         EndDates: 738541
       StartDates: 730871
    ValuationDate: 730505
            Basis: 0
     EndMonthRule: 1

Now change the Compounding argument to 1 (annual).

RateSpec = intenvset(RateSpec, 'Compounding', 1)

RateSpec = struct with fields:
           FinObj: 'RateSpec'
      Compounding: 1
             Disc: 0.3545
            Rates: 0.0506
         EndTimes: 22
       StartTimes: 1
         EndDates: 738541
       StartDates: 730871
    ValuationDate: 730505
            Basis: 0
     EndMonthRule: 1

Create a RateSpec Using Two Curves

Define data for the interest-rate term structure and use intenvset to create a RateSpec.

StartDates = datetime(2011,11,1); 
EndDates = [datetime(2012,11,1) ; datetime(2013,11,1) ; datetime(2014,11,1) ; datetime(2015,11,1)];
Rates = [[0.0356;0.041185;0.04489;0.047741],[0.0325;0.0423;0.0437;0.0465]];
RateSpec = intenvset('Rates', Rates, 'StartDates',StartDates,...
'EndDates', EndDates, 'Compounding', 1)

RateSpec = struct with fields:
           FinObj: 'RateSpec'
      Compounding: 1
             Disc: [4x2 double]
            Rates: [4x2 double]
         EndTimes: [4x1 double]
       StartTimes: [4x1 double]
         EndDates: [4x1 double]
       StartDates: 734808
    ValuationDate: 734808
            Basis: 0
     EndMonthRule: 1

To look at the Rates for the two interest-rate curves:

RateSpec.Rates

ans = 4×2

    0.0356    0.0325
    0.0412    0.0423
    0.0449    0.0437
    0.0477    0.0465

Create a RateSpec to Price Multi-Stepped Coupon Bonds

Price the following multi-stepped coupon bonds using the following data:

Rates = [0.035; 0.042147; 0.047345; 0.052707];
ValuationDate = datetime(2010,1,1);
StartDates = ValuationDate;
EndDates = [datetime(2011,1,1) ; datetime(2012,1,1) ; datetime(2013,1,1) ; datetime(2014,1,1)];
Compounding = 1;

% Create RateSpec using intenvset
RS = intenvset('ValuationDate', ValuationDate, 'StartDates', StartDates,...
'EndDates', EndDates,'Rates', Rates, 'Compounding', Compounding);

% Create a portfolio of stepped coupon bonds with different maturities
Settle = datetime(2010,1,1);
Maturity = [datetime(2011,1,1) ; datetime(2012,1,1) ; datetime(2013,1,1) ; datetime(2014,1,1)];
CouponRate = {{datetime(2011,1,1) .042;datetime(2012,1,1) .05;datetime(2013,1,1) .06;datetime(2014,1,1) .07}};

% Display the instrument portfolio 
ISet = instbond(CouponRate, Settle, Maturity, 1);
instdisp(ISet)

Index Type CouponRate Settle         Maturity       Period Basis EndMonthRule IssueDate FirstCouponDate LastCouponDate StartDate Face
1     Bond [Cell]     01-Jan-2010    01-Jan-2011    1      0     1            NaN       NaN             NaN            NaN       100 
2     Bond [Cell]     01-Jan-2010    01-Jan-2012    1      0     1            NaN       NaN             NaN            NaN       100 
3     Bond [Cell]     01-Jan-2010    01-Jan-2013    1      0     1            NaN       NaN             NaN            NaN       100 
4     Bond [Cell]     01-Jan-2010    01-Jan-2014    1      0     1            NaN       NaN             NaN            NaN       100 
 

Build a BDTTree to price the stepped coupon bonds. Assume the volatility to be 10%

Sigma = 0.1; 
BDTTimeSpec = bdttimespec(ValuationDate, EndDates, Compounding);
BDTVolSpec = bdtvolspec(ValuationDate, EndDates, Sigma*ones(1, length(EndDates))');
BDTT = bdttree(BDTVolSpec, RS, BDTTimeSpec);

% Compute the price of the stepped coupon bonds
PBDT = bdtprice(BDTT, ISet)

PBDT = 4×1

  100.6763
  100.7368
  100.9266
  101.0115

Input Arguments

RateSpec — Interest-rate specification for initial risk-free rate curve

structure

(Optional) Interest-rate specification for initial rate curve, specified by the RateSpec obtained previously from intenvset or toRateSpec for an IRDataCurve or toRateSpec for an IRFunctionCurve.

Data Types: struct

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: RateSpec = intenvset('Rates',0.05,'StartDates','20-Jan-2001','EndDates','20-Jan-2002','ValuationDate','20-Jan-2000')

Compounding — Rate at which the input zero rates were compounded when annualized

2 (default) | integer with value of 0,1, 2, 3, 4, 6, 12, 365, or -1

Rate at which the input zero rates were compounded when annualized, specified as the comma-separated pair consisting of 'Compounding' and a scalar integer value. The Compounding argument determines the formula for the discount factors (Disc):

• Compounding = 0 for simple interest

  • Disc = 1/(1 + Z * T), where T is time in years and simple interest assumes annual times F = 1.

• Compounding = 1, 2, 3, 4, 6, 12

  • Disc = (1 + Z/F)^(-T), where F is the compounding frequency, Z is the zero rate, and T is the time in periodic units, for example, T = F is one year.

• Compounding = 365

  • Disc = (1 + Z/F)^(-T), where F is the number of days in the basis year and T is a number of days elapsed computed by basis.

• Compounding = -1

  • Disc = exp(-T*Z), where T is time in years.

Data Types: double

Disc — Unit bond prices over investment intervals

[ ] (default) | matrix

Unit bond prices over investment intervals from StartDates (when the cash flow is valued) to EndDates (when the cash flow is received), specified as the comma-separated pair consisting of 'Disc' and a number of points (NPOINTS) by number of curves (NCURVES) matrix.

Data Types: double

Rates — Interest rates

matrix of decimal values

Interest rates, specified as the comma-separated pair consisting of 'Rates' and a number of points (NPOINTS) by number of curves (NCURVES) matrix of decimal values. Rates can only contain negative decimal values if the resulting RateSpec is used with a Normal (Bachelier) model, shifted Black model, or a shifted SABR model.

Data Types: double

EndDates — Maturity dates ending the interval to discount over

datetime array | string array | date character vector

Maturity dates ending the interval to discount over, specified as the comma-separated pair consisting of 'EndDates' and a scalar or a NPOINTS-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, intenvset also accepts serial date numbers as inputs, but they are not recommended.

StartDates — Dates starting the interval to discount over

datetime array | string array | date character vector

Dates starting the interval to discount over, specified as the comma-separated pair consisting of 'StartDates' and a scalar or a NPOINTS-by-1 vector using a datetime array, string array, or date character vectors. StartDates must be earlier than EndDates.

To support existing code, intenvset also accepts serial date numbers as inputs, but they are not recommended.

ValuationDate — Observation date of the investment horizons entered in StartDates and EndDates

min(StartDates) (default) | datetime array | string array | date character vector

Observation date of the investment horizons entered in StartDates and EndDates, specified as the comma-separated pair consisting of 'ValuationDate' and a specified as a scalar datetime, string, or date character vector.

To support existing code, intenvset also accepts serial date numbers as inputs, but they are not recommended.

Basis — Day-count basis

0 (actual/actual) (default) | integer from 0 to 13

Day-count basis, specified as the comma-separated pair consisting of 'Basis' and a scalar integer value.

• 0 = actual/actual

• 1 = 30/360 (SIA)

• 2 = actual/360

• 3 = actual/365

• 4 = 30/360 (PSA)

• 5 = 30/360 (ISDA)

• 6 = 30/360 (European)

• 7 = actual/365 (Japanese)

• 8 = actual/actual (ICMA)

• 9 = actual/360 (ICMA)

• 10 = actual/365 (ICMA)

• 11 = 30/360E (ICMA)

• 12 = actual/365 (ISDA)

• 13 = BUS/252

For more information, see Basis.

Data Types: double

EndMonthRule — End-of-month rule flag

1 (in effect) (default) | nonnegative integer with values 0 or 1

End-of-month rule flag, specified as the comma-separated pair consisting of 'EndMonthRule' and a scalar integer with a value of 0 or 1. This rule applies only when EndDates is an end-of-month date for a month having 30 or fewer days.

• 0 = Ignore rule, meaning that a bond coupon payment date is always the same numerical day of the month.

• 1 = Set rule on, meaning that a bond coupon payment date is always the last actual day of the month.

Data Types: double

Output Arguments

RateSpec — Interest-rate specification for initial rate curve

structure

Interest-rate specification for initial rate curve, returned as a structure.

RateSpecOld — Properties of an interest-rate structure before the changes introduced by the call to intenvset

structure

Properties of an interest-rate structure before the changes introduced by the call to intenvset, returned as a structure.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although intenvset supports serial date numbers, datetime values are recommended instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

To convert serial date numbers or text to datetime values, use the datetime function. For example:

t = datetime(738427.656845093,"ConvertFrom","datenum");
y = year(t)

y =

        2021

There are no plans to remove support for serial date number inputs.