# 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

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 optional name-value pair inputs: `Period`, `Basis`, `EndMonthRule`, `IssueDate`,`FirstCouponDate`, `LastCouponDate`, `StartDate`,`Face`, `CompoundingFrequency`, `DiscountBasis`, and `LastCouponInterest`.

## Syntax

``Yield = bndyield(Price,CouponRate,Settle,Maturity)``
``Yield = bndyield(___,Name,Value)``

## Description

example

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

example

````Yield = bndyield(___,Name,Value)` adds optional name-value arguments. ```

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

## Input Arguments

collapse all

Clean price of the bond (current price without accrued interest), specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector.

Data Types: `double`

Annual percentage rate used to determine the coupons payable on a bond, specified as decimal using a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector.

Data Types: `double`

Settlement date of the bond, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using serial date numbers, date character vectors, or datetime arrays. The `Settle` date must be before the `Maturity` date.

Data Types: `double` | `char` | `datetime`

Maturity date of the bond, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using serial date numbers, date character vectors, or datetime arrays.

Data Types: `double` | `char` | `datetime`

### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Example: ```Yield = bndyield(Price,CouponRate,Settle,Maturity,'Period',4,'Basis',9)```

collapse all

Number of coupon payments per year, specified as scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using the values: `0`, `1`, `2`, `3`, `4`, `6`, or `12`.

Data Types: `double`

Day-count of the instrument, specified as scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using a supported value:

• 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

Data Types: `double`

End-of-month rule flag, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` 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.

Data Types: `logical`

Bond Issue date, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using serial date numbers, date character vectors, or datetime arrays.

If you do not specify an `IssueDate`, the cash flow payment dates are determined from other inputs.

Data Types: `double` | `char` | `datetime`

Irregular or normal first coupon date, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using serial date numbers, date character vectors, or datetime arrays.

If you do not specify a `FirstCouponDate`, the cash flow payment dates are determined from other inputs.

Data Types: `double` | `char` | `datetime`

Irregular or normal last coupon date, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using serial date numbers, date character vectors, or datetime arrays.

If you do not specify a `LastCouponDate`, the cash flow payment dates are determined from other inputs.

Data Types: `double` | `char` | `datetime`

Forward starting date of payments, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using serial date numbers, date character vectors, or datetime arrays.

If you do not specify a `StartDate`, the effective start date is the `Settle` date.

Data Types: `double` | `char` | `datetime`

Face value of the bond, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector.

Data Types: `double`

Compounding frequency for yield calculation, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector. Values are:

• `1` — Annual compounding

• `2` — Semiannual compounding

• `3` — Compounding three times per year

• `4` — Quarterly compounding

• `6` — Bimonthly compounding

• `12` — Monthly compounding

### Note

By default, SIA bases (`0`-`7`) and `BUS/252` use a semiannual compounding convention and ICMA bases (`8`-`12`) use an annual compounding convention.

Data Types: `double`

Basis used to compute the discount factors for computing the yield, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector. Values are:

• 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

### Note

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.

Data Types: `double`

Compounding convention for computing the yield of a bond in the last coupon period, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector. This is based on only the last coupon and the face value to be repaid. Acceptable values are:

• `simple`

• `compound`

Data Types: `char` | `cell`

## Output Arguments

collapse all

Yield to maturity with semiannual compounding, returned as a `NUMBONDS`-by-`1` vector.

collapse all

### Price and Yield Conventions

The `Price` and `Yield` are related to different formulae for SIA and ICMA conventions.

For SIA conventions, `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 semiannual 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

[1] Krgin, D. Handbook of Global Fixed Income Calculations. Wiley, 2002.

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

[3] Stigum, M., Robinson, F. Money Market and Bond Calculation. McGraw-Hill, 1996.