.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "api/gallery/fixed_income/duration/plot_01_macaulay_duration.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_api_gallery_fixed_income_duration_plot_01_macaulay_duration.py>`
        to download the full example code or to run this example in your browser via JupyterLite.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_api_gallery_fixed_income_duration_plot_01_macaulay_duration.py:


Macaulay duration
=================

Frederick Macaulay (1938) measured a bond's "length" not by its maturity
but by the present-value-weighted average time to its payments,

.. math:: D = \frac{1}{P}\sum_i t_i \, c_i \, e^{-y t_i}.

Drawn as bars of present value, the duration is the balance point of the
bars. Coupons pull it in front of maturity: the higher the coupon, the
shorter the bond.

.. GENERATED FROM PYTHON SOURCE LINES 16-22

.. code-block:: Python

    import matplotlib.pyplot as plt
    import numpy as np

    from financialkit.fixed_income import bond_cash_flows, macaulay_duration
    from financialkit.fixed_income.visualizers import plot_cash_flows








.. GENERATED FROM PYTHON SOURCE LINES 23-25

The duration is the fulcrum of the present-value bars
-----------------------------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 25-35

.. code-block:: Python


    y = 0.06
    cf = bond_cash_flows(100.0, 0.08, 10.0, freq=2)
    D = macaulay_duration(cf, y)
    ax = plot_cash_flows(cf, y)
    ax.axvline(D, color="k", ls="--")
    ax.annotate(f"D = {D:.2f} years", (D, ax.get_ylim()[1] * 0.8), xytext=(5, 0), textcoords="offset points")
    ax.set_title("10-year 8% bond at a 6% yield")
    ax.set_yscale("log")




.. image-sg:: /api/gallery/fixed_income/duration/images/sphx_glr_plot_01_macaulay_duration_001.png
   :alt: 10-year 8% bond at a 6% yield
   :srcset: /api/gallery/fixed_income/duration/images/sphx_glr_plot_01_macaulay_duration_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 36-41

Duration against maturity for several coupons
---------------------------------------------
A zero-coupon bond's duration is its maturity (the diagonal). Coupon
bonds fall below it and level off near :math:`1/y`, Macaulay's
perpetuity limit for a continuously compounded yield.

.. GENERATED FROM PYTHON SOURCE LINES 41-51

.. code-block:: Python


    maturities = np.linspace(0.5, 50, 100)
    fig, ax = plt.subplots()
    for c in (0.0, 0.03, 0.06, 0.12):
        ax.plot(maturities, [macaulay_duration(bond_cash_flows(100.0, c, T), y) for T in maturities], label=f"coupon {100 * c:.0f}%")
    ax.axhline(1 / y, color="0.5", ls=":", label="1/y")
    ax.set_xlabel("maturity (years)")
    ax.set_ylabel("Macaulay duration (years)")
    ax.legend()
    plt.show()



.. image-sg:: /api/gallery/fixed_income/duration/images/sphx_glr_plot_01_macaulay_duration_002.png
   :alt: plot 01 macaulay duration
   :srcset: /api/gallery/fixed_income/duration/images/sphx_glr_plot_01_macaulay_duration_002.png
   :class: sphx-glr-single-img






.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.072 seconds)


.. _sphx_glr_download_api_gallery_fixed_income_duration_plot_01_macaulay_duration.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: lite-badge

      .. image:: images/jupyterlite_badge_logo.svg
        :target: ../../../../lite/lab/index.html?path=api/gallery/fixed_income/duration/plot_01_macaulay_duration.ipynb
        :alt: Launch JupyterLite
        :width: 150 px

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_01_macaulay_duration.ipynb <plot_01_macaulay_duration.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_01_macaulay_duration.py <plot_01_macaulay_duration.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_01_macaulay_duration.zip <plot_01_macaulay_duration.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_