FixedLeg#

class rateslib.legs.FixedLeg(schedule, *, notional=NoInput.blank, amortization=NoInput.blank, currency=NoInput.blank, pair=NoInput.blank, fx_fixings=NoInput.blank, mtm=LegMtm.Initial, convention=NoInput.blank, initial_exchange=False, final_exchange=False, fixed_rate=NoInput.blank, index_base=NoInput.blank, index_lag=NoInput.blank, index_method=NoInput.blank, index_fixings=NoInput.blank, index_only=False)#

Bases: _BaseLeg, _WithExDiv

A Leg containing FixedPeriod.

Examples

In [1]: fl = FixedLeg(
   ...:     schedule=Schedule(
   ...:          effective=dt(2000, 2, 1),
   ...:          termination=dt(2002, 2, 1),
   ...:          frequency="S",
   ...:     ),
   ...:     convention="ActActICMA",
   ...:     fixed_rate=2.5,
   ...:     notional=10e6,
   ...: )
   ...: 

In [2]: fl.cashflows()
Out[2]: 
          Type  Ccy    Payment    Notional   Period  Convention  DCF  Acc Start    Acc End    DF  Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  Rate Spread
0  FixedPeriod  USD 2000-08-03  10000000.0  Regular  ActActICMA  0.5 2000-02-01 2000-08-01  None -125000.0  None      1.0      USD    None       None   2.5   None
1  FixedPeriod  USD 2001-02-03  10000000.0  Regular  ActActICMA  0.5 2000-08-01 2001-02-01  None -125000.0  None      1.0      USD    None       None   2.5   None
2  FixedPeriod  USD 2001-08-03  10000000.0  Regular  ActActICMA  0.5 2001-02-01 2001-08-01  None -125000.0  None      1.0      USD    None       None   2.5   None
3  FixedPeriod  USD 2002-02-03  10000000.0  Regular  ActActICMA  0.5 2001-08-01 2002-02-01  None -125000.0  None      1.0      USD    None       None   2.5   None

Parameters:

schedule (Schedule, required) –
The Schedule object which structures contiguous Periods. The schedule object also contains data for payment dates, payment dates for notional exchanges and ex-dividend dates for each period.

Note

The following are period parameters combined with the schedule.
convention (str, optional (set by ‘defaults’)) –
The day count convention applied to calculations of period accrual dates. See dcf().

Note

The following define generalised settlement parameters.
currency (str, optional (set by ‘defaults’)) – The local settlement currency of the leg (3-digit code).
notional (float, Dual, Dual2, Variable, optional (set by ‘defaults’)) – The initial leg notional, defined in units of reference currency.
amortization (float, Dual, Dual2, Variable, str, Amortization, optional (set as zero)) – Set a non-constant notional per Period. If a scalar value, adjusts the notional of each successive period by that same value. Should have sign equal to that of notional if the notional is to reduce towards zero.
initial_exchange (bool, optional (set as False)) – Whether to also include an initial notional exchange. If True then final_exchange will also be set to True.
final_exchange (bool, optional (set as initial_exchange)) –
Whether to also include a final notional exchange and interim amortization notional exchanges.

Note

The following define rate parameters.
fixed_rate (float, Dual, Dual2, Variable, optional) –
The fixed rate of each composited FixedPeriod.

Note

The following define non-deliverable parameters. If the Leg is directly deliverable then do not set a non-deliverable pair or any fx_fixings.
pair (FXIndex, str, optional) – The FXIndex for FXFixing defining the currency pair that determines Period settlement. The reference currency is implied from pair. Must include currency.
fx_fixings (float, Dual, Dual2, Variable, Series, str, 2-tuple or list, optional) –
The value of the FXFixing for each Period according to non-deliverability. Review the notes section non-deliverability. This should only ever be entered as either:
- scalar value: 1.15,
- fixings series: “Reuters_ZBS”,
- tuple of transaction rate and fixing series: (1.25, “Reuters_ZBC”)
mtm (LegMtm or str, optional (set to ‘initial’)) –
Define how the fixing dates are determined for each FXFixing See Notes regarding non-deliverability.

