:orphan:

Examples
========

This gallery walks through every public feature of ``financialkit.fixed_income``:
bond prices and yields, duration and convexity, yield-curve construction,
immunization and swaps. Each script illustrates one dated breakthrough from
the :doc:`history page </history/fixed_income_breakthroughs>`.

See also the narrative tutorial:

- :doc:`/tutorials/yield_curve_end_to_end`

Each script in this gallery is self-contained and can be run directly with
``python examples/fixed_income/<section>/<script>.py``.

Sections
--------

- **bonds** -- yield to maturity, accrued interest, and a coupon bond as a
  portfolio of STRIPS.
- **duration** -- Macaulay, modified and Fisher-Weil duration, convexity,
  and key rate durations.
- **curves** -- forward rates, McCulloch splines, bootstrapping,
  Nelson-Siegel and Svensson fits, and the principal components of curve
  moves.
- **immunization** -- Redington's conditions and the Fong-Vasicek
  :math:`M^2` bound.
- **swaps** -- the IBM-World Bank currency swap and the plain-vanilla
  interest-rate swap.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Bonds
-----

Pricing a bond off a single yield and off a curve of zero-coupon prices.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Sidney Homer and Martin Leibowitz&#x27;s Inside the Yield Book (1972) taught a generation of bond traders to think in yield to maturity: the single rate that discounts a bond&#x27;s cash flows to its price. The script inverts prices for yields, shows a bond pulled to par as it ages at a constant yield, and separates the dirty price, which drops by a coupon on each payment date, from the quoted clean price.">

.. only:: html

  .. image:: /api/gallery/fixed_income/bonds/images/thumb/sphx_glr_plot_01_yield_to_maturity_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/bonds/plot_01_yield_to_maturity`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Inside the Yield Book: yield to maturity</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In February 1985 the US Treasury&#x27;s STRIPS program (Separate Trading of Registered Interest and Principal of Securities) let dealers split a note into one zero-coupon security per payment date. A coupon bond is then exactly a portfolio of zeros. If the strips are worth more than the bond, dealers buy bonds and strip them. If they are worth less, dealers buy strips and reconstitute the bond. Either trade pulls the two prices back together.">

.. only:: html

  .. image:: /api/gallery/fixed_income/bonds/images/thumb/sphx_glr_plot_02_strips_zero_coupon_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/bonds/plot_02_strips_zero_coupon`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">STRIPS: a bond as a portfolio of zeros</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Yield curves
------------

Forward rates, bootstrapped, spline and parametric curves, and the factors
that move them.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Friedrich Lutz (1940) read the term structure as a sequence of expected future short rates. The forward rate for the period from t_1 to t_2 is what the zero curve locks in today,">

.. only:: html

  .. image:: /api/gallery/fixed_income/curves/images/thumb/sphx_glr_plot_01_lutz_forward_rates_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/curves/plot_01_lutz_forward_rates`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Lutz: forward rates</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Huston McCulloch (1971) fitted the discount function itself with a spline, d(t) = 1 + \sum_j a_j g_j(t). Because every bond price is linear in d, it is also linear in the coefficients, so the fit is ordinary least squares on a cross-section of bond prices. His 1971 paper used quadratic splines; the cubic version (1975) gives smooth forward rates.">

.. only:: html

  .. image:: /api/gallery/fixed_income/curves/images/thumb/sphx_glr_plot_02_mcculloch_spline_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/curves/plot_02_mcculloch_spline`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">McCulloch's spline discount function</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="With bonds that pay on common dates, Carleton and Cooper (1976) noted that prices are linear in the discount factors, P = C d. Solving that system one bond at a time, shortest first, is bootstrapping: each bond adds one zero rate at its maturity. With more bonds than dates the same system is solved by least squares.">

.. only:: html

  .. image:: /api/gallery/fixed_income/curves/images/thumb/sphx_glr_plot_03_bootstrapping_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/curves/plot_03_bootstrapping`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Carleton-Cooper bootstrapping</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Nelson and Siegel (1987) described the whole yield curve with four numbers:">

.. only:: html

  .. image:: /api/gallery/fixed_income/curves/images/thumb/sphx_glr_plot_04_nelson_siegel_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/curves/plot_04_nelson_siegel`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Nelson-Siegel</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Litterman and Scheinkman (1991) ran a principal component analysis of Treasury returns and found that three factors explain almost all of the variation. They named them level, steepness (slope) and curvature. The script repeats the analysis on synthetic daily yield changes and shows the three loadings and their shares of variance.">

.. only:: html

  .. image:: /api/gallery/fixed_income/curves/images/thumb/sphx_glr_plot_05_litterman_scheinkman_pca_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/curves/plot_05_litterman_scheinkman_pca`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Litterman-Scheinkman: level, slope, curvature</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Lars Svensson (1994) added a second hump term to Nelson-Siegel, with its own decay \tau_2, to fit forward curves that bend twice. He built it to estimate forward rates at the Swedish Riksbank, and central banks still publish curves fitted with it. On such a curve, Nelson-Siegel misses the second bend and Svensson does not.">

.. only:: html

  .. image:: /api/gallery/fixed_income/curves/images/thumb/sphx_glr_plot_06_svensson_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/curves/plot_06_svensson`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Svensson</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Duration and convexity
