BaseDerivative#

class rateslib.instruments.BaseDerivative(effective=NoInput.blank, termination=NoInput.blank, frequency=NoInput.blank, stub=NoInput.blank, front_stub=NoInput.blank, back_stub=NoInput.blank, roll=NoInput.blank, eom=NoInput.blank, modifier=NoInput.blank, calendar=NoInput.blank, payment_lag=NoInput.blank, notional=NoInput.blank, currency=NoInput.blank, amortization=NoInput.blank, convention=NoInput.blank, leg2_effective=NoInput.inherit, leg2_termination=NoInput.inherit, leg2_frequency=NoInput.inherit, leg2_stub=NoInput.inherit, leg2_front_stub=NoInput.inherit, leg2_back_stub=NoInput.inherit, leg2_roll=NoInput.inherit, leg2_eom=NoInput.inherit, leg2_modifier=NoInput.inherit, leg2_calendar=NoInput.inherit, leg2_payment_lag=NoInput.inherit, leg2_notional=NoInput.negate, leg2_currency=NoInput.inherit, leg2_amortization=NoInput.negate, leg2_convention=NoInput.inherit, curves=NoInput.blank, spec=NoInput.blank)#

Bases: Sensitivities, BaseMixin

Abstract base class with common parameters for many Derivative subclasses.

Parameters:

effective (datetime) – The adjusted or unadjusted effective date.
termination (datetime or str) – The adjusted or unadjusted termination date. If a string, then a tenor must be given expressed in days (“D”), months (“M”) or years (“Y”), e.g. “48M”.
frequency (str in {"M", "B", "Q", "T", "S", "A", "Z"}, optional) – The frequency of the schedule.
stub (str combining {"SHORT", "LONG"} with {"FRONT", "BACK"}, optional) – The stub type to enact on the swap. Can provide two types, for example “SHORTFRONTLONGBACK”.
front_stub (datetime, optional) – An adjusted or unadjusted date for the first stub period.
back_stub (datetime, optional) – An adjusted or unadjusted date for the back stub period. See notes for combining stub, front_stub and back_stub and any automatic stub inference.
roll (int in [1, 31] or str in {"eom", "imm", "som"}, optional) – The roll day of the schedule. Inferred if not given.
eom (bool, optional) – Use an end of month preference rather than regular rolls for inference. Set by default. Not required if roll is specified.
modifier (str, optional) – The modification rule, in {“F”, “MF”, “P”, “MP”}
calendar (calendar or str, optional) – The holiday calendar object to use. If str, looks up named calendar from static data.
payment_lag (int, optional) – The number of business days to lag payments by.
notional (float, optional) – The leg notional, which is applied to each period.
amortization (float, optional) – The amount by which to adjust the notional each successive period. Should have sign equal to that of notional if the notional is to reduce towards zero.
convention (str, optional) – The day count convention applied to calculations of period accrual dates. See dcf().
leg2_kwargs (Any) – All leg2 arguments can be similarly input as above, e.g. leg2_frequency. If not given, any leg2 argument inherits its value from the leg1 arguments, except in the case of notional and amortization where leg2 inherits the negated value.
curves (Curve, LineCurve, str or list of such, optional) –
A single Curve, LineCurve or id or a list of such. A list defines the following curves in the order:
- Forecasting Curve or LineCurve for leg1.
- Discounting Curve for leg1.
- Forecasting Curve or LineCurve for leg2.
- Discounting Curve for leg2.
spec (str, optional) – An identifier to pre-populate many field with conventional values. See here for more info and available values.

effective#

Type:: datetime

termination#

Type:: datetime

frequency#

Type:: str

stub#

Type:: str

front_stub#

Type:: datetime

back_stub#

Type:: datetime

roll#

Type:: str, int

eom#

Type:: bool

modifier#

Type:: str

calendar#

Type:: Calendar

payment_lag#

Type:: int

notional#

Type:: float

amortization#

Type:: float

convention#

Type:: str

leg2_effective#

Type:: datetime

leg2_termination#

Type:: datetime

leg2_frequency#

Type:: str

leg2_stub#

Type:: str

leg2_front_stub#

