prbyzero

Price bonds in portfolio by set of zero curves

Syntax

BondPrices = prbyzero(Bonds,Settle,ZeroRates,ZeroDates)

BondPrices = prbyzero(___,Compounding)

Description

BondPrices = prbyzero(Bonds,Settle,ZeroRates,ZeroDates) computes the bond prices in a portfolio using a set of zero curves.

BondPrices = prbyzero(___,Compounding) adds an optional argument for Compounding.

Examples

Compute the Bond Prices in a Portfolio Using a Set of Zero Curves

This example uses the function zbtprice to compute a zero curve given a portfolio of coupon bonds and their prices. It then reverses the process, using the zero curve as input to the function prbyzero to compute the prices.

Bonds = [datenum('6/1/1998') 0.0475 100 2 0 0; 
         datenum('7/1/2000') 0.06 100 2 0 0; 
         datenum('7/1/2000') 0.09375 100 6 1 0; 
         datenum('6/30/2001') 0.05125 100 1 3 1;
         datenum('4/15/2002') 0.07125 100 4 1 0;
         datenum('1/15/2000') 0.065 100 2 0 0; 
         datenum('9/1/1999') 0.08 100 3 3 0; 
         datenum('4/30/2001') 0.05875 100 2 0 0; 
         datenum('11/15/1999') 0.07125 100 2 0 0; 
         datenum('6/30/2000') 0.07 100 2 3 1; 
         datenum('7/1/2001') 0.0525 100 2 3 0; 
         datenum('4/30/2002') 0.07 100 2 0 0];

Prices = [ 99.375;
           99.875;
          105.75 ;
           96.875;
          103.625;
          101.125;
          103.125;
           99.375;
          101.0  ;
          101.25 ;
           96.375;
          102.75 ];

Settle = datenum('12/18/1997');

Set semiannual compounding for the zero curve, on an actual/365 basis.

OutputCompounding = 2;

Execute the function zbtprice which returns the zero curve at the maturity dates.

[ZeroRates, ZeroDates] = zbtprice(Bonds, Prices, Settle,...
OutputCompounding)

ZeroRates = 11×1

    0.0616
    0.0609
    0.0658
    0.0590
    0.0647
    0.0655
    0.0606
    0.0601
    0.0642
    0.0621
      ⋮

ZeroDates = 11×1

      729907
      730364
      730439
      730500
      730667
      730668
      730971
      731032
      731033
      731321
      ⋮

Execute the function prbyzero.

BondPrices = prbyzero(Bonds, Settle, ZeroRates, ZeroDates)

BondPrices = 12×1

   99.3750
   98.7980
  106.8270
   96.8750
  103.6249
  101.1250
  103.1250
   99.3637
  101.0000
  101.2500
      ⋮

In this example zbtprice and prbyzero do not exactly reverse each other. Many of the bonds have the end-of-month rule off (EndMonthRule = 0). The rule subtly affects the time factor computation. If you set the rule on (EndMonthRule = 1) everywhere in the Bonds matrix, then prbyzero returns the original prices, except when the two incompatible prices fall on the same maturity date.

Compute the Bond Prices in a Portfolio Using a Set of Zero Curves and datetime Inputs

This example uses the function zbtprice to compute a zero curve given a portfolio of coupon bonds and their prices. It then reverses the process, using the zero curve as input to the function prbyzero with datetime inputs to compute the prices.

Bonds = [datenum('6/1/1998') 0.0475 100 2 0 0;
         datenum('7/1/2000') 0.06 100 2 0 0;
         datenum('7/1/2000') 0.09375 100 6 1 0;
         datenum('6/30/2001') 0.05125 100 1 3 1;
         datenum('4/15/2002') 0.07125 100 4 1 0;
         datenum('1/15/2000') 0.065 100 2 0 0;
         datenum('9/1/1999') 0.08 100 3 3 0;
         datenum('4/30/2001') 0.05875 100 2 0 0;
         datenum('11/15/1999') 0.07125 100 2 0 0;
         datenum('6/30/2000') 0.07 100 2 3 1;
         datenum('7/1/2001') 0.0525 100 2 3 0;
         datenum('4/30/2002') 0.07 100 2 0 0];

