bndtotalreturn
Total return of fixed-coupon bond
Syntax
Description
[
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
)
Examples
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 = 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
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
Input Arguments
Price
— Clean price at settlement date
matrix
Clean price at the settlement date, specified as a scalar or a
NINST
-by-1
vector.
Data Types: double
CouponRate
— Coupon rate
decimal
Coupon rate, specified as a scalar or a
NINST
-by-1
vector of decimal
values.
Data Types: double
Settle
— Settlement date of fixed-coupon bond
datetime array | string array | date character vector
Settlement date of the fixed-coupon bond, specified as scalar or a
NINST
-by-1
vector using a datetime
array, string array, or date character vectors. 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
.
To support existing code, bndtotalreturn
also
accepts serial date numbers as inputs, but they are not recommended.
Data Types: char
| string
| datetime
Maturity
— Maturity date of fixed-coupon bond
datetime array | string array | date character vector
Maturity date of the fixed-coupon bond, specified as scalar or a
NINST
-by-1
vector using a datetime
array, string array, or date character vectors.
To support existing code, bndtotalreturn
also
accepts serial date numbers as inputs, but they are not recommended.
Data Types: char
| string
| datetime
ReinvestRate
— Reinvestment rate
decimal
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 Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: [BondEquiv,EffectiveRate] =
bndtotalreturn(Price,CouponRate,Settle,Maturity,ReinvestRate,'HorizonDate','15-Nov-2021')
HorizonDate
— Investment horizon date
Maturity
date (default) | datetime array | string array | date character vector
Investment horizon date, specified as the comma-separated pair
consisting of 'HorizonDate'
and a scalar or a
NINST
-by-1
vector using a
datetime array, string array, or date character vectors.
If HorizonDate
is unspecified, the total return
is calculated to Maturity
.
To support existing code, bndtotalreturn
also
accepts serial date numbers as inputs, but they are not recommended.
Data Types: char
| string
| datetime
HorizonPrice
— Price at investment horizon date
calculated based on
ReinvestRate
(default) | numeric
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
Period
— Number of coupon payments per year
2
(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 basis
0
(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 flag
1
(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 date
datetime array | string array | date character vector
Bond Issue date, specified as the comma-separated pair consisting
of 'IssueDate'
and a scalar or a
NINST
-by-1
vector using a
datetime array, string array, or date character vectors.
If you do not specify an IssueDate
, the cash
flow payment dates are determined from other inputs.
To support existing code, bndtotalreturn
also
accepts serial date numbers as inputs, but they are not recommended.
Data Types: char
| string
| datetime
FirstCouponDate
— Irregular or normal first coupon date
datetime array | string array | date character vector
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 a datetime array, string array, or date character
vectors.
If you do not specify a FirstCouponDate
, the
cash flow payment dates are determined from other inputs.
To support existing code, bndtotalreturn
also
accepts serial date numbers as inputs, but they are not recommended.
Data Types: char
| string
| datetime
LastCouponDate
— Irregular or normal last coupon date
datetime array | string array | date character vector
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 a datetime array, string array, or date character
vectors.
If you do not specify a LastCouponDate
, the
cash flow payment dates are determined from other inputs.
To support existing code, bndtotalreturn
also
accepts serial date numbers as inputs, but they are not recommended.
Data Types: char
| string
| datetime
StartDate
— Forward starting date of payments
datetime array | string array | date character vector
Forward starting date of payments, specified as the
comma-separated pair consisting of 'StartDate'
and a
scalar or a NINST
-by-1
vector
using a datetime array, string array, or date character vectors.
If you do not specify a StartDate
, the
effective start date is the Settle
date.
To support existing code, bndtotalreturn
also
accepts serial date numbers as inputs, but they are not recommended.
Data Types: char
| string
| datetime
Face
— Face value of bond
100
(default) | numeric
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
CompoundingFrequency
— Compounding frequency for yield calculation
integer with value of 1
, 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 compounding2
— Semiannual compounding3
— Compounding three times per year4
— Quarterly compounding6
— Bimonthly compounding12
— 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
integers of the set [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
Output Arguments
BondEquiv
— Total return in bond equivalent basis
numeric
Total return in bond equivalent basis, returned as a
NUMBONDS
-by-1
vector.
EffectiveRate
— Total return in effective rate basis
numeric
Total return in effective rate basis, returned as a
NUMBONDS
-by-1
vector.
References
[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.
Version History
Introduced in R2012bR2022b: Serial date numbers not recommended
Although bndtotalreturn
supports serial date numbers,
datetime
values are recommended instead. The
datetime
data type provides flexible date and time
formats, storage out to nanosecond precision, and properties to account for time
zones and daylight saving time.
To convert serial date numbers or text to datetime
values, use the datetime
function. For example:
t = datetime(738427.656845093,"ConvertFrom","datenum"); y = year(t)
y = 2021
There are no plans to remove support for serial date number inputs.
MATLAB Command
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.
Select a Web Site
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: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)