Accelerating the pace of engineering and science

# bndyield

Yield to maturity for fixed-income security

## Syntax

Yield = bndyield(Price, CouponRate, Settle, Maturity)
Yield = bndyield(Price, CouponRate, Settle, Maturity,
Period, Basis, EndMonthRule, IssueDate, FirstCouponDate,
LastCouponDate, StartDate, Face)
Yield = bndyield(Price, CouponRate, Settle, Maturity,
'ParameterName', 'ParameterValue ...)

## Description

Yield = bndyield(Price, CouponRate, Settle, Maturity), given NUMBONDS bonds with SIA date parameters and clean prices (excludes accrued interest), returns the bond equivalent yields to maturity.

Yield = bndyield(Price, CouponRate, Settle, Maturity,
Period, Basis, EndMonthRule, IssueDate, FirstCouponDate,
LastCouponDate, StartDate, Face)
bonds with SIA date parameters and clean prices (excludes accrued interest) and optional inputs, returns the bond equivalent yields to maturity.

Yield = bndyield(Price, CouponRate, Settle, Maturity,
'ParameterName', 'ParameterValue ...)
accepts optional inputs as one or more comma-separated parameter/value pairs. 'ParameterName' is the name of the parameter inside single quotes. ParameterValue is the value corresponding to 'ParameterName'. Specify parameter/value pairs in any order. Names are case-insensitive.

## Input Arguments

 Price Clean price of the bond (current price without accrued interest). CouponRate Decimal number indicating the annual percentage rate used to determine the coupons payable on a bond. Settle Settlement date. A vector of serial date numbers or date strings. Settle must be earlier than Maturity. Maturity Maturity date. A vector of serial date numbers or date strings.

### Ordered Input or Parameter–Value Pairs

Enter the following inputs using an ordered syntax or as parameter/value pairs. You cannot mix ordered syntax with parameter/value pairs.

 Period Coupons per year of the bond. A vector of integers. Values are 0, 1, 2, 3, 4, 6, and 12. Default: 2 Basis Day-count basis of the instrument. A vector of integers. 0 = actual/actual 1 = 30/360 (SIA)2 = actual/3603 = actual/3654 = 30/360 (PSA)5 = 30/360 (ISDA)6 = 30/360 (European)7 = actual/365 (Japanese)8 = actual/actual (ISMA)9 = actual/360 (ISMA)10 = actual/365 (ISMA)11 = 30/360E (ISMA) 12 = actual/365 (ISDA)13 = BUS/252For more information, see basis. Default: 0 EndMonthRule End-of-month rule. A vector. 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 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. Default: 1 IssueDate Issue date for a bond. Default: If you do not specify an IssueDate, the cash flow payment dates are determined from other inputs. FirstCouponDate Date when a bond makes its first coupon payment; used when bond has an irregular first coupon period. When FirstCouponDate and LastCouponDate are both specified, FirstCouponDate takes precedence in determining the coupon payment structure. Default: If you do not specify a FirstCouponDate, the cash flow payment dates are determined from other inputs. LastCouponDate Last coupon date of a bond before the maturity date; used when bond has an irregular last coupon period. In the absence of a specified FirstCouponDate, a specified LastCouponDate determines the coupon structure of the bond. The coupon structure of a bond is truncated at the LastCouponDate, regardless of where it falls, and is followed only by the bond's maturity cash flow date. Default: If you do not specify a LastCouponDate, the cash flow payment dates are determined from other inputs. StartDate Date when a bond actually starts (the date from which a bond cash flow is considered). To make an instrument forward-starting, specify this date as a future date. If you do not specify StartDate, the effective start date is the Settle date. Default: If you do not specify StartDate, the effective start date is the Settle date. Face Face or par value. Default: 100

### Parameter–Value Pairs

Enter the following inputs only as parameter/value pairs.

 CompoundingFrequency Compounding frequency for yield calculation. By default, SIA bases (0-7) and BUS/252 use a semiannual compounding convention and ISMA bases (8-12) use an annual compounding convention. Default: SIA bases (0-7) and BUS/252 use a semiannual compounding convention and ISMA bases (8-12) use an annual compounding convention. DiscountBasis Basis used to compute the discount factors for computing the yield. The default behavior is for SIA bases to use the actual/actual day count to compute discount factors. If you use ISMA day counts and BUS/252, the specified bases are used. Default: SIA bases use the actual/actual day count to compute discount factors. LastCouponInterest Compounding convention for computing the yield of a bond in the last coupon period. This computation is based on only the last coupon and the face value to be repaid. Acceptable values are simple or compound. Default: compound

## Output Arguments

 Yield NUMBONDS-by-1 vector of the yield to maturity with semiannual compounding.

## Definitions

All nonscalar or empty matrix input arguments must be either NUMBONDS-by-1 or 1-by-NUMBONDS conforming vectors. Fill in unspecified entries input vectors with NaNs. Dates can be serial date numbers or date strings.

## Examples

expand all

### Compute Yield to Maturity for a Treasury Bond

This example shows how to compute the yield of a Treasury bond at three different price values.

```Price = [95; 100; 105];
CouponRate = 0.05;
Settle = '20-Jan-1997';
Maturity = '15-Jun-2002';
Period = 2;
Basis = 0;

Yield = bndyield(Price, CouponRate, Settle,...
Maturity, Period, Basis)
```
```Yield =

0.0610
0.0500
0.0396

```

expand all

### Algorithms

For SIA conventions, the following formula defines bond price and yield:

$PV=\frac{CF}{{\left(1+\frac{z}{f}\right)}^{TF}},$

where:

 PV = Present value of a cash flow. CF = The cash flow amount. z = The risk-adjusted annualized rate or yield corresponding to a given cash flow. The yield is quoted on a semiannual basis. f = The frequency of quotes for the yield. TF = Time factor for a given cash flow. Time is measured in semiannual periods from the settlement date to the cash flow date. In computing time factors, use SIA actual/actual day count conventions for all time factor calculations.

For ISMA conventions, the frequency of annual coupon payments determines bond price and yield.

## References

Krgin, Dragomir, Handbook of Global Fixed Income Calculations, John Wiley & Sons, 2002.

Mayle, Jan, "Standard Securities Calculations Methods: Fixed Income Securities Formulas for Analytic Measures", SIA, Vol 2, Jan 1994.

Stigum, Marcia, and Franklin Robinson, Money Market and Bond Calculations, McGraw-Hill, 1996.