----------------------

From Macaulay's average time to payment to Ho's key rate durations.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Frederick Macaulay (1938) measured a bond&#x27;s &quot;length&quot; not by its maturity but by the present-value-weighted average time to its payments,">

.. only:: html

  .. image:: /api/gallery/fixed_income/duration/images/thumb/sphx_glr_plot_01_macaulay_duration_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/duration/plot_01_macaulay_duration`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Macaulay duration</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="John Hicks (1939) found Macaulay&#x27;s average period again as the elasticity of a capital value with respect to the discount factor. Measured per unit of yield, that elasticity is modified duration,">

.. only:: html

  .. image:: /api/gallery/fixed_income/duration/images/thumb/sphx_glr_plot_02_hicks_modified_duration_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/duration/plot_02_hicks_modified_duration`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Hicks: duration as an elasticity (modified duration)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Fisher and Weil (1971) computed Macaulay&#x27;s weights with each cash flow discounted on its own zero rate instead of the bond&#x27;s single yield,">

.. only:: html

  .. image:: /api/gallery/fixed_income/duration/images/thumb/sphx_glr_plot_03_fisher_weil_duration_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/duration/plot_03_fisher_weil_duration`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fisher-Weil duration</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Duration is a tangent, but the price-yield curve bends. Bierwag, Kaufman and Toevs (1983) brought the second-order term into portfolio practice:">

.. only:: html

  .. image:: /api/gallery/fixed_income/duration/images/thumb/sphx_glr_plot_04_convexity_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/duration/plot_04_convexity`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Bierwag-Kaufman-Toevs: convexity</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A single duration assumes the whole curve moves in parallel. Thomas Ho (1992) shocked the curve one key rate at a time, with triangular shapes that sum to a parallel shift, so a bond&#x27;s risk becomes a vector whose entries add up to its effective duration. Two portfolios with the same duration can have very different key rate profiles.">

.. only:: html

  .. image:: /api/gallery/fixed_income/duration/images/thumb/sphx_glr_plot_05_ho_key_rate_durations_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/duration/plot_05_ho_key_rate_durations`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Ho's key rate durations</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Immunization
------------

Protecting a surplus against parallel and non-parallel rate moves.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Frank Redington (1952), an actuary, asked how a life office could hold assets so that a change in interest rates leaves its surplus unharmed. His answer has three conditions: match the present values, match the durations, and make the assets more convex than the liabilities. Then the surplus has a local minimum at today&#x27;s rates. Assets that straddle the liabilities satisfy the third condition. Assets bunched inside them do not.">

.. only:: html

  .. image:: /api/gallery/fixed_income/immunization/images/thumb/sphx_glr_plot_01_redington_immunization_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/immunization/plot_01_redington_immunization`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Redington immunization</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Redington&#x27;s conditions protect against parallel shifts only. Fong and Vasicek (1984) showed that when the forward curve twists with slope at most K, a duration-matched portfolio loses at most">

.. only:: html

  .. image:: /api/gallery/fixed_income/immunization/images/thumb/sphx_glr_plot_02_fong_vasicek_m_squared_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/immunization/plot_02_fong_vasicek_m_squared`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fong-Vasicek M-squared</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Swaps
-----

Swaps valued as the difference between two bonds.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In August 1981 Salomon Brothers arranged for the World Bank to take over IBM&#x27;s Swiss franc and Deutsche mark debt payments, while IBM took over dollar payments from the World Bank. Each side got the currency it wanted without issuing new debt. A fixed-for-fixed currency swap is a long bond in one currency and a short bond in the other, so its value moves with the exchange rate and with both yield curves.">

.. only:: html

  .. image:: /api/gallery/fixed_income/swaps/images/thumb/sphx_glr_plot_01_ibm_world_bank_currency_swap_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/swaps/plot_01_ibm_world_bank_currency_swap`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The IBM-World Bank currency swap</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The single-currency swap followed within a year of the IBM-World Bank deal. One side pays a fixed rate and the other pays a floating rate on the same notional. The floating leg is worth par on every reset date, so the swap is worth a floating-rate note minus a fixed-coupon bond. The par swap rate is the coupon that makes the two equal.">

.. only:: html

  .. image:: /api/gallery/fixed_income/swaps/images/thumb/sphx_glr_plot_02_interest_rate_swap_thumb.png
    :alt:

  :doc:`/api/gallery/fixed_income/swaps/plot_02_interest_rate_swap`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The plain-vanilla interest-rate swap</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /api/gallery/fixed_income/bonds/index.rst
   /api/gallery/fixed_income/curves/index.rst
   /api/gallery/fixed_income/duration/index.rst
   /api/gallery/fixed_income/immunization/index.rst
   /api/gallery/fixed_income/swaps/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

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

      :download:`Download all examples in Python source code: fixed_income_python.zip </api/gallery/fixed_income/fixed_income_python.zip>`

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

      :download:`Download all examples in Jupyter notebooks: fixed_income_jupyter.zip </api/gallery/fixed_income/fixed_income_jupyter.zip>`


.. only:: html

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

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