Defaults

Argument input management

The rateslib.default module is provided to give the user global control over a lot of parameters that are set by default when the user provides no input to those arguments.

Since financial instrument specification usually contains a large number of parameters (for example a cross-currency basis swap (XCS) has around 50 possible arguments to initialise the swap with), argument management is a key part of the design philosophy of rateslib.

The easiest way to construct conventional instruments is to use the spec argument. A number of market conventions have already been pre-added to rateslib, and if defining an Instrument that allows the spec (specification) argument a host of arguments will be pre-populated. The table below outlines all of the existing spec arguments.

Warning

When using the spec argument, arguments for leg2 which might normally inherit from leg1 might be defined specifically, and will no longer inherit. If overwriting an instrument that has been directly specified, ensure to overwrite both legs.

Derivatives

Currency	Calendar	IRS	XCS	FRA	SBS	STIRFuture	ZCS	ZCIS	IIRS	FXSwap	FXOption
USD	nyc, fed	usd_irs, usd_irs_lt_2y				usd_stir, usd_stir1
EUR	tgt	eur_irs, eur_irs3, eur_irs6, eur_irs1	eurusd_xcs, eurgbp_xcs	eur_fra3, eur_fra6, eur_fra1	eur_sbs36	eur_stir, eur_stir1, eur_stir3
GBP	ldn	gbp_irs	gbpusd_xcs, gbpeur_xcs			gbp_stir,
CHF	zur	chf_irs
SEK	stk	sek_irs, sek_irs3		sek_fra3
NOK	osl	nok_irs, nok_irs3, nok_irs6		nok_fra3, nok_fra6	nok_sbs36
CAD	tro	cad_irs, cad_irs_le_1y
JPY	tyo	jpy_irs	jpyusd_xcs
AUD	syd	aud_irs, aud_irs3, aud_irs6
NZD	wlg	nzd_irs3, nzd_irs6

Securities

Currency	FixedRateBond	Bill	IndexFixedRateBond	FloatRateNote
USD	us_gb, us_gb_tsy	us_gbb
EUR	de_gb, fr_gb, it_gb, nl_gb
GBP	uk_gb	uk_gbb
CHF
SEK	se_gb	se_gbb
NOK	no_gb
CAD	ca_gb
JPY
AUD
NZD

The NoInput argument

Warning

When an argument is not provided this actually assumes a defined datatype in rateslib called NoInput. Never use None as an entry to an argument, this will typically create downstream errors. It is better to omit the argument entry entirely and let rateslib control the NoInput value.

There are 3 types of NoInput that work behind the scenes:

• NoInput.blank: this specifies the user has provided no input for this argument and if there is a default value that will be used instead. For example, not providing a convention will result in the value of defaults.convention being used.

• NoInput.inherit: this specifies that the user has provided no input for this argument and its value will be inherited from the equivalent attribute on leg1. For example the value leg2_payment_lag has a value of NoInput.inherit meaning its value will be obtained from the value of payment_lag whether that is taken by default or set by a user.

• NoInput.negate: this is similar to NoInput.inherit except it negates the value. This is useful for notional and amortization when 2 legs commonly take opposite values.

In the below code snippet one can observe how these NoInputs are operating in the initialisation of a swap to infer what a user might expect when just inputting a small subset of parameters.

In [1]: from rateslib import IRS

In [2]: irs = IRS(
   ...:     effective=dt(2000, 1, 1),
   ...:     termination="1Y",
   ...:     frequency="S",
   ...:     payment_lag=4,
   ...:     notional=50e6,
   ...:     amortization=10e6
   ...: )
   ...: 

In [3]: irs.leg1.schedule.frequency
Out[3]: 'S'

In [4]: irs.leg1.schedule.payment_lag
Out[4]: 4

In [5]: irs.leg1.notional
Out[5]: 50000000.0

In [6]: irs.leg1.amortization
Out[6]: 10000000.0

In [7]: irs.leg2.schedule.frequency  # <- Inherited
Out[7]: 'S'

In [8]: irs.leg2.schedule.payment_lag  # <- Inherited
Out[8]: 4

In [9]: irs.leg2.notional  # <- Inherited with negate
Out[9]: -50000000.0