Note

The following parameters define indexation. The Period will be considered indexed if any of index_method, index_lag, index_base, index_fixings are given.
index_method (IndexMethod, str, optional (set by ‘defaults’)) – The interpolation method, or otherwise, to determine index values from reference dates.
index_lag (int, optional (set by ‘defaults’)) – The indexation lag, in months, applied to the determination of index values.
index_base (float, Dual, Dual2, Variable, optional) – The specific value applied as the base index value for all Periods. If not given and index_fixings is a string fixings identifier that will be used to determine the base index value.
index_fixings (float, Dual, Dual2, Variable, Series, str, 2-tuple or list, optional) – The index value for the reference date. Best practice is to supply this value as string identifier relating to the global fixings object.
index_only (bool, optional (set as False)) – A flag which indicates that the nominal amount is deducted from the cashflow leaving only the indexed up quantity.

Notes

Typical Fixed Legs

A typical FixedLeg has no amortization, no indexation, is directly deliverable and offers no notional exchanges. This represents one component of, for example, an IRS.

In [3]: leg = FixedLeg(
   ...:     schedule=Schedule(dt(2000, 1, 1), dt(2000, 7, 1), "Q"),
   ...:     fixed_rate=2.0,
   ...:     convention="Act360",
   ...:     notional=5000000,
   ...: )
   ...: 

In [4]: print(leg.cashflows())
          Type  Ccy    Payment   Notional   Period Convention       DCF  Acc Start    Acc End    DF      Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  Rate Spread
0  FixedPeriod  USD 2000-04-03  5000000.0  Regular     Act360  0.252778 2000-01-01 2000-04-01  None -25277.777778  None      1.0      USD    None       None   2.0   None
1  FixedPeriod  USD 2000-07-03  5000000.0  Regular     Act360  0.252778 2000-04-01 2000-07-01  None -25277.777778  None      1.0      USD    None       None   2.0   None

Notional Exchanges

Notional exchanges are common elements on securities, e.g. a FixedRateBond. These can be specifically included using the final_exchange and initial_exchange parameters.

In [5]: leg = FixedLeg(
   ...:     schedule=Schedule(dt(2000, 1, 1), dt(2000, 7, 1), "Q"),
   ...:     fixed_rate=2.0,
   ...:     convention="Act360",
   ...:     notional=5000000,
   ...:     final_exchange=True,
   ...: )
   ...: 

In [6]: print(leg.cashflows())
          Type  Ccy    Payment   Notional   Period Convention       DCF  Acc Start    Acc End    DF      Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  Rate  Spread
0  FixedPeriod  USD 2000-04-03  5000000.0  Regular     Act360  0.252778 2000-01-01 2000-04-01  None -2.527778e+04  None      1.0      USD    None       None   2.0     NaN
1  FixedPeriod  USD 2000-07-03  5000000.0  Regular     Act360  0.252778 2000-04-01 2000-07-01  None -2.527778e+04  None      1.0      USD    None       None   2.0     NaN
2     Cashflow  USD 2000-07-01  5000000.0      NaN        NaN       NaN        NaT        NaT  None -5.000000e+06  None      1.0      USD    None       None   NaN     NaN

Initial and final notional exchanges have opposite directions.

Amortization

Amortization can be applied either with customised schedules, or with simpler consistent amounts per period.

If final_exchange is True then amortization will also create interim notional exchange cashflows. Note that a same sign amortization value is translated into a notional reduction. If final_exchange is False, or amortization is zero, there are no interim notional exchange cashflows generated.

In [7]: leg = FixedLeg(
   ...:     schedule=Schedule(dt(2000, 1, 1), dt(2000, 7, 1), "Q"),
   ...:     fixed_rate=2.0,
   ...:     convention="Act360",
   ...:     notional=5000000,
   ...:     amortization=1000000,
   ...:     final_exchange=True,
   ...: )
   ...: 

In [8]: print(leg.cashflows())
          Type  Ccy    Payment   Notional   Period Convention       DCF  Acc Start    Acc End    DF      Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  Rate  Spread
