zero2pyld

Par yield curve given zero curve

Syntax

[ParRates,CurveDates] = zero2pyld(ZeroRates,CurveDates,Settle)

[ParRates,CurveDates] = zero2pyld(___,Name,Value)

Description

[ParRates,CurveDates] = zero2pyld(ZeroRates,CurveDates,Settle) returns a par yield curve given a zero curve and its maturity dates. If either input for CurveDates or Settle is a datetime array, CurveDates is returned as a datetime array. Otherwise, CurveDates is returned as a serial date number. Use the function datetime to convert serial date numbers to formatted datetime arrays. ParRates is the same for any of these input data types.

[ParRates,CurveDates] = zero2pyld(___,Name,Value) adds optional name-value pair arguments

Examples

Compute Par Yield Curve Given a Zero Curve and Maturity Dates Using datetime Inputs

Given a zero curve over a set of maturity dates, a settlement date, and annual compounding for the input zero curve and monthly compounding for the output par rates, use datetime inputs to compute a par yield curve.

ZeroRates = [0.0457
0.0487
0.0506
0.0507
0.0505
0.0504
0.0506
0.0516
0.0539
0.0530];
CurveDates = [datetime(2000,11,6)
              datetime(2000,12,11)
              datetime(2001,1,15) 
              datetime(2001,2,5) 
              datetime(2001,3,4) 
              datetime(2001,4,2) 
              datetime(2001,4,30) 
              datetime(2001,6,25) 
              datetime(2001,9,4) 
              datetime(2001,11,12)];

Settle = datetime(2000,11,3);
InputCompounding = 12;
InputBasis = 2;
OutputCompounding = 1;
OutputBasis = 2;

[ParRates, CurveDates] = zero2pyld(ZeroRates, CurveDates,...
Settle, 'InputCompounding',12,'InputBasis',2,'OutputCompounding',1,'OutputBasis',2)

ParRates = 10×1

   -0.0436
    0.0611
    0.0579
    0.0567
    0.0550
    0.0543
    0.0541
    0.0546
    0.0565
    0.0561

CurveDates = 10×1 datetime
   06-Nov-2000
   11-Dec-2000
   15-Jan-2001
   05-Feb-2001
   04-Mar-2001
   02-Apr-2001
   30-Apr-2001
   25-Jun-2001
   04-Sep-2001
   12-Nov-2001

Demonstrate a Roundtrip From zero2pyld to pyld2zero

Given the following zero curve and its maturity dates, return the ParRates.

Settle = datetime(2013,2,1);

CurveDates = [datetime(2014,2,1) 
             datetime(2015,2,1) 
             datetime(2016,2,1) 
             datetime(2018,2,1) 
             datetime(2020,2,1) 
             datetime(2023,2,1) 
             datetime(2033,2,1) 
             datetime(2043,2,1) ];

OriginalZeroRates = [.11 0.30 0.64 1.44 2.07 2.61 3.29 3.55]'/100;

OutputCompounding = 1;
OutputBasis = 0;
InputCompounding = 1;
InputBasis = 0;

ParRates = zero2pyld(OriginalZeroRates, CurveDates, Settle, ...
'OutputCompounding', OutputCompounding, 'OutputBasis', OutputBasis, ...
'InputCompounding', InputCompounding, 'InputBasis', InputBasis)

ParRates = 8×1

    0.0011
    0.0030
    0.0064
    0.0142
    0.0202
    0.0251
    0.0310
    0.0331

For the ParRates, use the pyld2zero function to return the ZeroRatesOut and determine the roundtrip error.

ZeroRatesOut = pyld2zero(ParRates, CurveDates, Settle, ...
'OutputCompounding', OutputCompounding, 'OutputBasis', OutputBasis, ...
'InputCompounding', InputCompounding, 'InputBasis', InputBasis)

ZeroRatesOut = 8×1

    0.0011
    0.0030
    0.0064
    0.0144
    0.0207
    0.0261
    0.0329
    0.0355

max(abs(OriginalZeroRates - ZeroRatesOut)) % Roundtrip error

ans = 
1.4919e-16

Input Arguments

ZeroRates — Annualized zero rates

decimal fraction

Annualized zero rates, specified as a NUMBONDS-by-1 vector using decimal fractions. In aggregate, the rates constitute an implied zero curve for the investment horizon represented by CurveDates.