In [10]: irs.leg2.amortization  # <- Inherited with negate
Out[10]: -10000000.0

Defaults

The defaults object is a global instance of the Defaults class. Its purpose is to provide necessary values when a user does not supply inputs. In the above swap the user provided no convention, modifier or currency. These have been set by default.

In [11]: irs.leg1.schedule.modifier
Out[11]: 'MF'

In [12]: irs.leg1.convention
Out[12]: 'ACT360'

In [13]: irs.leg1.currency
Out[13]: 'usd'

The defaults values can be seen by calling its print() method.

In [14]: from rateslib import defaults

In [15]: print(defaults.print())
Scheduling:

	stub: SHORTFRONT
	stub_length: SHORT
	modifier: MF
	eom: False
	eom_fx: True
	eval_mode: swaps_align
	frequency_months: {'M': 1, 'B': 2, 'Q': 3, 'T': 4, 'S': 6, 'A': 12, 'Z': 100000000.0}

Instruments:

	convention: ACT360
	payment_lag: 2
	payment_lag_exchange: 0
	payment_lag_specific: {'IRS': 2, 'STIRFuture': 0, 'IIRS': 2, 'ZCS': 2, 'ZCIS': 0, 'FXSwap': 0, 'SBS': 2, 'Swap': 2, 'XCS': 2, 'FixedRateBond': 0, 'IndexFixedRateBond': 0, 'FloatRateNote': 0, 'Bill': 0, 'FRA': 0}
	notional: 1000000.0
	fixing_method: rfr_payment_delay
	fixing_method_param: {'rfr_payment_delay': 0, 'rfr_observation_shift': 2, 'rfr_lockout': 2, 'rfr_lookback': 2, 'rfr_payment_delay_avg': 0, 'rfr_observation_shift_avg': 2, 'rfr_lockout_avg': 2, 'rfr_lookback_avg': 2, 'ibor': 2}
	spread_compound_method: none_simple
	base_currency: usd

Curves:

	interpolation: {'Curve': 'log_linear', 'LineCurve': 'linear', 'IndexCurve': 'linear_index'}
	endpoints: natural
	multi_csa_steps: [2, 5, 10, 20, 30, 50, 77, 81, 86, 91, 96, 103, 110, 119, 128, 140, 153, 169, 188, 212, 242, 281, 332, 401, 498, 636, 835, 1104, 1407, 1646, 1766, 1808, 1821, 1824, 1825]

Solver:

	algorithm: levenberg_marquardt
	tag: v
	curve_not_in_solver: ignore

Miscellaneous:

	headers: {'type': 'Type', 'stub_type': 'Period', 'u_acc_start': 'Unadj Acc Start', 'u_acc_end': 'Unadj Acc End', 'a_acc_start': 'Acc Start', 'a_acc_end': 'Acc End', 'payment': 'Payment', 'convention': 'Convention', 'dcf': 'DCF', 'df': 'DF', 'notional': 'Notional', 'currency': 'Ccy', 'rate': 'Rate', 'spread': 'Spread', 'npv': 'NPV', 'cashflow': 'Cashflow', 'fx': 'FX Rate', 'npv_fx': 'NPV Ccy', 'real_cashflow': 'Real Cashflow', 'index_value': 'Index Val', 'index_ratio': 'Index Ratio', 'index_base': 'Index Base', 'collateral': 'Collateral', 'pair': 'Pair', 'expiry': 'Expiry', 't_e': 'Time to Expiry', 'delivery': 'Delivery', 'model': 'Model', 'vol': 'Vol', 'strike': 'Strike'}
	no_fx_fixings_for_xcs: warn
	pool: 1

These values can also be set:

In [16]: defaults.convention = "ACT365F"

In [17]: defaults.base_currency = "gbp"

In [18]: irs = IRS(effective=dt(2022, 1, 1), termination="1Y", frequency="A")

In [19]: irs.leg1.convention  # <- uses new default value
Out[19]: 'ACT365F'

In [20]: irs.leg1.currency  # <- uses new default value
Out[20]: 'gbp'

In [21]: defaults.reset_defaults()  # <- reverse the changes.