0  FixedPeriod  USD 2000-04-03  5000000.0  Regular     Act360  0.252778 2000-01-01 2000-04-01  None -2.527778e+04  None      1.0      USD    None       None   2.0     NaN
1     Cashflow  USD 2000-04-01  1000000.0      NaN        NaN       NaN        NaT        NaT  None -1.000000e+06  None      1.0      USD    None       None   NaN     NaN
2  FixedPeriod  USD 2000-07-03  4000000.0  Regular     Act360  0.252778 2000-04-01 2000-07-01  None -2.022222e+04  None      1.0      USD    None       None   2.0     NaN
3     Cashflow  USD 2000-07-01  4000000.0      NaN        NaN       NaN        NaT        NaT  None -4.000000e+06  None      1.0      USD    None       None   NaN     NaN

Indexation

An IndexFixedRateBond is the most common instrument that uses an index-linked FixedLeg. Setting index parameters creates the necessary indexation of cashflows. Note that all previous features such as notional exchanges and amortization are all adjusted appropriately.

In [9]: fixings.add("MY_RPI", Series(
   ...:     index=[dt(2000, 1, 1), dt(2000, 4, 1), dt(2000, 7, 1)],
   ...:     data=[101.0, 102.0, 103.0]
   ...: ))
   ...: 

In [10]: leg = FixedLeg(
   ....:     schedule=Schedule(dt(2000, 1, 1), dt(2000, 7, 1), "Q"),
   ....:     fixed_rate=2.0,
   ....:     convention="Act360",
   ....:     notional=5000000,
   ....:     amortization=1000000,
   ....:     final_exchange=True,
   ....:     index_fixings="MY_RPI",
   ....:     index_lag=0,
   ....:     index_method="monthly",
   ....: )
   ....: 

In [11]: print(leg.cashflows())
          Type  Ccy    Payment   Notional   Period Convention       DCF  Acc Start    Acc End    DF      Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  Rate  Spread  Index Base  Index Val  Index Ratio Index Fix Date  Unindexed Cashflow
0  FixedPeriod  USD 2000-04-03  5000000.0  Regular     Act360  0.252778 2000-01-01 2000-04-01  None -2.552805e+04  None      1.0      USD    None       None   2.0     NaN       101.0      102.0     1.009901     2000-04-01       -2.527778e+04
1     Cashflow  USD 2000-04-01  1000000.0      NaN        NaN       NaN        NaT        NaT  None -1.009901e+06  None      1.0      USD    None       None   NaN     NaN       101.0      102.0     1.009901     2000-04-01       -1.000000e+06
2  FixedPeriod  USD 2000-07-03  4000000.0  Regular     Act360  0.252778 2000-04-01 2000-07-01  None -2.062266e+04  None      1.0      USD    None       None   2.0     NaN       101.0      103.0     1.019802     2000-07-01       -2.022222e+04
3     Cashflow  USD 2000-07-01  4000000.0      NaN        NaN       NaN        NaT        NaT  None -4.079208e+06  None      1.0      USD    None       None   NaN     NaN       101.0      103.0     1.019802     2000-07-01       -4.000000e+06

Any interim notional exchange cashflows generated by amortization are also indexed.

Non-Deliverability

The leg uses a mtm argument to define the types of non-deliverability that it can construct. Currently there are three kinds which cater to the various type of requirements for, ND-IRS, MTM-XCS, non-MTM XCS, ND-XCS

This uses the Initial variant of a LegMtm and it defines all FXFixing on the Leg to be a single date at the start of the Leg (derived from schedule.pschedule2[0]). Usually this fixing is directly specified being agreed at execution of the transaction and not dependent upon a published financial fixing.

This type of non-deliverability is suitable to define a Leg of one currency, but expressed by a notional in another currency, and is used for a non-MTM XCS.

Since only one fixing is required, fx_fixings can be entered either as a known scalar value or string series identifier.