Type:: datetime

leg2_back_stub#

Type:: datetime

leg2_roll#

Type:: str, int

leg2_eom#

Type:: bool

leg2_modifier#

Type:: str

leg2_calendar#

Type:: Calendar

leg2_payment_lag#

Type:: int

leg2_notional#

Type:: float

leg2_amortization#

Type:: float

leg2_convention#

Type:: str

Attributes Summary

`fixed_rate`	If set will also set the `fixed_rate` of the contained leg1.
`float_spread`	If set will also set the `float_spread` of contained leg1.
`index_base`	If set will also set the `index_base` of the contained leg1.
`leg2_fixed_rate`	If set will also set the `fixed_rate` of the contained leg2.
`leg2_float_spread`	If set will also set the `float_spread` of contained leg2.
`leg2_index_base`	If set will also set the `index_base` of the contained leg1.

Methods Summary

`analytic_delta`(*args[, leg])	Return the analytic delta of a leg of the derivative object.
`cashflows`([curves, solver, fx, base])	Return the properties of all legs used in calculating cashflows.
`cashflows_table`([curves, solver, fx, base])
`delta`(args, *kwargs)	Calculate the delta of the Instrument.
`gamma`(args, *kwargs)	Calculate the gamma of the Instrument.
`npv`([curves, solver, fx, base, local])	Return the NPV of the derivative object by summing legs.
`rate`(args, *kwargs)	Return the rate or typical price for a derivative instrument.

Attributes Documentation

fixed_rate#

If set will also set the fixed_rate of the contained leg1.

Note

fixed_rate, float_spread, leg2_fixed_rate and leg2_float_spread are attributes only applicable to certain Instruments. AttributeErrors are raised if calling or setting these is invalid.

Type:: float or None

float_spread#

If set will also set the float_spread of contained leg1.

Type:: float or None

index_base#

If set will also set the index_base of the contained leg1.

Note

index_base and leg2_index_base are attributes only applicable to certain Instruments. AttributeErrors are raised if calling or setting these is invalid.

Type:: float or None

leg2_fixed_rate#

If set will also set the fixed_rate of the contained leg2.

Type:: float or None

leg2_float_spread#

If set will also set the float_spread of contained leg2.

Type:: float or None

leg2_index_base#

If set will also set the index_base of the contained leg1.

Note

index_base and leg2_index_base are attributes only applicable to certain Instruments. AttributeErrors are raised if calling or setting these is invalid.

Type:: float or None

Methods Documentation

abstract analytic_delta(*args, leg=1, **kwargs)#

Return the analytic delta of a leg of the derivative object.

Parameters:

args – Required positional arguments supplied to BaseLeg.analytic_delta.
leg (int in [1, 2]) – The leg identifier of which to take the analytic delta.
kwargs – Required Keyword arguments supplied to BaseLeg.analytic_delta().

Return type:

float, Dual, Dual2

Examples

In [1]: curve = Curve({dt(2021,1,1): 1.00, dt(2025,1,1): 0.83}, id="SONIA")

In [2]: fxr = FXRates({"gbpusd": 1.25}, base="usd")

In [3]: irs = IRS(
   ...:     effective=dt(2022, 1, 1),
   ...:     termination="6M",
   ...:     frequency="Q",
   ...:     currency="gbp",
   ...:     notional=1e9,
   ...:     fixed_rate=5.0,
   ...: )
   ...: 

In [4]: irs.analytic_delta(curve, curve)
Out[4]: 47156.00216054951

In [5]: irs.analytic_delta(curve, curve, fxr)
Out[5]: <Dual: 58945.002701, (fx_gbpusd), [47156.0]>

In [6]: irs.analytic_delta(curve, curve, fxr, "gbp")
Out[6]: 47156.00216054951

