bondYield
Syntax
bondYield(start, maturity, issuePrice, coupon, frequency, dayCountConvention,
bondType, settlement, price, priceType, [method='newton'], [maxIter=100],
[benchmark='Excel'])
Arguments
start is a scalar or vector of DATE type, indicating the bond’s value date.
maturity is a DATE scalar or vector indicating the maturity date.
issuePrice is a numeric scalar or vector of the same length as start indicating the bond’s issue price. For discount bonds, the actual issue price must be specified (typically less than 100); for other bonds, it is usually 100.
coupon is a numeric scalar or vector indicating the annual coupon rate. For example, 0.03 indicates a 3% annual coupon.
- 0/"Once": Bullet payment at maturity.
- 1/"Annual": Annual payments.
- 2/"Semiannual": Semi-annual payments.
- 4/"Quarterly": Quarterly payments.
- 12/"Monthly": Monthly payments.
- "Thirty360US": US (NASD) 30/360
- "ActualActual" (default): actual/actual
- "Actual360": actual/360
- "Actual365": actual/365
- "Thirty360EU": European 30/360
- "FixedRate": Fixed-rate bond, where interest is paid periodically based on the coupon rate.
- "Discount": Discount bond, where no interest is paid, and the bond is issued at a discount. FV at maturity = face value.
- "ZeroCoupon": Zero-coupon bond, where interest and face value are paid at maturity. FV at maturity = face value + interest.
settlement is a DATE scalar or vector indicating the settlement date.
- When priceType is "CleanPrice", price indicates the bond's clean price.
- When priceType is "DirtyPrice", price indicates the bond's dirty price.
- "CleanPrice": Clean price.
- "DirtyPrice": Dirty price.
- "newton" (default): Newton algorithm.
- "brent": Brent algorithm.
- "nm": Nelder-Mead simplex algorithm.
- "bfgs": BFGS algorithm.
- "lbfgs": LBFGS algorithm.
maxIter (optional) is a positive integer or a vector of positive integers indicating the maximum number of iterations. The default value is 100.
benchmark (optional) is a STRING scalar indicating the reference algorithm. Currently, only "Excel" (the algorithm used in Excel) is supported.
Details
Calculate the bond yield for each 100 face value of a bond based on its clean price or dirty price.
Return value: A DOUBLE scalar or vector.
Note:
- If there is one coupon period or less until redemption, YIELD is calculated as
follows:
where:-
- A = number of days from the beginning of the coupon period to the settlement date (accrued days).
- DSR = number of days from the settlement date to the redemption date.
- E = number of days in the coupon period.
-
-
If there is more than one coupon period until redemption, bond yield is calculated through a hundred iterations. The resolution uses the Newton method. The yield is changed until the estimated price given the yield is close to price.
-
An annual coupon rate is used by default.
Examples
bondYield(start=2023.01.01, maturity=2030.12.31, issuePrice=100, coupon=0.05, frequency=1, dayCountConvention="ActualActual", bondType="FixedRate", settlement=2023.04.01, price=100.2143, priceType="CleanPrice", method = ['newton', 'nm', 'brentq', 'bfgs','lbfgs'])
// output: [0.049624,0.049624,0.049624,0.049624,0.049629]