# bndtotalreturn

Total return of fixed-coupon bond

## Syntax

``[BondEquiv,EffectiveRate] = bndtotalreturn(Price,CouponRate,Settle,Maturity,ReinvestRate)``
``[BondEquiv,EffectiveRate] = bndtotalreturn(___,Name,Value)``

## Description

example

````[BondEquiv,EffectiveRate] = bndtotalreturn(Price,CouponRate,Settle,Maturity,ReinvestRate)`calculates the total return for fixed-coupon bonds to maturity or to a specific investment horizon.```
````[BondEquiv,EffectiveRate] = bndtotalreturn(___,Name,Value)` adds optional name-value pair arguments. ```

## Examples

collapse all

Use `bndtotalreturn` to compute the total return for a fixed-coupon bond, given an investment horizon date.

Define fixed-coupon bond.

```Price = 101; CouponRate = 0.05; Settle = '15-Nov-2011'; Maturity = '15-Nov-2031'; ReinvestRate = 0.04;```

```[BondEquiv, EffectiveRate] = bndtotalreturn(Price, CouponRate, ... Settle, Maturity, ReinvestRate)```
```BondEquiv = 0.0460 ```
```EffectiveRate = 0.0466 ```

Specify an investment horizon.

```HorizonDate = '15-Nov-2021'; [BondEquiv, EffectiveRate] = bndtotalreturn(Price, CouponRate, ... Settle, Maturity, ReinvestRate, 'HorizonDate', HorizonDate)```
```BondEquiv = 0.0521 ```
```EffectiveRate = 0.0528 ```

Perform scenario analysis on the reinvestment rate.

```ReinvestRate = [0.03; 0.035; 0.04; 0.045; 0.05]; [BondEquiv, EffectiveRate] = bndtotalreturn(Price, CouponRate, ... Settle, Maturity, ReinvestRate, 'HorizonDate', HorizonDate)```
```BondEquiv = 5×1 0.0557 0.0538 0.0521 0.0505 0.0490 ```
```EffectiveRate = 5×1 0.0565 0.0546 0.0528 0.0511 0.0496 ```

Use `bndtotalreturn` with `datetime` inputs to compute the total return for a fixed-coupon bond, given an investment horizon date.

```Price = 101; CouponRate = 0.05; Settle = datetime('15-Nov-2011','Locale','en_US'); Maturity = datetime('15-Nov-2031','Locale','en_US'); HorizonDate = datetime('15-Nov-2021','Locale','en_US'); ReinvestRate = 0.04; [BondEquiv, EffectiveRate] = bndtotalreturn(Price, CouponRate, ... Settle, Maturity, ReinvestRate, 'HorizonDate', HorizonDate)```
```BondEquiv = 0.0521 ```
```EffectiveRate = 0.0528 ```

## Input Arguments

collapse all

Clean price at the settlement date, specified as a scalar or a `NINST`-by-`1` vector.

Data Types: `double`

Coupon rate, specified as a scalar or a `NINST`-by-`1` vector of decimal values.

Data Types: `double`

Settlement date of the fixed-coupon bond, specified as scalar or a `NINST`-by-`1` vector of serial date numbers, date character vectors, or datetime arrays. If supplied as a `NINST`-by-`1` vector of dates, settlement dates can be different, as long as they are before the `Maturity` date and `HorizonDate`.

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

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

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

Reinvestment rate (the rate earned by reinvesting the coupons), specified as scalar or a `NINST`-by-`2` vector of decimal values.

Data Types: `double`

### 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 quotes. You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Example: ```[BondEquiv,EffectiveRate] = bndtotalreturn(Price,CouponRate,Settle,Maturity,ReinvestRate,'HorizonDate','15-Nov-2021')```

Investment horizon date, specified as the comma-separated pair consisting of `'HorizonDate'` and a scalar or a `NINST`-by-`1` vector using serial date numbers, date character vectors, or datetime arrays.

If `HorizonDate` is unspecified, the total return is calculated to `Maturity`.

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

Price at investment horizon date, specified as the comma-separated pair consisting of `'HorizonPrice'` and a scalar or a `NINST`-by-`1` vector.

If `HorizonPrice` is unspecified, the price at the `HorizonDate` is calculated based on the `ReinvestRate`. If the `HorizonDate` equals the `Maturity` date, the `HorizonPrice` is ignored and the total return to maturity is calculated based on the `Face` value.

Data Types: `double`

Number of coupon payments per year, specified as the comma-separated pair consisting of `'Period'` and a scalar or a `NINST`-by-`1` vector using the values: `0`, `1`, `2`, `3`, `4`, `6`, or `12`.

Data Types: `double`

Day-count basis, specified as the comma-separated pair consisting of `'Basis'` and a scalar or a `NINST`-by-`1` 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

Data Types: `double`

End-of-month rule flag, specified as the comma-separated pair consisting of `'EndMonthRule'` and a scalar or a `NINST`-by-`1` 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 the comma-separated pair consisting of `'IssueDate'` and a scalar or a `NINST`-by-`1` 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 the comma-separated pair consisting of `'FirstCouponDate'` and a scalar or a `NINST`-by-`1` 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 the comma-separated pair consisting of `'LastCouponDate'` and a scalar or a `NINST`-by-`1` 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 the comma-separated pair consisting of `'StartDate'` and a scalar or a `NINST`-by-`1` 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 the comma-separated pair consisting of `'Face'` and a scalar or a `NINST`-by-`1` vector.

Data Types: `double`

Compounding frequency for yield calculation, specified as the comma-separated pair consisting of `'CompoundingFrequency'` and a scalar or a `NINST`-by-`1` vector.

• `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 the comma-separated pair consisting of `'DiscountBasis'` and a scalar or a `NINST`-by-`1` 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

The default behavior is for SIA bases (`0`-`7`) to use the `actual/actual` day count to compute discount factors, and for ICMA day counts (`8``12`) and `BUS/252` to use the specified `DiscountBasis`.

Data Types: `double`

## Output Arguments

collapse all

Total return in bond equivalent basis, returned as a `NUMBONDS`-by-`1` vector.

Total return in effective rate basis, returned as a `NUMBONDS`-by-`1` vector.

 Fabozzi, Frank J., Mann, Steven V. Introduction to Fixed Income Analytics: Relative Value Analysis, Risk Measures and Valuation. John Wiley and Sons, New York, 2010.