ZeroIndexLeg#

class rateslib.legs.ZeroIndexLeg(schedule, *, convention=NoInput.blank, notional=NoInput.blank, currency=NoInput.blank, initial_exchange=False, final_exchange=False, pair=NoInput.blank, fx_fixings=NoInput.blank, mtm=False, index_base=NoInput.blank, index_lag=NoInput.blank, index_method=NoInput.blank, index_fixings=NoInput.blank)#

Bases: _BaseLeg

A Leg composed of indexed Cashflow at termination, and possibly effective.

Examples

In [1]: fixings.add("CPI_UK", Series(index=[dt(2000, 1, 1), dt(2002, 1, 1)], data=[100.0, 115.0]))

In [2]: zil = ZeroIndexLeg(
   ...:     schedule=Schedule(
   ...:          effective=dt(2000, 2, 1),
   ...:          termination=dt(2002, 2, 1),
   ...:          frequency="Z",
   ...:     ),
   ...:     index_lag=1,
   ...:     index_fixings="CPI_UK",
   ...:     notional=10e6,
   ...: )
   ...: 

In [3]: zil.cashflows()
Out[3]: 
       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
0  Cashflow  USD 2002-02-01  10000000.0  None -1500000.0  None      1.0      USD    None       None       100.0      115.0         1.15     2002-02-01         -10000000.0

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. Only the start and end of the schedule are relevant for this Zero type Leg.

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.
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 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 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.
mtm (bool, optional (set to False)) –
Define whether the non-deliverability depends on a single FXFixing defined at the start of the Leg, or the end. Review the notes section 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.

Notes

A ZeroIndexLeg contains, at most, two Cashflow. Three structures can be configured:

One cashflow consisting of only the indexed amount relating to some notional value ( initial_exchange and final_exchange are both False)
One cashflow consisting of a notional amount plus its indexed amount (final_exchange is True)
Two cashflows (of opposite directions) exchanging notionals (initial_exchange and final_exchange are both True)

Non-deliverability

Non-deliverability behaves in the same way as a FixedLeg. If mtm is False then a single FXFixing defined by the effective date or an agreed transactional value is used for all cashflows.

With notional exchanges this same principle applies, since there are only upto two cashflows.

Without notional exchanges and setting mtm to True allows the FXFixing to have a delivery date equal to the future payment date of the cashflow.

Attributes Summary

`amortization`	The `Amortization` object associated with the schedule.
`periods`	A list of all contained Periods.
`schedule`	The `Schedule` object of Leg.
`settlement_params`	The `_SettlementParams` associated with the `Cashflow` at maturity.

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.
`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`(args, *kwargs)	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.

periods#: A list of all contained Periods.

schedule#: The Schedule object of Leg.

settlement_params#: The _SettlementParams associated with the Cashflow at maturity.

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

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(*args, **kwargs)#

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

ZeroIndexLeg#

This Page