In [12]: leg = FixedLeg(
   ....:     schedule=Schedule(
   ....:         effective=dt(2000, 1, 1),
   ....:         termination=dt(2000, 7, 1),
   ....:         frequency="Q",
   ....:         payment_lag=1,
   ....:         payment_lag_exchange=0,
   ....:     ),
   ....:     fixed_rate=1.0,
   ....:     initial_exchange=True,
   ....:     mtm="initial",
   ....:     currency="usd",
   ....:     pair="eurusd",
   ....:     notional=10e6,      # <- Leg is a USD leg but expressed with a EUR notional
   ....:     fx_fixings=1.25,    # <- All periods are treated as 12.5mm USD
   ....: )
   ....: 

In [13]: print(leg.cashflows())
          Type  Ccy    Payment    Notional    DF      Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  FX Fixing FX Fix Date Reference Ccy   Period Convention       DCF  Acc Start    Acc End  Rate  Spread
0     Cashflow  USD 2000-01-01 -10000000.0  None  1.250000e+07  None      1.0      USD    None       None       1.25  1999-12-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
1  FixedPeriod  USD 2000-04-02  10000000.0  None -3.159722e+04  None      1.0      USD    None       None       1.25  1999-12-30           EUR  Regular     Act360  0.252778 2000-01-01 2000-04-01   1.0     NaN
2  FixedPeriod  USD 2000-07-02  10000000.0  None -3.159722e+04  None      1.0      USD    None       None       1.25  1999-12-30           EUR  Regular     Act360  0.252778 2000-04-01 2000-07-01   1.0     NaN
3     Cashflow  USD 2000-07-01  10000000.0  None -1.250000e+07  None      1.0      USD    None       None       1.25  1999-12-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN

Under the Payment variant of a LegMtm all reference currency cashflows are converted to settlement currency using an FXFixing with a date of the payment. This is probably the most traditional type of non-deliverability and is suitable for NDIRS and NDXCS Instruments.

The best practice entry for fx_fixings depends if the Leg has notional exchanges or not. If there is an initial notional exchange then a 2-tuple, with the first element being the transacted exchange rate and the second element referring to the fixing series for future FX Fixings. If only future fixings are required then a string series is used.

In [14]: fixings.add("WMR_10AM_TY0_T+2_EURUSD", Series(
   ....:     index=[dt(2000, 1, 1), dt(2000, 4, 2), dt(2000, 7, 1), dt(2000, 7, 2)],
   ....:     data=[1.26, 1.27, 1.29, 1.295])
   ....: )
   ....: 

In [15]: leg = FixedLeg(
   ....:     schedule=Schedule(
   ....:         effective=dt(2000, 1, 1),
   ....:         termination=dt(2000, 7, 1),
   ....:         frequency="Q",
   ....:         payment_lag=1,
   ....:         payment_lag_exchange=0,
   ....:     ),
   ....:     fixed_rate=1.0,
   ....:     initial_exchange=True,
   ....:     mtm="payment",
   ....:     currency="usd",
   ....:     pair="eurusd",
   ....:     notional=10e6,                          # <- Leg settles in USD leg but reference cashflows in EUR
   ....:     fx_fixings=(1.25, "WMR_10AM_TY0_T+2"),  # <- Initial exchange rate and future fixings
   ....: )
   ....: 

In [16]: print(leg.cashflows())
          Type  Ccy    Payment    Notional    DF    Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  FX Fixing FX Fix Date Reference Ccy   Period Convention       DCF  Acc Start    Acc End  Rate  Spread
0     Cashflow  USD 2000-01-01 -10000000.0  None  12500000.0  None      1.0      USD    None       None       1.25  1999-12-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
1  FixedPeriod  USD 2000-04-02  10000000.0  None         NaN  None      1.0      USD    None       None        NaN  2000-03-30           EUR  Regular     Act360  0.252778 2000-01-01 2000-04-01   1.0     NaN
2  FixedPeriod  USD 2000-07-02  10000000.0  None         NaN  None      1.0      USD    None       None        NaN  2000-06-29           EUR  Regular     Act360  0.252778 2000-04-01 2000-07-01   1.0     NaN
3     Cashflow  USD 2000-07-01  10000000.0  None         NaN  None      1.0      USD    None       None        NaN  2000-06-29           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN

