Total return of fixed-coupon bond
[
calculates
the total return for fixed-coupon bonds to maturity or to a specific investment
horizon.BondEquiv
,EffectiveRate
] = bndtotalreturn(Price
,CouponRate
,Settle
,Maturity
,ReinvestRate
)
[
adds optional name-value pair arguments. BondEquiv
,EffectiveRate
] = bndtotalreturn(___,Name,Value
)
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 = 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
Price
— Clean price at settlement dateClean price at the settlement date, specified as a scalar or a
NINST
-by-1
vector.
Data Types: double
CouponRate
— Coupon rateCoupon rate, specified as a scalar or a
NINST
-by-1
vector of decimal
values.
Data Types: double
Settle
— Settlement date of fixed-coupon bondSettlement 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
— Maturity date of fixed-coupon bondMaturity 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
ReinvestRate
— Reinvestment rateReinvestment rate (the rate earned by reinvesting the coupons),
specified as scalar or a
NINST
-by-2
vector of decimal
values.
Data Types: double
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
.
[BondEquiv,EffectiveRate] =
bndtotalreturn(Price,CouponRate,Settle,Maturity,ReinvestRate,'HorizonDate','15-Nov-2021')
'HorizonDate'
— Investment horizon dateMaturity
date (default) | serial date number | date character vector | datetimeInvestment 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
'HorizonPrice'
— Price at investment horizon dateReinvestRate
(default) | numericPrice 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
'Period'
— Number of coupon payments per year2
(default) | numeric with values 0
, 1
,
2
, 3
,
4
, 6
or
12
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
'Basis'
— Day-count basis0
(actual/actual) (default) | integers of the set [0...13]
| vector of integers of the set [0...13]
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
For more information, see Basis.
Data Types: double
'EndMonthRule'
— End-of-month rule flag1
(in effect) (default) | nonnegative integer 0
or
1
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
'IssueDate'
— Bond issue dateBond 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
'FirstCouponDate'
— Irregular or normal first coupon dateIrregular 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
'LastCouponDate'
— Irregular or normal last coupon dateIrregular 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
'StartDate'
— Forward starting date of paymentsForward 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'
— Face value of bond100
(default) | numericFace 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
'CompoundingFrequency'
— Compounding frequency for yield calculation1
, 2
,
3
, 4
,
6
, or 12
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
'DiscountBasis'
— Basis used to compute the discount factors for computing the yield[0...13]
| vector of integers of the set [0...13]
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
For more information, see Basis.
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
BondEquiv
— Total return in bond equivalent basisTotal return in bond equivalent basis, returned as a
NUMBONDS
-by-1
vector.
EffectiveRate
— Total return in effective rate basisTotal return in effective rate basis, returned as a
NUMBONDS
-by-1
vector.
[1] 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.
A modified version of this example exists on your system. Do you want to open this version instead?
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
Select web siteYou can also select a web site from the following list:
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.