pyld2zero

Zero curve given par yield curve

In R2017b, 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.

Syntax

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

[ZeroRates,CurveDates] = pyld2zero(___,Name,Value)

Description

[ZeroRates,CurveDates] = pyld2zero(ParRates,CurveDates,Settle) returns a zero curve given a par yield 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.

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

Examples

Compute Zero Curve Given Par Yield Curve

Define the settlement date, maturity, and zero rates.

Settle = datenum('01-Feb-2013');
CurveDates = datemnth(Settle,12*[1 2 3 5 7 10 20 30]');
ZeroRates = [.11 0.30 0.64 1.44 2.07 2.61 3.29 3.55]'/100;
InputCompounding = 2;
InputBasis = 1;
OutputCompounding = 2;
OutputBasis = 1;

Compute par yield curve from zero rates.

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

ParRates = 8×1

    0.0011
    0.0030
    0.0064
    0.0142
    0.0201
    0.0251
    0.0309
    0.0330

Compute zero curve from the par yield curve.

ZeroRates = pyld2zero(ParRates, CurveDates, Settle,'InputCompounding',2,...
'InputBasis',1,'OutputCompounding',2,'OutputBasis',1)

ZeroRates = 8×1

    0.0011
    0.0030
    0.0064
    0.0144
    0.0207
    0.0261
    0.0329
    0.0355

Compute Zero Curve Given Par Yield Curve Using datetime Inputs

Use datetime inputs to compute the zero curve given the par yield curve.

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)];

OriginalParRates = [0.11 0.30 0.64 1.42 2.02 2.51 3.10 3.31]'/100;

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

[ZeroRates Dates] = pyld2zero(OriginalParRates, CurveDates, Settle, ...
'OutputCompounding', OutputCompounding, 'OutputBasis', OutputBasis, ...
'InputCompounding', InputCompounding, 'InputBasis', InputBasis)

ZeroRates = 8×1

    0.0011
    0.0030
    0.0064
    0.0144
    0.0207
    0.0261
    0.0329
    0.0356

Dates = 8×1 datetime
   01-Feb-2014
   01-Feb-2015
   01-Feb-2016
   01-Feb-2018
   01-Feb-2020
   01-Feb-2023
   01-Feb-2033
   01-Feb-2043

Demonstrate a Roundtrip From pyld2zero to zero2pyld

Given the following a par yield curve and its maturity dates, return the ZeroRates.

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)];

OriginalParRates = [0.11 0.30 0.64 1.42 2.02 2.51 3.10 3.31]'/100;

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

ZeroRates = pyld2zero(OriginalParRates, CurveDates, Settle, ...
'OutputCompounding', OutputCompounding, 'OutputBasis', OutputBasis, ...
'InputCompounding', InputCompounding, 'InputBasis', InputBasis)

ZeroRates = 8×1

    0.0011
    0.0030
    0.0064
    0.0144
    0.0207
    0.0261
    0.0329
    0.0356

With the ZeroRates, use the zero2pyld function to return the ParRatesOut and determine the roundtrip error.

ParRatesOut = zero2pyld(ZeroRates, CurveDates, Settle, ...
'OutputCompounding', OutputCompounding, 'OutputBasis', OutputBasis, ...
'InputCompounding', InputCompounding, 'InputBasis', InputBasis)

ParRatesOut = 8×1

    0.0011
    0.0030
    0.0064
    0.0142
    0.0202
    0.0251
    0.0310
    0.0331

max(abs(OriginalParRates - ParRatesOut)) % Roundtrip error

ans = 
1.2750e-16

Input Arguments

ParRates — Annualized par yields

decimal fraction

Annualized par yields (coupon 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 ParRates, specified as a NUMBONDS-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, pyld2zero 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 ParRates, specified as a scalar datetime, string, or data character vector.

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

OutputCompounding — Compounding frequency of output ZeroRates

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

Compounding frequency of output ZeroRates, specified using the 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 OutputCompounding is set to 0 (simple), -1 (continuous), or 365 (daily), the InputCompounding must also be specified using a valid value.

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

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

Data Types: double

OutputBasis — Day-count basis of output ZeroRates

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

Day count basis of output ZeroRates, specified using 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 ParRates

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

Compounding frequency of input ParRates, specified using 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 OutputCompounding is 1, 2, 3, 4, 6, or 12 and InputCompounding is not specified, the value of OutputCompounding is used.

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

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

Data Types: double

InputBasis — Day-count basis of input ParRates

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

Day count basis of the input ParRates, specified using 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

ZeroRates — Zero rates

numeric

Zero rates, returned as a NUMBONDS-by-1 numeric vector. In aggregate, the rates in ZeroRates constitute a zero curve for the investment horizon represented by CurveDates. ZeroRates are ordered by ascending maturity.

CurveDates — Maturity dates that correspond to ZeroRates

datetime | serial date number

Maturity dates that correspond to the ZeroRates, returned as a NUMBONDS-by-1 vector of maturity dates that correspond to each par rate contained in ZeroRates. CurveDates are ordered by ascending maturity.

If either input for CurveDates or Settle is a datetime array, CurveDates is returned as a datetime array. Otherwise, CurveDates are returned as a serial date numbers. Use the function datetime to convert serial date numbers to formatted datetime arrays.

More About

Par Yield

Par yield is a financial term that refers to the coupon rate of a bond that is trading at par value, which means it is priced at its face value.

The par yield is the interest rate at which the present value of the bond's future cash flows (coupon payments and the face value at maturity) equals its current market price.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

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