The XCS variant of a LegMtm is specially configured for MTM-XCS. These Legs have their cashflows determined with FXFixing at the start of each Period, in a manner slightly similar to the Initial variant, and specifically generated MtmCashflow Periods adjusting the value of the notional by an FXFixing at the end of each Period.

The best practice entry for fx_fixings is as a 2-tuple, with the first element the transacted exchange rate and the second element referring to the fixing series for future FX Fixings.

In [17]: fixings.add("WMR_4PM_GMT_T+2_EURUSD", Series(
   ....:     index=[dt(2000, 4, 1), dt(2000, 4, 2), dt(2000, 7, 2)],
   ....:     data=[1.265, 1.27, 1.29])
   ....: )
   ....: 

In [18]: leg = FixedLeg(
   ....:     schedule=Schedule(
   ....:         effective=dt(2000, 1, 1),
   ....:         termination=dt(2000, 7, 1),
   ....:         frequency="Q",
   ....:         payment_lag=1,
   ....:         payment_lag_exchange=0,
   ....:     ),
   ....:     fixed_rate=1.0,
   ....:     initial_exchange=True,
   ....:     currency="usd",
   ....:     pair="eurusd",
   ....:     mtm="xcs",
   ....:     notional=10e6,
   ....:     fx_fixings=(1.25, "WMR_4PM_GMT_T+2"),
   ....: )
   ....: 

In [19]: print(leg.cashflows())
          Type  Ccy    Payment    Notional    DF      Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  FX Fixing FX Fix Date Reference Ccy   Period Convention       DCF  Acc Start    Acc End  Rate  Spread
0     Cashflow  USD 2000-01-01 -10000000.0  None  1.250000e+07  None      1.0      USD    None       None       1.25  1999-12-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
1  FixedPeriod  USD 2000-04-02  10000000.0  None -3.159722e+04  None      1.0      USD    None       None       1.25  1999-12-30           EUR  Regular     Act360  0.252778 2000-01-01 2000-04-01   1.0     NaN
2  MtmCashflow  USD 2000-04-01 -10000000.0  None           NaN  None      1.0      USD    None       None        NaN  2000-03-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
3  FixedPeriod  USD 2000-07-02  10000000.0  None           NaN  None      1.0      USD    None       None        NaN  2000-03-30           EUR  Regular     Act360  0.252778 2000-04-01 2000-07-01   1.0     NaN
4     Cashflow  USD 2000-07-01  10000000.0  None           NaN  None      1.0      USD    None       None        NaN  2000-03-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN

Amortization and Non-Deliverability

When amortization is combined with non-deliverability, the interim notional exchange cashflows are adjusted appropriately in both the non-mtm and mtm cases.

Amortization under this method adopts the same singular fixing as all other Periods.

In [20]: leg = FixedLeg(
   ....:     schedule=Schedule(
   ....:         effective=dt(2000, 1, 1),
   ....:         termination=dt(2000, 7, 1),
   ....:         frequency="Q",
   ....:         payment_lag=1,
   ....:         payment_lag_exchange=0,
   ....:     ),
   ....:     fixed_rate=1.0,
   ....:     initial_exchange=True,
   ....:     mtm="initial",
   ....:     currency="usd",
   ....:     pair="eurusd",
   ....:     notional=10e6,      # <- Leg is a USD leg but expressed with a EUR notional
   ....:     amortization=4e6,
   ....:     fx_fixings=1.25,    # <- All periods are treated as 12.5mm USD
   ....: )
   ....: 

In [21]: print(leg.cashflows())
          Type  Ccy    Payment    Notional    DF      Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  FX Fixing FX Fix Date Reference Ccy   Period Convention       DCF  Acc Start    Acc End  Rate  Spread
