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, specified as a serial date number, date character vector, or datetime array.

Maturity

NINST-by-1 vector of dates representing the maturity date of the fixed-coupon bond, specified as a serial date number, date character vector, or datetime array.

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, specified as a serial date number, date character vector, or datetime array. If unspecified, the total return is calculated to maturity.

'HorizonPrice'

Price at investment horizon date. If unspecified, the price at horizon is 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/365 (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, 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'

Irregular or normal first coupon date, specified as a serial date number, date character vector, or datetime array.

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, specified as a serial date number, date character vector, or datetime array.

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

'StartDate'

Forward starting date of payments, specified as a serial date number, date character vector, or datetime array.

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 ICMA 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 ICMA day counts (812) 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

collapse 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

Compute the Total Return of a Fixed-Coupon Bond Using datetime Inputs

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

Related Examples

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.

Introduced in R2012b

Was this topic helpful?