XCS#

class rateslib.instruments.XCS(*args, fixed=NoInput.blank, payment_lag_exchange=NoInput.blank, fixed_rate=NoInput.blank, float_spread=NoInput.blank, spread_compound_method=NoInput.blank, fixings=NoInput.blank, fixing_method=NoInput.blank, method_param=NoInput.blank, leg2_fixed=NoInput.blank, leg2_mtm=NoInput.blank, leg2_payment_lag_exchange=NoInput.inherit, leg2_fixed_rate=NoInput.blank, leg2_float_spread=NoInput.blank, leg2_fixings=NoInput.blank, leg2_fixing_method=NoInput.blank, leg2_method_param=NoInput.blank, leg2_spread_compound_method=NoInput.blank, fx_fixings=NoInput.blank, **kwargs)#

Bases: BaseDerivative

Create a cross-currency swap (XCS) composing relevant fixed or floating Legs.

MTM-XCSs will introduce a MTM Leg as Leg2.

Parameters:

  • args (tuple) – Required positional arguments for BaseDerivative.

  • fixed (bool, optional) – Whether leg1 is fixed or floating rate. Defaults to False.

  • payment_lag_exchange (int) – The number of business days by which to delay notional exchanges, aligned with the accrual schedule.

  • fixed_rate (float, optional) – If fixed, the fixed rate of leg1.

  • float_spread (float, optional) – If not fixed, the spread applied to the FloatLeg. Can be set to None and designated later, perhaps after a mid-market spread for all periods has been calculated.

  • spread_compound_method (str, optional) – If not fixed, the method to use for adding a floating spread to compounded rates. Available options are {“none_simple”, “isda_compounding”, “isda_flat_compounding”}.

  • fixings (float, list, or Series optional) – If not fixed, then if a float scalar, will be applied as the determined fixing for the first period. If a list of n fixings will be used as the fixings for the first n periods. If any sublist of length m is given, is used as the first m RFR fixings for that FloatPeriod. If a datetime indexed Series will use the fixings that are available in that object, and derive the rest from the curve.

  • fixing_method (str, optional) – If not fixed, the method by which floating rates are determined, set by default. See notes.

  • method_param (int, optional) – If not fixed A parameter that is used for the various fixing_method s. See notes.

  • leg2_fixed (bool, optional) – Whether leg2 is fixed or floating rate. Defaults to False

  • leg2_mtm (bool optional) – Whether leg2 is a mark-to-market leg. Defaults to True

  • leg2_payment_lag_exchange (int) – The number of business days by which to delay notional exchanges, aligned with the accrual schedule.

  • leg2_fixed_rate (float, optional) – If leg2_fixed, the fixed rate of leg2.

  • leg2_float_spread (float, optional) – If not leg2_fixed, the spread applied to the FloatLeg. Can be set to None and designated later, perhaps after a mid-market spread for all periods has been calculated.

  • leg2_spread_compound_method (str, optional) – If not leg2_fixed, the method to use for adding a floating spread to compounded rates. Available options are {“none_simple”, “isda_compounding”, “isda_flat_compounding”}.

  • leg2_fixings (float, list, or Series optional) – If not leg2_fixed, then if a float scalar, will be applied as the determined fixing for the first period. If a list of n fixings will be used as the fixings for the first n periods. If any sublist of length m is given, is used as the first m RFR fixings for that FloatPeriod. If a datetime indexed Series will use the fixings that are available in that object, and derive the rest from the curve.

  • leg2_fixing_method (str, optional) – If not leg2_fixed, the method by which floating rates are determined, set by default. See notes.

  • leg2_method_param (int, optional) – If not leg2_fixed A parameter that is used for the various fixing_method s. See notes.

  • fx_fixings (float, Dual, Dual2, list of such, optional) – Specify a known initial FX fixing or a list of such for mtm legs, where leg 1 is considered the domestic currency. For example for an ESTR/SOFR XCS in 100mm EUR notional a value of 1.10 for fx_fixings implies the notional on leg 2 is 110m USD. Fixings that are not specified will be forecast at pricing time with an FXForwards object.

  • kwargs (dict) – Required keyword arguments for BaseDerivative.

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.

fx_fixings

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 by summing legs.

rate([curves, solver, fx, leg])

Return the mid-market pricing parameter of the XCS.

spread(*args, **kwargs)

Alias for rate()

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

fx_fixings#
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 [4]: curve = Curve({dt(2021,1,1): 1.00, dt(2025,1,1): 0.83}, id="SONIA")

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

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

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

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

In [9]: irs.analytic_delta(curve, curve, fxr, "gbp")
Out[9]: 47156.00216054951
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:

  • 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().

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

Return the NPV of the derivative by summing legs.

Warning

If fx_fixing has not been set for the instrument requires fx as an FXForwards object to dynamically determine this.

See BaseDerivative.npv().

rate(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, leg=1)#

Return the mid-market pricing parameter of the XCS.

Parameters:

  • curves (list of Curves) –

    A list defines the following curves in the order:

    • Forecasting Curve for leg1 (if floating).

    • Discounting Curve for leg1.

    • Forecasting Curve for leg2 (if floating).

    • Discounting Curve for leg2.

  • solver (Solver, optional) – The numerical Solver that constructs Curve from calibrating instruments.

  • fx (FXForwards, optional) – The FX forwards object that is used to determine the initial FX fixing for determining leg2_notional, if not specified at initialisation, and for determining mark-to-market exchanges on mtm XCSs.

  • leg (int in [1, 2]) – The leg whose pricing parameter is to be determined.

Return type:

float, Dual or Dual2

Notes

Fixed legs have pricing parameter returned in percentage terms, and float legs have pricing parameter returned in basis point (bp) terms.

If the XCS type is specified without a fixed_rate on any leg then an implied float_spread will return as its originaly value or zero since the fixed rate used for calculation is the implied mid-market rate including the current float_spread parameter.

Examples

spread(*args, **kwargs)#

Alias for rate()