Prices = [ 99.375;
           99.875;
          105.75 ;
           96.875;
          103.625;
          101.125;
          103.125;
           99.375;
          101.0  ;
          101.25 ;
           96.375;
          102.75 ];

Settle = datenum('12/18/1997');
OutputCompounding = 2;

[ZeroRates, ZeroDates] = zbtprice(Bonds, Prices, Settle, OutputCompounding);

dates = datetime(Bonds(:,1),'ConvertFrom','datenum','Locale','en_US');
data = Bonds(:,2:end);
t=[table(dates) array2table(data)];
BondPrices = prbyzero(t, datetime(Settle,'ConvertFrom','datenum','Locale','en_US'),...
ZeroRates, datetime(ZeroDates,'ConvertFrom','datenum','Locale','en_US'))

BondPrices = 12×1

   99.3750
   98.7980
  106.8270
   96.8750
  103.6249
  101.1250
  103.1250
   99.3637
  101.0000
  101.2500
      ⋮

Input Arguments

Bonds — Coupon bond information to compute prices

table | matrix

Coupon bond information to compute prices, specified as a 6-column table or a NumBonds-by-6 matrix of bond information where the table columns or matrix columns contains:

• Maturity (Required) Maturity date of the bond as a serial date number. Use datenum to convert date character vectors to serial date numbers. If the input Bonds is a table, the Maturity dates can be a datetime array, string array, or date character vectors.

• CouponRate (Required) Decimal number indicating the annual percentage rate used to determine the coupons payable on a bond.

• Face (Optional) Face or par value of the bond. Default = 100.

• Period (Optional) Coupons per year of the bond. Allowed values are 0, 1, 2 (default), 3, 4, 6, and 12.

• Basis (Optional) Day-count basis of the bond. A vector of integers.

  • 0 = actual/actual (default)

  • 1 = 30/360 (SIA)

  • 2 = actual/360

  • 3 = actual/365

  • 4 = 30/360 (BMA)

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

• EndMonthRule (Optional) End-of-month rule. This rule applies only when Maturity is an end-of-month date for a month having 30 or fewer days. 0 = ignore rule, meaning that a bond's coupon payment date is always the same numerical day of the month. 1 = set rule on (default), meaning that a bond's coupon payment date is always the last actual day of the month

:

Note

• If Bonds is a table, the table columns have the same meaning as when a matrix is used, but the Maturity dates can be a datetime array, string array, or date character vectors.

• If Bonds is a matrix, it is a NUMBONDS-by-6 matrix of bonds where each row describes one bond. The first two columns are required; the remaining columns are optional but must be added in order. All rows in Bonds must have the same number of columns. The columns are Maturity, CouponRate, Face, Period, Basis, and EndMonthRule.

.

Data Types: double | char | string | datetime | table

Settle — Settlement date

datetime scalar | string scalar | date character vector

Settlement date, specified as a scalar datetime, string, or date character vector.

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

Data Types: datetime | string | char

ZeroRates — Observed zero rates

decimal fractions

Observed zero rates, specified as NUMDATES-by-NUMCURVES matrix of decimal fractions. Each column represents a rate curve. Each row represents an observation date.

Data Types: double

ZeroDates — Observed dates for ZeroRates

datetime array | string array | date character vector

Observed dates for ZeroRates, specified as a NUMDATES-by-1 column vector using a datetime array, string array, or date character vectors.

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

Data Types: datetime | string | char

Compounding — Compounding frequency of input ZeroRates when annualized

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

(Optional) Compounding frequency of input ZeroRates when annualized, specified using the allowed values:

• 1 — Annual compounding

• 2 — Semiannual compounding (default)

• 3 — Compounding three times per year

• 4 — Quarterly compounding

• 6 — Bimonthly compounding

• 12 — Monthly compounding

Data Types: double

Output Arguments

BondPrices — Clean bond prices

numeric

Clean bond prices, returned as a NUMBONDS-by-NUMCURVES matrix. Each column is derived from the corresponding zero curve in ZeroRates.

In addition, you can use the Financial Instruments Toolbox™ method getZeroRates (Financial Instruments Toolbox) for an IRDataCurve object with a Dates property to create a vector of dates and data acceptable for prbyzero. For more information, see Converting an IRDataCurve or IRFunctionCurve Object (Financial Instruments Toolbox).

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

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