DOC: edit Fixings cookbook

docs/source/i_whatsnew.rst

@@ -65,6 +65,9 @@ email contact through **[email protected]**.
      - Allow ``fixings`` as a 2-tuple to manually define the first *FloatPeriod* (say as IBOR stub)
        and determine the rest from a *Series*. Also allow ``fx_fixings`` as a 2-tuple for similar
        reason for MTM *XCS*.
+   * - Legs
+     - Refactor how the ``defaults.fixings`` object works. **Breaking change**. Explained in
+       :ref:`Working with Fixings <cook-fixings-doc>`.
    * - Instruments
      - :class:`~rateslib.instruments.Fly` and :class:`~rateslib.instruments.Spread` now express
        *rate* in basis point terms and not percent.

docs/source/z_fixings.rst

@@ -24,14 +24,14 @@ within, *rateslib* documentation are shown below along with the source directory
 .. ipython:: python
 
    defaults.fixings.directory
-   defaults.fixings.usd_rfr  # an available alias is 'fixings.sofr'
+   defaults.fixings["usd_rfr"]  # an available alias is 'fixings["sofr"]'
 
 It is possible to overwrite these CSV files (provided the template structure is
-maintained) or to set a new directory and place CSV files there.
+maintained) or to set a new directory and place new CSV files there.
 Due to lazy loading, this should be done before calling any fixing *Series*, and
 all files should be stored in the same folder with the required naming convention.
 
-First we create a new fixing Series for the SEK 3M STIBOR index, and
+First we obtain (or create) new fixing for the SEK 3M STIBOR index, and
 save it to CSV file in the current working directory.
 
 .. ipython:: python
@@ -50,25 +50,71 @@ Next we set the directory of the `defaults.fixings` object and load the fixings.
 
    import os
    defaults.fixings.directory = os.getcwd()
-   defaults.fixings.sek_ibor_3m
+   defaults.fixings["sek_ibor_3m"]
 
-Currently the `fixings` object has support only for USD, GBP, EUR, SEK, NOK, CAD, CHF,
-with the indexes: RFR, 1M IBOR, 3M IBOR, 6M IBOR and 12M IBOR, but this is easily
-extendable via pull request.
+These fixings are entirely user defined in their construction and naming convention. If
+an attempt is made to call a fixing series that doesn't exist the user is met with the instructive
+error.
+
+.. ipython:: python
+
+   try:
+       defaults.fixings["arbitrary_index"]
+   except ValueError as e:
+       print(e)
+
+Constructing *Instruments* with *fixings*
+------------------------------------------
 
 These fixings can then be passed to *Instrument* constructors. For STIBOR the
 index lag is 2 business days so the fixing for the below *IRS* effective as of
-4th January is taken as the value **published on** reference date 2nd Jan 2023.
+4th January is taken as the value **published on** the reference date 2nd January.
 
 .. ipython:: python
 
    irs = IRS(
        effective=dt(2023, 1, 4),
        termination="6M",
        spec="sek_irs3",
-       leg2_fixings=defaults.fixings.sek_ibor_3m,
+       leg2_fixings=defaults.fixings["sek_ibor_3m"],
        fixed_rate=2.00,
    )
    curve = Curve({dt(2023, 1, 3): 1.0, dt(2024, 1, 3): 0.98})
    irs.cashflows(curve)
    irs.leg2.fixings_table(curve)
+
+Using *fx fixings* in multi-currency *Instruments*
+----------------------------------------------------
+
+:class:`~rateslib.instruments.XCS` typically require MTM payments based on FX fixings. However,
+the first FX fixing is usually agreed at trade time as the prevailing FX rate at the instant of
+execution. This poses a challenge to the initial construction of these *Instruments*.
+
+*Rateslib* handles this by allowing a 2-tuple as an input to ``fx_fixings``. The first entry is
+assigned to the first period and the latter entry is the FX fixings *Series*.
+
+Consider the example below.
+
+.. ipython:: python
+
+   df = DataFrame(
+       data=[1.19, 1.21, 1.24],
+       index=Index(["17-01-2023", "17-04-2023", "17-07-2023"], name="reference_date"),
+       columns=["rate"]
+   )
+   print(df)
+   df.to_csv("gbpusd.csv")  # Save the DataFrame and create a CSV file
+
+.. ipython:: python
+   :okwarning:
+
+   xcs = XCS(
+       effective=dt(2023, 1, 15),
+       termination="9M",
+       spec="gbpusd_xcs",
+       fx_fixings=(1.20, defaults.fixings["gbpusd"]),
+   )
+   xcs.cashflows(curves=curve, fx=1.25)  # arguments here used as a placeholder to display values.
+
+Note how the rate for initial exchange is 1.20 (and not 1.19)
+and the MTM payments are 1.21 and 1.24, as expected.

docs/source/z_quantlib.rst

