financial.macaulay_duration
===========================

.. py:module:: financial.macaulay_duration

.. autoapi-nested-parse::

   Calculate the Macaulay Duration of a bond.
   Reference: https://www.investopedia.com/terms/m/macaulayduration.asp



Functions
---------

.. autoapisummary::

   financial.macaulay_duration.macaulay_duration


Module Contents
---------------

.. py:function:: 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