# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

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

 Note:   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 `NaN`s. Dates can be serial date numbers, date character vectors, or datetime arrays.

## 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, date character vectors, or datetime arrays. `Settle` must be earlier than `Maturity`. `Maturity` Maturity date. A vector of serial date numbers, date character vectors, or datetime arrays.

### 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 (ICMA)9 = actual/360 (ICMA)10 = actual/365 (ICMA)11 = 30/360E (ICMA) 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, specified as a serial date number, date character vector, or datetime array. 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, specified as a serial date number, date character vector, or datetime array. `FirstCouponDate` is used when a 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, specified as a serial date number, date character vector, or datetime array. `LastCouponDate` is 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, specified as a serial date number, date character vector, or datetime array, 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. Possible values include: `1`, `2`, `3`, `4`, `6`, `12`. Default: SIA bases (0–7) and BUS/252 use a semiannual compounding convention and ICMA bases (8–12) use an annual compounding convention. `DiscountBasis` Basis used to compute the discount factors for computing the yield. The possible values for `DiscountBasis` are: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 (ICMA)9 = actual/360 (ICMA)10 = actual/365 (ICMA)11 = 30/360E (ICMA) 12 = actual/365 (ISDA)13 = BUS/252 If a SIA day-count basis is defined in the `Basis` input argument and there is no value assigned for `DiscountBasis`, the default behavior is for SIA bases to use the actual/actual day count to compute discount factors. If an ICMA day-count basis or BUS/252 is defined in the `Basis` input argument and there is no value assigned for `DiscountBasis`, the specified bases from the`Basis` input argument 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.

## Examples

collapse all

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 ```

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

```Price = [95; 100; 105]; CouponRate = 0.05; Settle = datetime('20-Jan-1997','Locale','en_US'); Maturity = datetime('15-Jun-2002','Locale','en_US'); Period = 2; Basis = 0; Yield = bndyield(Price, CouponRate, Settle,... Maturity, Period, Basis)```
```Yield = 0.0610 0.0500 0.0396 ```

Compute the yield of a Treasury bond.

```Price = [95; 100; 105]; CouponRate = 0.0345; Settle = '15-May-2016'; Maturity = '02-Feb-2026'; Period = 2; Basis = 1; format long Yield = bndyield(Price,CouponRate,Settle,Maturity,Period,Basis)```
```Yield = 0.040764403932618 0.034482347625316 0.028554719853118 ```

Using the same data, compute the yield of a Treasury bond using the same basis for discounting and generating the cash flows.

```DiscountBasis = 1; Yield = bndyield(Price,CouponRate,Settle,Maturity,'Period',Period,'Basis',Basis, ... 'DiscountBasis',DiscountBasis)```
```Yield = 0.040780176658036 0.034495592361619 0.028565614029497 ```

## Algorithms

For SIA conventions, the Price and Yield are related by the formula:

` Price + Accrued Interest = sum(Cash_Flow*(1+Yield/2)^(-Time)) `
where the sum is over the bond's cash flows and corresponding times in units of semi-annual coupon periods.

For ICMA conventions, the Price and Yield are related by the formula:

` Price + Accrued Interest = sum(Cash_Flow*(1+Yield)^(-Time))`

## 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 ICMA 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.