@@ -1,7 +1,7 @@
 .. _cook-quantlib-doc:
 
-Coming from QuantLib
-********************
+Comparing Curve Building and Instrument Pricing with QuantLib
+****************************************************************
 This document offers a brief comparison between *rateslib* and *QuantLib* for constructing a *Curve*. In this example we build a *Curve* whose index is STIBOR-3M. 
 The evaluation includes *Curve* creation and pricing an :class:`~rateslib.instruments.IRS` using both libraries. Let's start with *QuantLib*:
 
@@ -235,14 +235,14 @@ This results in the following cashflows:
 
 .. table:: Cashflows attributes from QuantLib
 
-  +-------------+--------------+------------+-------------+-------------+-------------+-------------+--------------+
-  | Type        | accrualStart | accrualEnd | paymentDate | df          | rate        | cashflow    | npv          |
-  +=============+==============+============+=============+=============+=============+=============+==============+
-  | FixedPeriod | 2023-01-03   | 2024-01-03 | 2024-01-03  | 0.966203023 | 0.03269     | 3314402.778 | -3202385.985 |
-  | FixedPeriod | 2024-01-03   | 2025-01-03 | 2025-01-03  | 0.93439395  | 0.03269     | 3323483.333 | -3105442.721 |
-  | FloatPeriod | 2023-01-03   | 2024-01-03 | 2024-01-03  | 0.966203023 | 0.0345      | 3497916.667 | 3379697.659  |
-  | FloatPeriod | 2024-01-03   | 2025-01-03 | 2025-01-03  | 0.93439395  | 0.03348     | 3404246.458 | 3180907.297  |
-  +-------------+--------------+------------+-------------+-------------+-------------+-------------+--------------+
+  +-------+----------+----------+-----------+---------+------------+-------------+
+  | Type  | accStart | accEnd   |df         | rate    | cashflow   | npv         |
+  +=======+==========+==========+===========+=========+============+=============+
+  | Fixed | 23-01-03 | 24-01-03 | 0.9662030 | 0.03269 | 3314402.77 | -3202385.98 |
+  | Fixed | 24-01-03 | 25-01-03 | 0.9343939 | 0.03269 | 3323483.33 | -3105442.72 |
+  | Float | 23-01-03 | 24-01-03 | 0.9662030 | 0.03450 | 3497916.66 | 3379697.65  |
+  | Float | 24-01-03 | 25-01-03 | 0.9343939 | 0.03348 | 3404246.45 | 3180907.29  |
+  +-------+----------+----------+-----------+---------+------------+-------------+
 
 Which compared with *rateslib*
 
@@ -269,14 +269,14 @@ Results in the following table:
 
 .. table:: Cashflows attributes from rateslib
 
-  +-------------+------------+------------+------------+-------------+-------------+--------------+--------------+
-  | Type        | Acc Start  | Acc End    | Payment    | DF          | Rate        | Cashflow     | NPV          |
-  +=============+============+============+============+=============+=============+==============+==============+
-  | FixedPeriod | 2023-01-03 | 2024-01-03 | 2024-01-03 | 0.966203023 | 3.26900     | -3314402.778 | -3202385.985 |
-  | FixedPeriod | 2024-01-03 | 2025-01-03 | 2025-01-03 | 0.93439395  | 3.26900     | -3323483.333 | -3105442.721 |
-  | FloatPeriod | 2023-01-03 | 2024-01-03 | 2024-01-03 | 0.966203023 | 3.450       | 3497916.667  | 3379697.659  |
-  | FloatPeriod | 2024-01-03 | 2025-01-03 | 2025-01-03 | 0.93439395  | 3.348439139 | 3404246.458  | 3180907.297  |
-  +-------------+------------+------------+------------+-------------+-------------+--------------+--------------+
+  +-------+----------+----------+-----------+--------+-------------+-------------+
+  | Type  | AccStart | Acc End  | DF        | Rate   | Cashflow    | NPV         |
+  +=======+==========+==========+===========+========+=============+=============+
+  | Fixed | 23-01-03 | 24-01-03 | 0.9662030 | 3.2690 | -3314402.77 | -3202385.98 |
+  | Fixed | 24-01-03 | 25-01-03 | 0.9343939 | 3.2690 | -3323483.33 | -3105442.72 |
+  | Float | 23-01-03 | 24-01-03 | 0.9662030 | 3.4500 | 3497916.66  | 3379697.65  |
+  | Float | 24-01-03 | 25-01-03 | 0.9343939 | 3.3484 | 3404246.45  | 3180907.29  |
+  +-------+----------+----------+-----------+--------+-------------+-------------+
 
 Which is identical to the *QuantLib* result. 
 If you're interested in delving deeper into the calculation of DFs by *rateslib* and *QuantLib*, you may find some insights in this `blog post <https://xiar-fatah.github.io/2023/11/14/rateslib-bootstrapping.html>`_.