tr2bonds

Term-structure parameters given Treasury bond parameters

Syntax

[Bonds,Prices,Yields] = tr2bonds(TreasuryMatrix,Settle)

[Bonds,Prices,Yields] = tr2bonds(___,Settle)

Description

[Bonds,Prices,Yields] = tr2bonds(TreasuryMatrix,Settle) returns term-structure parameters (Bonds, Prices, and Yields) sorted by ascending maturity date, given Treasury bond parameters. The formats of the output matrix and vectors meet requirements for input to the zbtprice and zbtyield zero-curve bootstrapping functions.

[Bonds,Prices,Yields] = tr2bonds(___,Settle) adds an optional argument for Settle.

Examples

Return Term-Structure Parameters Given Treasury Bond Parameters

This example shows how to return term-structure parameters (bond information, prices, and yields) sorted by ascending maturity date, given Treasury bond market parameters for December 22, 1997.

Matrix =[0.0650 datenum('15-apr-1999')  101.03125 101.09375 0.0564
         0.05125 datenum('17-dec-1998')  99.4375   99.5     0.0563
         0.0625 datenum('30-jul-1998')  100.3125  100.375   0.0560
         0.06125 datenum('26-mar-1998') 100.09375 100.15625 0.0546];

[Bonds, Prices, Yields] = tr2bonds(Matrix)

Bonds = 4×6
105 ×

    7.2984    0.0000    0.0010    0.0000         0    0.0000
    7.2997    0.0000    0.0010    0.0000         0    0.0000
    7.3011    0.0000    0.0010    0.0000         0    0.0000
    7.3022    0.0000    0.0010    0.0000         0    0.0000

Prices = 4×1

  100.1562
  100.3750
   99.5000
  101.0938

Yields = 4×1

    0.0546
    0.0560
    0.0563
    0.0564

Return Term-Structure Parameters Given Treasury Bond Parameters Using datetime Input

This example shows how to use datetime input to return term-structure parameters (bond information, prices, and yields) sorted by ascending maturity date, given Treasury bond market parameters for December 22, 1997.

Matrix =[0.0650 datenum('15-apr-1999')  101.03125 101.09375 0.0564
         0.05125 datenum('17-dec-1998')  99.4375   99.5     0.0563
         0.0625 datenum('30-jul-1998')  100.3125  100.375   0.0560
         0.06125 datenum('26-mar-1998') 100.09375 100.15625 0.0546];

t=array2table(Matrix);
t.Matrix2=datetime(t{:,2},'ConvertFrom','datenum','Locale','en_US');
[Bonds, Prices, Yields] = tr2bonds(t,datetime(1997,1,1))

Bonds=4×6 table
     Maturity      CouponRate    Face    Period    Basis    EndMonthRule
    ___________    __________    ____    ______    _____    ____________

    26-Mar-1998     0.06125      100       2         0           1      
    30-Jul-1998      0.0625      100       2         0           1      
    17-Dec-1998     0.05125      100       2         0           1      
    15-Apr-1999       0.065      100       2         0           1      

Prices = 4×1

  100.1562
  100.3750
   99.5000
  101.0938

Yields = 4×1

    0.0598
    0.0599
    0.0540
    0.0598

Input Arguments

TreasuryMatrix — Treasury bond parameters

table | matrix

Treasury bond parameters, specified as a 5-column table or a NumBonds-by-5 matrix of bond information where the table columns or matrix columns contains:

• CouponRate (Required) Coupon rate of the Treasury bond, specified as a decimal indicating the coupon rates for each bond in the portfolio.

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

• Bid (Required) Bid prices, specified using an integer-decimal form for each bond in the portfolio.

• Asked (Required) Asked prices, specified using an integer-decimal form for each bond in the portfolio.

• AskYield (Required) Quoted ask yield, specified using a decimal form for each bond in the portfolio.

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

Settle — Settlement date of Treasury bond

datetime array | string array | date character vector

(Optional) Settlement date of the Treasury bond, specified as a scalar or a NINST-by-1 vector using a datetime array, string array, or date character vectors. The Settle date must be before the Maturity date.

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

Data Types: char | string | datetime

Output Arguments

Bonds — Coupon bond information

table | matrix

Coupon bond information, returned as a table or matrix depending on the TreasuryMatrix input.

When TreasuryMatrix is a table, Bonds is also a table, and the variable type for the Maturity dates in Bonds (column 1) matches the variable type for Maturity in TreasuryMatrix.

When TreasuryMatrix input is a n-by-5 matrix, then each row describes a bond.

The parameters or columns returned for Bonds are:

• Maturity (Column 1) Maturity date for each bond in the portfolio. The format of the dates matches the format used for Maturity in TreasuryMatrix (datetime array, string array, date character vector, or serial date number).

• CouponRate (Column 2) Coupon rate for each bond in the portfolio in decimal form.

• Face (Column 3, Optional) Face or par value for each bond in the portfolio. The default is 100.

• Period (Column 4, Optional) Number of coupon payments per year for each bond in the portfolio with allowed values: 1, 2, 3, 4, 6, and 12. The default is 2, unless you are dealing with zero coupons, then Period is 0 instead of 2.

• Basis (Column 5, Optional) Day-count basis for each bond in the portfolio with possible values:

  • 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 (Column 6, Optional) End-of-month rule flag for each bond in the portfolio. 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, meaning that a bond's coupon payment date is always the last actual day of the month. The default is 1.

Prices — Bond prices

numeric

Bond prices, returned as a column vector containing the price of each bond in Bonds, respectively. The number of rows (n) matches the number of rows in Bonds.

Yields — Bond yields

numeric

Bond yields, returned as a column vector containing the yield to maturity of each bond in Bonds, respectively. The number of rows (n) matches the number of rows in Bonds.

If the optional input argument Settle is used, Yields is computed as a semiannual yield to maturity. If the input Settle is not used, the quoted input yields are used.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

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