abstract cashflows(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#

Return the properties of all legs used in calculating cashflows.

Parameters:

curves (CurveType, str or list of such, optional) –
A single Curve, LineCurve or id or a list of such. A list defines the following curves in the order:
- Forecasting Curve or LineCurve for leg1.
- Discounting Curve for leg1.
- Forecasting Curve or LineCurve for leg2.
- Discounting Curve for leg2.
solver (Solver, optional) – The numerical Solver that constructs Curves from calibrating instruments.
fx (float, FXRates, FXForwards, optional) – The immediate settlement FX rate that will be used to convert values into another currency. A given float is used directly. If giving a FXRates or FXForwards object, converts from local currency into base.
base (str, optional) – The base currency to convert cashflows into (3-digit code). Only used if fx is an FXRates or FXForwards object. If not given defaults to fx.base.

Return type:

DataFrame

Notes

If only one curve is given this is used as all four curves.

If two curves are given the forecasting curve is used as the forecasting curve on both legs and the discounting curve is used as the discounting curve for both legs.

If three curves are given the single discounting curve is used as the discounting curve for both legs.

Examples

In [1]: irs.cashflows([curve], fx=fxr)
Out[1]: 
               Type   Period  Ccy  Acc Start    Acc End    Payment Convention  DCF       Notional   DF Collateral  Rate  Spread     Cashflow          NPV  FX Rate      NPV Ccy
leg1 0  FixedPeriod  Regular  GBP 2022-01-01 2022-04-01 2022-04-03     ACT360 0.25  1000000000.00 0.94       None  5.00     NaN -12500000.00 -11792277.34     1.25 -14740346.67
     1  FixedPeriod  Regular  GBP 2022-04-01 2022-07-01 2022-07-03     ACT360 0.25  1000000000.00 0.93       None  5.00     NaN -12638888.89 -11785723.74     1.25 -14732154.68
leg2 0  FloatPeriod  Regular  GBP 2022-01-01 2022-04-01 2022-04-03     ACT360 0.25 -1000000000.00 0.94       None  4.62    0.00  11544335.50  10890720.47     1.25  13613400.59
     1  FloatPeriod  Regular  GBP 2022-04-01 2022-07-01 2022-07-03     ACT360 0.25 -1000000000.00 0.93       None  4.62    0.00  11673351.69  10885363.37     1.25  13606704.21

cashflows_table(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#

delta(*args, **kwargs)#

Calculate the delta of the Instrument.

For arguments see Sensitivities.delta().

gamma(*args, **kwargs)#

Calculate the gamma of the Instrument.

For arguments see Sensitivities.gamma().

abstract npv(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, local=False)#

Return the NPV of the derivative object by summing legs.

Parameters:

curves (Curve, LineCurve, str or list of such) –
A single Curve, LineCurve or id or a list of such. A list defines the following curves in the order:
- Forecasting Curve or LineCurve for leg1.
- Discounting Curve for leg1.
- Forecasting Curve or LineCurve for leg2.
- Discounting Curve for leg2.
solver (Solver, optional) – The numerical Solver that constructs Curves from calibrating instruments.
fx (float, FXRates, FXForwards, optional) – The immediate settlement FX rate that will be used to convert values into another currency. A given float is used directly. If giving a FXRates or FXForwards object, converts from local currency into base.
base (str, optional) – The base currency to convert cashflows into (3-digit code). Only used if fx is an FXRates or FXForwards object. If not given defaults to fx.base.
local (bool, optional) – If True will return a dict identifying NPV by local currencies on each leg. Useful for multi-currency derivatives and for ensuring risk sensitivities are allocated to local currencies without conversion.

Return type:

float, Dual or Dual2, or dict of such.

Notes

If only one curve is given this is used as all four curves.

If two curves are given the forecasting curve is used as the forecasting curve on both legs and the discounting curve is used as the discounting curve for both legs.

If three curves are given the single discounting curve is used as the discounting curve for both legs.

Examples

In [1]: irs.npv(curve)
Out[1]: -1801917.2427669652

In [2]: irs.npv([curve], fx=fxr)
Out[2]: <Dual: -2252396.553459, (fx_gbpusd), [-1801917.2]>

In [3]: irs.npv([curve], fx=fxr, base="gbp")
Out[3]: -1801917.2427669652

abstract rate(*args, **kwargs)#

Return the rate or typical price for a derivative instrument.

Return type:: Dual

Notes

This method must be implemented for instruments to function effectively in Solver iterations.