0     Cashflow  USD 2000-01-01 -10000000.0  None  1.250000e+07  None      1.0      USD    None       None       1.25  1999-12-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
1  FixedPeriod  USD 2000-04-02  10000000.0  None -3.159722e+04  None      1.0      USD    None       None       1.25  1999-12-30           EUR  Regular     Act360  0.252778 2000-01-01 2000-04-01   1.0     NaN
2     Cashflow  USD 2000-04-01   4000000.0  None -5.000000e+06  None      1.0      USD    None       None       1.25  1999-12-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
3  FixedPeriod  USD 2000-07-02   6000000.0  None -1.895833e+04  None      1.0      USD    None       None       1.25  1999-12-30           EUR  Regular     Act360  0.252778 2000-04-01 2000-07-01   1.0     NaN
4     Cashflow  USD 2000-07-01   6000000.0  None -7.500000e+06  None      1.0      USD    None       None       1.25  1999-12-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN

Amortization under this method settles according to the payment date.

In [22]: leg = FixedLeg(
   ....:     schedule=Schedule(
   ....:         effective=dt(2000, 1, 1),
   ....:         termination=dt(2000, 7, 1),
   ....:         frequency="Q",
   ....:         payment_lag=1,
   ....:         payment_lag_exchange=0,
   ....:     ),
   ....:     fixed_rate=1.0,
   ....:     initial_exchange=True,
   ....:     mtm="payment",
   ....:     currency="usd",
   ....:     pair="eurusd",
   ....:     notional=10e6,                     # <- Leg settles in USD leg but reference cashflows in EUR
   ....:     amortization=4e6,
   ....:     fx_fixings=(1.25, "WMR_10AM_TY0_T+2"),  # <- Initial exchange rate and future fixings
   ....: )
   ....: 

In [23]: print(leg.cashflows())
          Type  Ccy    Payment    Notional    DF    Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  FX Fixing FX Fix Date Reference Ccy   Period Convention       DCF  Acc Start    Acc End  Rate  Spread
0     Cashflow  USD 2000-01-01 -10000000.0  None  12500000.0  None      1.0      USD    None       None       1.25  1999-12-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
1  FixedPeriod  USD 2000-04-02  10000000.0  None         NaN  None      1.0      USD    None       None        NaN  2000-03-30           EUR  Regular     Act360  0.252778 2000-01-01 2000-04-01   1.0     NaN
2     Cashflow  USD 2000-04-01   4000000.0  None         NaN  None      1.0      USD    None       None        NaN  2000-03-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
3  FixedPeriod  USD 2000-07-02   6000000.0  None         NaN  None      1.0      USD    None       None        NaN  2000-06-29           EUR  Regular     Act360  0.252778 2000-04-01 2000-07-01   1.0     NaN
4     Cashflow  USD 2000-07-01   6000000.0  None         NaN  None      1.0      USD    None       None        NaN  2000-06-29           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN

Amortization for a XCS takes places after the MtmCashflow.

In [24]: leg = FixedLeg(
   ....:     schedule=Schedule(
   ....:         effective=dt(2000, 1, 1),
   ....:         termination=dt(2000, 7, 1),
   ....:         frequency="Q",
   ....:         payment_lag=1,
   ....:         payment_lag_exchange=0,
   ....:     ),
   ....:     fixed_rate=1.0,
   ....:     initial_exchange=True,
   ....:     currency="usd",
   ....:     pair="eurusd",
   ....:     mtm="xcs",
   ....:     notional=10e6,
   ....:     amortization=4e6,
   ....:     fx_fixings=(1.25, "WMR_4PM_GMT_T+2"),
   ....: )
   ....: 

In [25]: print(leg.cashflows())
          Type  Ccy    Payment    Notional    DF      Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  FX Fixing FX Fix Date Reference Ccy   Period Convention       DCF  Acc Start    Acc End  Rate  Spread
