Documentation

bndtotalreturn

Total return of fixed-coupon bond

Syntax

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

Description

[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(Price,CouponRate,Settle,Maturity,
ReinvestRate,Name,Value)
calculates the total return for fixed-coupon bonds to maturity or to a specific investment horizon with additional options specified by one or more Name,Value pair arguments.

Input Arguments

Price

NINST-by-1 matrix for the clean price at the settlement date.

CouponRate

NINST-by-1 matrix for the coupon rate in decimal form.

Settle

NINST-by-1 vector for the settlement date of the fixed-coupon bond.

Maturity

NINST-by-1 vector of dates representing the maturity date of the fixed-coupon bond.

ReinvestRate

NINST-by-1 vector for the reinvestment rate in decimal form. This is the rate earned by reinvesting the coupons.

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.

'HorizonDate'

Investment horizon date. If unspecified, the total return is calculated to maturity.

'HorizonPrice'

Price at investment horizon date. If unspecified, the price at horizon will be calculated based on the reinvestment rate. If the horizon date equals the maturity date, this price is ignored and the total return to maturity is calculated based on the face value.

'Period'

Number of coupon payments per year. Values are: 0, 1, 2 , 3, 4, 6, 12.

Default: 2

'Basis'

NINST-by-1 vector representing day-count basis:

  • 0 = actual/actual

  • 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/actual (ISDA)

  • 13 = BUS/252

For more information, see basis.

Default: 0 (actual/actual)

'EndMonthRule'

Value for the end-of-month rule.

  • 0 – Rule is not in effect for the bond(s).

  • 1 – Rule is in effect for the bond(s). This means that a security that pays coupon interest on the last day of the month will always make payment on the last day of the month.

Default: 1 (in effect)

'IssueDate'

Bond issue date.

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

'FirstCouponDate'

Irregular or normal first coupon date.

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

'LastCouponDate'

Irregular or normal last coupon date.

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

'StartDate'

Forward starting date of payments.

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

'Face'

Face value of the bond.

Default: 100

'CompoundingFrequency'

Compounding frequency for yield calculation. By default, SIA bases (0-7) and BUS/252 use a semi-annual 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, and for ISMA day counts (8-12) and BUS/252 to use the specified basis.

Output Arguments

BondEquiv

NUMBONDS-by-1 vector for the total return in bond equivalent basis.

EffectiveRate

NUMBONDS-by-1 vector for the total return in effective rate basis.

Examples

expand all

Compute the Total Return of a Fixed-Coupon Bond

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;

Calculate the total return to maturity.

[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 =

    0.0557
    0.0538
    0.0521
    0.0505
    0.0490


EffectiveRate =

    0.0565
    0.0546
    0.0528
    0.0511
    0.0496

References

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.

Was this topic helpful?