diff --git a/financial/macaulay_duration.py b/financial/macaulay_duration.py new file mode 100644 index 000000000000..ce559f57aad9 --- /dev/null +++ b/financial/macaulay_duration.py @@ -0,0 +1,77 @@ +""" +Calculate the Macaulay Duration of a bond. +Reference: https://www.investopedia.com/terms/m/macaulayduration.asp +""" + +from __future__ import annotations + + +def macaulay_duration( + face_value: float, + coupon_rate: float, + periods: int, + yield_rate: float, +) -> float: + """ + Calculates the Macaulay Duration of a bond. + + :param face_value: The final payout amount of the bond. + :param coupon_rate: The annual interest rate paid by the bond. + :param periods: The number of years until the bond matures. + :param yield_rate: The current market interest rate used to discount + future cash flows. + :return: The Macaulay Duration of the bond in years. + + >>> round(macaulay_duration(1000.0, 0.05, 8, 0.04), 2) + 6.83 + >>> round(macaulay_duration(987435.34, 0.07, 5, 0.038), 2) + 4.43 + >>> round(macaulay_duration(3564.2, 0.023, 6, 0.071), 2) + 5.62 + >>> macaulay_duration(-1000.0, 0.05, 8, 0.04) + Traceback (most recent call last): + ... + ValueError: face_value must be > 0 + >>> macaulay_duration(1000.0, -0.05, 8, 0.04) + Traceback (most recent call last): + ... + ValueError: coupon_rate must be >= 0 + >>> macaulay_duration(1000.0, 0.05, 0, 0.04) + Traceback (most recent call last): + ... + ValueError: periods must be > 0 + >>> macaulay_duration(1000.0, 0.05, 8, -0.04) + Traceback (most recent call last): + ... + ValueError: yield_rate must be > 0 + """ + if face_value <= 0: + raise ValueError("face_value must be > 0") + if coupon_rate < 0: + raise ValueError("coupon_rate must be >= 0") + if periods < 1: + raise ValueError("periods must be > 0") + if yield_rate <= 0: + raise ValueError("yield_rate must be > 0") + + total_present_value: float = 0.0 + total_time_weighted_value: float = 0.0 + + for period in range(1, periods + 1): + cash_flow: float = face_value * coupon_rate + ( + face_value if period == periods else 0 + ) + + time_weighted_value: float = (period * cash_flow) / pow(1 + yield_rate, period) + total_time_weighted_value += time_weighted_value + + present_value: float = cash_flow / pow(1 + yield_rate, period) + total_present_value += present_value + + return total_time_weighted_value / total_present_value + + +if __name__ == "__main__": + import doctest + + doctest.testmod()