0     Cashflow  USD 2000-01-01 -10000000.0  None  1.250000e+07  None      1.0      USD    None       None       1.25  1999-12-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
1  FixedPeriod  USD 2000-04-02  10000000.0  None -3.159722e+04  None      1.0      USD    None       None       1.25  1999-12-30           EUR  Regular     Act360  0.252778 2000-01-01 2000-04-01   1.0     NaN
2  MtmCashflow  USD 2000-04-01 -10000000.0  None           NaN  None      1.0      USD    None       None        NaN  2000-03-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
3     Cashflow  USD 2000-04-01   4000000.0  None           NaN  None      1.0      USD    None       None        NaN  2000-03-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
4  FixedPeriod  USD 2000-07-02   6000000.0  None           NaN  None      1.0      USD    None       None        NaN  2000-03-30           EUR  Regular     Act360  0.252778 2000-04-01 2000-07-01   1.0     NaN
5     Cashflow  USD 2000-07-01   6000000.0  None           NaN  None      1.0      USD    None       None        NaN  2000-03-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN

Indexation, Non-Deliverability and Amortization

In the most complicated case, which rarely even relates to real tradable instruments all of the parameters may be combined. The cashflows() method outlines the relevant fixing values and dates used in calculations.

In [26]: leg = FixedLeg(
   ....:     schedule=Schedule(
   ....:         effective=dt(2000, 1, 1),
   ....:         termination=dt(2000, 7, 1),
   ....:         frequency="Q",
   ....:         payment_lag=2,
   ....:         payment_lag_exchange=1
   ....:     ),
   ....:     fixed_rate=1.0,
   ....:     currency="usd",
   ....:     pair="eurusd",
   ....:     initial_exchange=True,
   ....:     notional=5e6,
   ....:     amortization=1000000,
   ....:     mtm="xcs",
   ....:     fx_fixings=(1.25, "WMR_10AM_TY0_T+2"),
   ....:     index_lag=0,
   ....:     index_fixings="MY_RPI",
   ....:     index_method="monthly",
   ....: )
   ....: 

In [27]: print(leg.cashflows())
          Type  Ccy    Payment   Notional    DF      Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  Index Base  Index Val  Index Ratio Index Fix Date  Unindexed Cashflow  FX Fixing FX Fix Date Reference Ccy   Period Convention       DCF  Acc Start    Acc End  Rate  Spread
0     Cashflow  USD 2000-01-02 -5000000.0  None  6.250000e+06  None      1.0      USD    None       None       101.0      101.0     1.000000     2000-01-01        6.250000e+06       1.25  1999-12-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
1  FixedPeriod  USD 2000-04-03  5000000.0  None -1.595503e+04  None      1.0      USD    None       None       101.0      102.0     1.009901     2000-04-01       -1.579861e+04       1.25  1999-12-30           EUR  Regular     Act360  0.252778 2000-01-01 2000-04-01   1.0     NaN
2  MtmCashflow  USD 2000-04-02 -5000000.0  None           NaN  None      1.0      USD    None       None       101.0      102.0     1.009901     2000-04-01                 NaN        NaN  2000-03-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
3     Cashflow  USD 2000-04-02  1000000.0  None           NaN  None      1.0      USD    None       None       101.0      102.0     1.009901     2000-04-01                 NaN        NaN  2000-03-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN
4  FixedPeriod  USD 2000-07-03  4000000.0  None           NaN  None      1.0      USD    None       None       101.0      103.0     1.019802     2000-07-01                 NaN        NaN  2000-03-30           EUR  Regular     Act360  0.252778 2000-04-01 2000-07-01   1.0     NaN
5     Cashflow  USD 2000-07-02  4000000.0  None           NaN  None      1.0      USD    None       None       101.0      103.0     1.019802     2000-07-01                 NaN        NaN  2000-03-30           EUR      NaN        NaN       NaN        NaT        NaT   NaN     NaN

Attributes Summary

`amortization`	The `Amortization` object associated with the schedule.
`fixed_rate`	The fixed rate parameter of each composited `FixedPeriod`.
`periods`	A list of all contained Periods.
`schedule`	The `Schedule` object of Leg.
`settlement_params`	The `_SettlementParams` associated with the first `FixedPeriod`.

Methods Summary