Data Types: double

CurveDates — Maturity dates

datetime array | string array | date character vector

Maturity dates which correspond to the input ZeroRates, specified as a NUMBONDS-by-1 vector using a datetime array, string array, or date character vectors.

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

Data Types: datetime | string | char

Settle — Common settlement date for ZeroRates

datetime scalar | string scalar | date character vector

Common settlement date for input ZeroRates, specified as a scalar datetime, string, or date character vector.

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

Data Types: datetime | string | char

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: [ParRates,CurveDates] = zero2pyld(ZeroRates,CurveDates, Settle,'OutputCompounding',3,'OutputBasis',5,'InputCompounding',4,'InputBasis',5)

OutputCompounding — Compounding frequency of output ParRates

2 (default) | numeric values: 0,1, 2, 3, 4, 6, 12, 365, -1

Compounding frequency of output ParRates, specified as the comma-separated pair consisting of 'OutputCompounding' and allowed values:

• 1 — Annual compounding

• 2 — Semiannual compounding (default)

• 3 — Compounding three times per year

• 4 — Quarterly compounding

• 6 — Bimonthly compounding

• 12 — Monthly compounding

Note

• If InputCompounding is 1, 2, 3, 4, 6, or 12 and OutputCompounding is not specified, the value of InputCompounding is used.

• If InputCompounding is 0 (simple), -1 (continuous), or 365 (daily), a valid OutputCompounding value must also be specified.

• If either InputCompounding or OutputCompounding are not specified, the default is 2 (semiannual) for both.

Data Types: double

OutputBasis — Day-count basis of output ParRates

0 (default) | numeric values: 0,1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13

Day count basis of output ParRates, specified as the comma-separated pair consisting of 'OutputBasis' and allowed values:

• 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.

Note

If OutputBasis is not specified, then OutputBasis is assigned the value specified for InputBasis. If either InputBasis or OutputBasis are not specified, the default is 0 (actual/actual) for both.

Data Types: double

InputCompounding — Compounding frequency of input ZeroRates

2 (default) | numeric values: 0,1, 2, 3, 4, 6, 12, 365, -1

Compounding frequency of input ZeroRates, specified as the comma-separated pair consisting of 'InputCompounding' and allowed values:

• 0 — Simple interest (no compounding)

• 1 — Annual compounding

• 2 — Semiannual compounding (default)

• 3 — Compounding three times per year

• 4 — Quarterly compounding

• 6 — Bimonthly compounding

• 12 — Monthly compounding

• 365 — Daily compounding

• -1 — Continuous compounding

Note

• If InputCompounding is set to 0 (simple), -1 (continuous), or 365 (daily), the OutputCompounding must also be specified using a valid value.

• If InputCompounding is not specified, then InputCompounding is assigned the value specified for OutputCompounding.

• If either InputCompounding or OutputCompounding are not specified, the default is 2 (semiannual) for both.

Data Types: double

InputBasis — Day-count basis of input ZeroRates

0 (default) | numeric values: 0,1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13

Day count basis of the input ZeroRates, specified as the comma-separated pair consisting of 'InputBasis' and allowed values:

• 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.

Note

If InputBasis is not specified, then InputBasis is assigned the value specified for OutputBasis. If either InputBasis or Outputbasis are not specified, the default is 0 (actual/actual) for both.

Data Types: double

Output Arguments

ParRates — Par bond coupon rates

numeric

Par bond coupon rates, returned as a NUMBONDS-by-1 numeric vector. ParRates are ordered by ascending maturity.

CurveDates — Maturity dates that correspond to ParRates

datetime | serial date number

Maturity dates that correspond to the ParRates, returned as a NUMBONDS-by-1 vector of maturity dates that correspond to each par rate contained in ParRates.

ParRates are expressed as serial date numbers (default) or datetimes (if CurveDates or Settle are datetime arrays). CurveDates are ordered by ascending maturity.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although zero2pyld 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.

R2017b: Support for optional name-value input arguments

The specification of optional input arguments has changed. While the previous ordered inputs syntax is still supported, it may no longer be supported in a future release. Use the new optional name-value pair inputs: InputCompounding, InputBasis, OutputCompounding, and OutputBasis.