Skip to content

Commit

Permalink
DOC: get started revisions (#94)
Browse files Browse the repository at this point in the history
  • Loading branch information
@attack68
attack68 authored Nov 11, 2023
1 parent 7091f3c commit 776bbdf
Show file tree
Hide file tree
Showing 3 changed files with 134 additions and 153 deletions.
13 changes: 13 additions & 0 deletions docs/source/_static/css/getting_started.css
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,18 @@
/* Getting started pages */

.tutorial {
width: 100%;
text-align: center;
}

.tutorial span {
background-color: #00004f;
color: white;
text-align: center;
padding: 0.2em 0.9em;
border-radius: 0.7em;
}

/* data intro */
.gs-data {
font-size: 0.9rem;
Expand Down
242 changes: 90 additions & 152 deletions docs/source/i_get_started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,207 +63,145 @@ Or, it can be installed via the community ``conda-forge`` channel available from
Introduction to Rateslib
-------------------------

.. raw:: html

<div class="container">
<div id="accordion" class="shadow tutorial-accordion">

<div class="card tutorial-card">
<div class="card-header collapsed card-link" data-toggle="collapse" data-target="#collapseOne">
<div class="d-flex flex-row tutorial-card-header-1">
<div class="d-flex flex-row tutorial-card-header-2">
<button class="btn btn-dark btn-sm"></button>
Which &nbsp;<span style="color: darkorange;">fixed income instruments</span>&nbsp; does rateslib include?
</div>
<span class="badge gs-badge-link">

:ref:`Straight to tutorial...<instruments-doc>`

.. raw:: html

</span>
</div>
</div>
<div id="collapseOne" class="collapse" data-parent="#accordion">
<div class="card-body">

**Securities**

- Discount securities - :class:`~rateslib.instruments.Bill`,
- Regular nominal bonds - :class:`~rateslib.instruments.FixedRateBond`,
- Bond futures - :class:`~rateslib.instruments.BondFuture`,
- Index linked bonds - :class:`~rateslib.instruments.IndexFixedRateBond`,
- Also FRNs - :class:`~rateslib.instruments.FloatRateNote`.

**Single Currency Derivatives**
For what purpose would I use *rateslib*?
=============================================

- Interest rate swaps (both IBOR and RFR) - :class:`~rateslib.instruments.IRS`,
- Index interest rate swaps - :class:`~rateslib.instruments.IIRS`,
- Zero coupon swaps - :class:`~rateslib.instruments.ZCS`,
- Zero coupon index swaps - :class:`~rateslib.instruments.ZCIS`,
- Basis swaps - :class:`~rateslib.instruments.SBS`,
- Forward rate agreements - :class:`~rateslib.instruments.FRA`.
- If you want to integrate linear fixed income analysis into your workflow with Python.
- If you desire a pain free setup process, a user-oriented API, and extensive documentation.
- If you are new to fixed income and interested to learn about basic and advanced concepts with
tools to explore the nuances of these markets, as a companion to various authored books.

**Multi-currency Derivatives**
Which ``fixed income instruments`` does *rateslib* include?
===========================================================

- Cross-currency basis swaps - :class:`~rateslib.instruments.XCS`,
- Non-mtm cross-currency basis swaps - :class:`~rateslib.instruments.NonMtmXCS`,
- FX swaps - :class:`~rateslib.instruments.FXSwap`.

.. raw:: html

</div>
</div>
</div>
.. list-table::
:widths: 25 25 25 25
:header-rows: 1

.. raw:: html

<div class="card tutorial-card">
<div class="card-header collapsed card-link" data-toggle="collapse" data-target="#collapseAD">
<div class="d-flex flex-row tutorial-card-header-1">
<div class="d-flex flex-row tutorial-card-header-2">
<button class="btn btn-dark btn-sm"></button>
Does rateslib use &nbsp;<span style="color: darkorange;">automatic differentiation (AD)</span>?
</div>
<span class="badge gs-badge-link">
* - Single Ccy Derivatives
- Multi-Ccy Derivatives
- Securities
- Combinations
* - :class:`~rateslib.instruments.IRS`
- :class:`~rateslib.instruments.FXExchange`
- :class:`~rateslib.instruments.FixedRateBond`
- :class:`~rateslib.instruments.Spread`
* - :class:`~rateslib.instruments.SBS`
- :class:`~rateslib.instruments.FXSwap`
- :class:`~rateslib.instruments.FloatRateNote`
- :class:`~rateslib.instruments.Fly`
* - :class:`~rateslib.instruments.FRA`
- :class:`~rateslib.instruments.XCS`
- :class:`~rateslib.instruments.Bill`
- :class:`~rateslib.instruments.Portfolio`
* - :class:`~rateslib.instruments.STIRFuture`
-
- :class:`~rateslib.instruments.BondFuture`
-
* - :class:`~rateslib.instruments.ZCS`
-
- :class:`~rateslib.instruments.IndexFixedRateBond`
-
* - :class:`~rateslib.instruments.ZCIS`
-
-
-
* - :class:`~rateslib.instruments.IIRS`
-
-
-

.. raw:: html

<div class="tutorial">

:ref:`Straight to tutorial...<dual-doc>`
:ref:`Straight to tutorial...<instruments-doc>`

.. raw:: html

</span>
</div>
</div>
<div id="collapseAD" class="collapse" data-parent="#accordion">
<div class="card-body">

**Yes**. The ``rateslib.dual`` module provides ``rateslib`` with its own integrated
automatic differentiation toolset, using dual numbers, which operate in forward mode
(as opposed to backwards, or adjoint, mode).

Whenever you see a calculation result that displays a ``<Dual: 2.40..>`` datatype,
it is sufficient to understand that the real value associated with this is the
answer (2.40), and can be extracted directly with ``float(result)`` or ``result.real``.
The ``dual`` attribute of the result contains first derivative information with regards
to variables that has attributed to its calculation.
</div>

.. raw:: html
Does *rateslib* handle ``foreign exchange (FX)``?
===========================================================

</div>
</div>
</div>
**Yes**. Foreign exchange is a pre-requisite of properly handling multi-currency fixed income
derivatives, so the :class:`~rateslib.fx.FXRates` and :class:`~rateslib.fx.FXForwards`
classes exist to allow full flexibility and expressing quantities in
consistent currencies.

.. raw:: html

<div class="card tutorial-card">
<div class="card-header collapsed card-link" data-toggle="collapse" data-target="#collapseTwo">
<div class="d-flex flex-row tutorial-card-header-1">
<div class="d-flex flex-row tutorial-card-header-2">
<button class="btn btn-dark btn-sm"></button>
Does rateslib handle &nbsp;<span style="color: darkorange;">foreign exchange (FX)</span>?
</div>
<span class="badge gs-badge-link">
<div class="tutorial">

:ref:`Straight to tutorial...<fx-doc>`

.. raw:: html

</span>
</div>
</div>
<div id="collapseTwo" class="collapse" data-parent="#accordion">
<div class="card-body">

**Yes**. Foreign exchange is a pre-requisite of properly handling multi-currency
derivatives, so the :class:`~rateslib.fx.FXRates` and :class:`~rateslib.fx.FXForwards`
classes exist to allow full flexibility and expressing quantities in
consistent currencies.
</div>

.. raw:: html
Can ``Curves`` be constructed and plotted in *rateslib*?
===========================================================

</div>
</div>
</div>
**Of course**. Building curves is a necessity for pricing fixed income instruments.
*Rateslib* has three primitive curve structures; :class:`~rateslib.curves.Curve` (which
is **discount factor based**), :class:`~rateslib.curves.LineCurve` (which is **purely value
based**), and :class:`~rateslib.curves.IndexCurve` (which is based on a *Curve* but also
calculates index values which is useful for inflation, for example). All *Curve* types offer
various interpolation methods, such as log-linear or log-cubic spline and can even splice certain
interpolation types together.

.. raw:: html

<div class="card tutorial-card">
<div class="card-header collapsed card-link" data-toggle="collapse" data-target="#collapseThree">
<div class="d-flex flex-row tutorial-card-header-1">
<div class="d-flex flex-row tutorial-card-header-2">
<button class="btn btn-dark btn-sm"></button>
Can rateslib create and plot &nbsp;<span style="color: darkorange;">interest rate curves</span>?
</div>
<span class="badge gs-badge-link">
<div class="tutorial">

:ref:`Straight to tutorial...<curves-doc>`

.. raw:: html

</span>
</div>
</div>
<div id="collapseThree" class="collapse" data-parent="#accordion">
<div class="card-body">
</div>

**Of course**. Building curves is a necessity for pricing fixed income instruments.
``rateslib`` has two available curve structures, and within those different
interpolation options:

- :class:`~rateslib.curves.Curve`, which is **discount factor based**. The native
interpolation options provided for these are ``log_linear``, ``linear_zero_rate``,
``log-cubic spline``, or
a mixture of the two with the longer end being log-cubic spline.
- :class:`~rateslib.curves.LineCurve`, which is **purely value based**. The native
interpolation options provided for these are ``linear``, ``flat_forward``,
``cubic spline``, or a
mixture of the two with the longer end being cubic spline.
Does *rateslib* ``solve`` curves relative to market prices?
===========================================================

.. raw:: html
**Yes**, when a :class:`~rateslib.solver.Solver` is configured along with all the intended
*Instruments* and their relevant *prices*.
Multiple algorithms (*gradient descent, Gauss-Newton, Leveberg-Marquardt*) and stopping criteria
can be used within the optimization routine
to simultaneously solve multiple *Curve* parameter.

</div>
</div>
</div>
The *Solver* can even construct dependency chains, like sequentially building curves
with dependencies to other desks on an investment bank trading floor, and internally manage all of
the **risk sensitivity** calculations.

.. raw:: html

<div class="card tutorial-card">
<div class="card-header collapsed card-link" data-toggle="collapse" data-target="#collapseFour">
<div class="d-flex flex-row tutorial-card-header-1">
<div class="d-flex flex-row tutorial-card-header-2">
<button class="btn btn-dark btn-sm"></button>
Can rateslib &nbsp;<span style="color: darkorange;">solve</span>&nbsp; interest rates curves from market instruments?
</div>
<span class="badge gs-badge-link">
<div class="tutorial">

:ref:`Straight to tutorial...<c-solver-doc>`

.. raw:: html

</span>
</div>
</div>
<div id="collapseFour" class="collapse" data-parent="#accordion">
<div class="card-body">
</div>

**Absolutely**. ``rateslib`` has a state-of-the-art :class:`~rateslib.solver.Solver`,
which can use multiple algorithms (*gradient descent, Gauss-Newton, Leveberg-Marquardt*)
to simultaneously solve the curve parameters to fit provided market instrument prices.
Does *rateslib* use ``automatic differentiation (AD)``?
===========================================================

The solver can even construct dependency chains, like sequentially building curves
with dependencies to other desks in on an investment bank trading floor, and it can
handle over-specified curves or under-specified curves.
**Yes**. The *dual* module provides *rateslib* with its own integrated
automatic differentiation toolset, primarily the dual datatypes :class:`~rateslib.dual.Dual` and
:class:`~rateslib.dual.Dual2`, which operate in forward mode
(as opposed to backwards, or adjoint, mode). This allows native calculations to store first
(or second) derivative information as those calculations are made on-the-fly.

.. raw:: html

</div>
</div>
</div>
<div class="tutorial">

:ref:`Straight to tutorial...<dual-doc>`

.. raw:: html

</div>
</div>


Imports and Defaults
Expand Down
32 changes: 31 additions & 1 deletion rateslib/instruments.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -868,6 +868,34 @@ def analytic_delta(self, *args, **kwargs):


class FXExchange(Sensitivities, BaseMixin):
"""
Create a simple exchange of two currencies.
Parameters
----------
settlement : datetime
The date of the currency exchange.
currency : str
The currency of the cashflow for which ``notional`` is applicable (3-digit code).
leg2_currency : str
The currency of the cashflow on the alternate *Leg*.
fx_rate : float, optional
The FX rate used to derive the notional exchange on *Leg2*.
notional : float
The cashflow amount for the initial currency.
curves : Curve, LineCurve, str or list of such, optional
A single :class:`~rateslib.curves.Curve`,
:class:`~rateslib.curves.LineCurve` or id or a
list of such. A list defines the following curves in the order:
- Forecasting :class:`~rateslib.curves.Curve` or
:class:`~rateslib.curves.LineCurve` for ``leg1``.
- Discounting :class:`~rateslib.curves.Curve` for ``leg1``.
- Forecasting :class:`~rateslib.curves.Curve` or
:class:`~rateslib.curves.LineCurve` for ``leg2``.
- Discounting :class:`~rateslib.curves.Curve` for ``leg2``.
"""

def __init__(
self,
settlement: datetime,
Expand Down Expand Up @@ -6805,7 +6833,9 @@ def gamma(self, *args, **kwargs):

class XCS(BaseDerivative):
"""
Base class with common methods for multi-currency ``Derivatives``.
Create a cross-currency swap (XCS) composing relevant fixed or floating *Legs*.
MTM-XCSs will introduce a MTM *Leg* as *Leg2*.
Parameters
----------
Expand Down

0 comments on commit 776bbdf

Please sign in to comment.