`analytic_delta`(*[, rate_curve, index_curve, ...])	Calculate the analytic rate delta of a Period expressed in a base currency.
`cashflows`(*[, rate_curve, disc_curve, ...])	Return aggregated cashflow data for the Leg.
`ex_div`(settlement)	Return a boolean whether the security is ex-div at the given settlement.
`local_analytic_delta`([rate_curve, ...])	Calculate the analytic rate delta of a Period expressed in its local settlement currency.
`local_analytic_rate_fixings`(*[, rate_curve, ...])	Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in local settlement currency of the Period.
`local_fixings`(identifiers[, scalars, ...])	Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.
`local_npv`(*[, rate_curve, index_curve, ...])	Calculate the NPV of the Leg expressed in local settlement currency.
`npv`(*[, rate_curve, index_curve, ...])	Calculate the NPV of the Period converted to any other base accounting currency.
`reset_fixings`([state])	Resets any fixings values of the Leg derived using the given data state.
`spread`(*, target_npv[, rate_curve, ...])	Calculate a spread metric which when applied to the Leg allows it to attain the target value.

Attributes Documentation

amortization#: The Amortization object associated with the schedule.

fixed_rate#: The fixed rate parameter of each composited FixedPeriod.

periods#: A list of all contained Periods.

schedule#: The Schedule object of Leg.

settlement_params#: The _SettlementParams associated with the first FixedPeriod.

Methods Documentation

analytic_delta(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, base=NoInput.blank, local=False, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the analytic rate delta of a Period expressed in a base currency.

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
base (str, optional) – The currency to convert the local settlement NPV to.
local (bool, optional) – An override flag to return a dict of NPV values indexed by string currency.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable

cashflows(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Return aggregated cashflow data for the Leg.

Warning

This method is a convenience method to provide a visual representation of all associated calculation data. Calling this method to extracting certain values should be avoided. It is more efficent to source relevant parameters or calculations from object attributes or other methods directly.

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
base (str, optional) – The currency to convert relevant values into.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

ex_div(settlement)#

Return a boolean whether the security is ex-div at the given settlement.

Parameters:: settlement (datetime) – The settlement date to test.
Return type:: bool

Notes

Uses the UK DMO convention of returning False if settlement is on or before the ex-div date for a regular coupon period.

This is evaluated by analysing the attribute pschedule3 of the associated Schedule object of the Leg.

local_analytic_delta(rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the analytic rate delta of a Period expressed in its local settlement currency.

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable

local_analytic_rate_fixings(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in local settlement currency of the Period.

If the Period has no sensitivity to rates fixings this DataFrame is empty.

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

local_fixings(identifiers, scalars=NoInput.blank, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.

Parameters:

indentifiers (Sequence of tuple[str, Series], required) – These are the series string identifiers and the data values that will be used in each Series to determine the sensitivity against.
scalars (Sequence of floats, optional (each set as 1.0)) – A sequence of scalars to multiply the sensitivities by for each on of the identifiers.
rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an class:~rateslib.fx.FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
settlement (datetime, optional (set as immediate date)) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional (set as settlement)) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

local_npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the NPV of the Leg expressed in local settlement currency.

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable

npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, base=NoInput.blank, local=False, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the NPV of the Period converted to any other base accounting currency.

Hint

If the cashflows are unspecified or incalculable due to missing information this method will raise an exception. For a function that returns a Result indicating success or failure use try_local_npv().

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
base (str, optional) – The currency to convert the local settlement NPV to.
local (bool, optional) – An override flag to return a dict of NPV values indexed by string currency.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable or dict of such indexed by string currency.

Notes

If base is not provided then this function will return the value obtained from try_local_npv().

If base is provided this then an FXForwards object may be required to perform conversions. An FXRates object is also allowed for this conversion although best practice does not recommend it due to possible settlement date conflicts.

reset_fixings(state=NoInput.blank)#

Resets any fixings values of the Leg derived using the given data state.

Parameters:: state (int, optional) – The state id of the data series that set the fixing. Only fixings determined by this data will be reset. If not given resets all fixings.
Return type:: None

spread(*, target_npv, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate a spread metric which when applied to the Leg allows it to attain the target value.

Parameters:

target_npv (DualTypes, required) – The target value of the Leg measured using all of the other given arguments. Must be expressed in local settlement currency units.
rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable

FixedLeg#

This Page