bondCalculator

bondCalculator(start, maturity, issuePrice, coupon, frequency, dayCountConvention, bondType, calendar, businessDayConvention, settlement, price, priceType, [calcRisk=false], [benchmark='Qeubee'])

This function performs mutual conversion among a bond's yield to maturity, clean price, and dirty price, and supports the calculation of duration and convexity, and other risk indicators.

Return Value: A dictionary or tuple.

start is a scalar or vector of DATE type, indicating the bond’s value date.

maturity is a scalar or vector of DATE type of the same length as start, indicating the bond's 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 coupon rate of the bond. For example, 0.03 indicates a 3% annual coupon.

calendar is a STRING scalar indicating the trading calendar. Currently, only "CFET" is supported, representing the bond trading calendar of the China Interbank Bond Market (for bonds ending with .IB).

businessDayConvention is a STRING scalar indicating how cash flows that fall on a non-trading day are treated. Currently, only "Unadjusted" is supported.

settlement is a scalar or vector of DATE type, indicating the bond's settlement date. The settlement date is the date after the issue date when the security is traded to the buyer.

benchmark (optional) is a STRING scalar indicating the he algorithm benchmark. Currently, only "Qeubee" (for domestic bond calculation) is supported.

A dictionary or tuple.

Example 1: Calculate the price, yield to maturity, accrued interest, and risk metrics for a fixed-rate bond.

bondCalculator(start=2022.07.15, maturity=2072.07.15, issuePrice=100, coupon=0.034, frequency="Semiannual", dayCountConvention="ActualActual", bondType="FixedRate", calendar="CFET", businessDayConvention="Unadjusted", settlement=2025.04.10, price=0.02, priceType="YTM", calcRisk=true);

/* Output:
pvbp->0.3902
ytm->0.0200
macaulayDuration->27.4761
dirtyPrice->143.4689
accruedInterest->0.7983
cleanPrice->142.6705
modifiedDuration->27.2041
convexity->1025.4003
*/


bondCalculator(start=2022.07.15, maturity=2072.07.15, issuePrice=100, coupon=0.034, frequency="Semiannual", dayCountConvention="ActualActual", bondType="FixedRate", calendar="CFET", businessDayConvention="Unadjusted", settlement=2072.04.18, price=100.2143, priceType="CleanPrice", calcRisk=false);

/* Output:
accruedInterest->0.8780
cleanPrice->100.2143
ytm->0.0250
dirtyPrice->101.0923
*/

Example 2: Calculate the price, yield to maturity, accrued interest for a zero-coupon bond.

bondCalculator(start=2025.01.09, maturity=2026.02.05, issuePrice=100, coupon=0.0119, frequency="Annual", dayCountConvention="ActualActual", bondType="ZeroCoupon", calendar="CFET",  businessDayConvention="Unadjusted", settlement=2025.04.10, price=0.025, priceType="YTM", calcRisk=false);

/* Output:
accruedInterest->0.2966
cleanPrice->98.9355
ytm->0.0250
dirtyPrice->99.2322
*/

Example 3. Calculate the price, yield to maturity, accrued interest, and risk metrics of a discount bond.

bondCalculator(start=2025.02.13, maturity=2025.05.15, issuePrice=99.663, coupon=0.0, frequency="Once", dayCountConvention="ActualActual", bondType="Discount", calendar="CFET", businessDayConvention="Unadjusted", settlement=2025.04.10, price=0.02, priceType="YTM", calcRisk=true);

/* Output:
pvbp->0.0009
ytm->0.0200
macaulayDuration->0.0958
dirtyPrice->99.8085
accruedInterest->0.2073
cleanPrice->99.6012
modifiedDuration->0.0957
convexity->0.0183
*/  

Example 4. Calculate the price, yield to maturity, accrued interest, and risk metrics for multiple bonds at once.

result = bondCalculator(start=[2025.02.13, 2025.01.09, 2022.07.15], maturity=[2025.05.15, 2026.02.05, 2072.07.15], issuePrice=[99.663, 100, 100], coupon=[0.0, 0.0119, 0.034], frequency=["Once", "Annual", "Semiannual"], dayCountConvention=["ActualActual", "ActualActual", "ActualActual"], bondType=["Discount", "ZeroCoupon", "FixedRate"], calendar=["CFET", "CFET", "CFET"], businessDayConvention=["Unadjusted", "Unadjusted", "Unadjusted"], settlement=[2025.04.10, 2025.04.10, 2072.04.18], price=[0.02, 0.025, 100.2143], priceType=["YTM", "YTM", "CleanPrice"], calcRisk=true);

print result

/* Output:
(dirtyPrice->99.808586272901294
cleanPrice->99.601201657516682
ytm->0.02
accruedInterest->0.207384615384617
macaulayDuration->0.095890410958904
modifiedDuration->0.095706863549357
convexity->0.018319607460911
pvbp->0.000955236674747
,dirtyPrice->99.232212603180983
cleanPrice->98.935527671674137
ytm->0.025
accruedInterest->0.296684931506849
macaulayDuration->0.824657534246575
modifiedDuration->0.80799946312328
convexity->1.305726264815019
pvbp->0.008017957450791
,dirtyPrice->101.092321978021971
cleanPrice->100.214299999999994
ytm->0.025000792220527
accruedInterest->0.878021978021978
macaulayDuration->0.240437158469945
modifiedDuration->0.239000497930427
convexity->0.114242476021984
pvbp->0.002416111528969
)
*/ 

Related Functions: bondAccrInt, bondConvexity, bondDirtyPrice, bondYield