FRA#

class rateslib.instruments.FRA(*args, fixed_rate=NoInput.blank, method_param=NoInput.blank, fixings=NoInput.blank, **kwargs)#

Bases: BaseDerivative

Create a forward rate agreement composing single period FixedLeg and FloatLeg valued in a customised manner.

Parameters:

  • args (dict) – Required positional args to BaseDerivative.

  • fixed_rate (float or None) – The fixed rate applied to the FixedLeg. If None will be set to mid-market when curves are provided.

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

  • fixings (float or list, optional) – 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 as the first m RFR fixings within individual curve and composed into the overall rate.

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

Notes

A FRA is a derivative whose FloatLeg fixing_method is set to “ibor”. Additionally, there is no concept of float_spread for the IBOR fixing rate on an FRA, and it is therefore set to 0.0.

Examples

Construct curves to price the example.

In [1]: eur3m = Curve(
   ...:     nodes={
   ...:         dt(2022, 1, 1): 1.0,
   ...:         dt(2023, 1, 1): 0.965,
   ...:         dt(2024, 1, 1): 0.94
   ...:     },
   ...:     id="eur3m",
   ...: )
   ...:

Create the FRA, and demonstrate the rate(), npv(), analytic_delta().

In [2]: fra = FRA(
   ...:     effective=dt(2023, 2, 15),
   ...:     termination="3M",
   ...:     frequency="Q",
   ...:     calendar="tgt",
   ...:     currency="eur",
   ...:     method_param=2,
   ...:     convention="Act360",
   ...:     notional=100e6,
   ...:     fixed_rate=2.617,
   ...:     curves=["eur3m"],
   ...: )
   ...: 

In [3]: fra.rate(curves=eur3m)
Out[3]: 2.5971685347783104

In [4]: fra.npv(curves=eur3m)
Out[4]: -4685.809351368945

In [5]: fra.analytic_delta(curve=eur3m)
Out[5]: 2362.815505051087

A DataFrame of cashflows().

In [6]: fra.cashflows(curves=eur3m)
Out[6]: 
  Type   Period  Ccy  Acc Start    Acc End    Payment Convention       DCF     Notional        DF Collateral   Rate      Spread     Cashflow          NPV  FX Rate      NPV Ccy
0  FRA  Regular  EUR 2023-02-15 2023-05-15 2023-02-15     Act360  0.247222  100000000.0  0.961882       None -2.617 -259.716853 -4871.500083 -4685.809351      1.0 -4685.809351

For accurate sensitivity calculations; delta() and gamma(), construct a curve model.

In [7]: irs_kws = dict(
   ...:     effective=dt(2022, 1, 1),
   ...:     frequency="A",
   ...:     leg2_frequency="Q",
   ...:     convention="30E360",
   ...:     leg2_convention="Act360",
   ...:     leg2_fixing_method="ibor",
   ...:     leg2_method_param=2,
   ...:     calendar="tgt",
   ...:     currency="eur",
   ...:     curves=["eur3m", "eur3m"],
   ...: )
   ...: 

In [8]: instruments = [
   ...:     IRS(termination="1Y", **irs_kws),
   ...:     IRS(termination="2Y", **irs_kws),
   ...: ]
   ...: 

In [9]: solver = Solver(
   ...:     curves=[eur3m],
   ...:     instruments=instruments,
   ...:     s=[1.55, 1.6],
   ...:     instrument_labels=["1Y", "2Y"],
   ...:     id="eur",
   ...: )
   ...: 
SUCCESS: `func_tol` reached after 4 iterations (levenberg_marquardt), `f_val`: 8.531977901052125e-16, `time`: 0.0156s

In [10]: fra.delta(solver=solver)
Out[10]: 
local_ccy                         eur
display_ccy                       eur
type        solver label             
instruments eur    1Y    -2375.628967
                   2Y     4766.744141

In [11]: fra.gamma(solver=solver)
Out[11]: 
type                                           instruments          
solver                                                 eur          
label                                                   1Y        2Y
local_ccy display_ccy type        solver label                      
eur       eur         instruments eur    1Y       0.595272 -0.483642
                                         2Y      -0.483642 -0.446091

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(curve[, disc_curve, fx, base])

Return the analytic delta of the FRA.

cashflow(curve)

Calculate the local currency cashflow on the FRA from current floating rate and fixed rate.

cashflows([curves, solver, fx, base])

Return the properties of the leg used in calculating cashflows.

cashflows_table([curves, solver, fx, base])

Aggregate the values derived from a cashflows() method on an Instrument.

delta(*args, **kwargs)

Calculate the delta of the Instrument.

exo_delta(*args, **kwargs)

Calculate the delta of the Instrument, measured against user defined Variable s.

fixings_table([curves, solver, fx, base, ...])

Return a DataFrame of fixing exposures on the FloatLeg.

gamma(*args, **kwargs)

Calculate the gamma of the Instrument.

npv([curves, solver, fx, base, local])

Return the NPV of the derivative.

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

Return the mid-market rate of the FRA.

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

analytic_delta(curve, disc_curve=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#

Return the analytic delta of the FRA.

For arguments see analytic_delta().

cashflow(curve)#

Calculate the local currency cashflow on the FRA from current floating rate and fixed rate.

Parameters:

curve (Curve or LineCurve,) – The forecasting curve for determining the floating rate.

Return type:

float, Dual or Dual2

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

Return the properties of the leg used in calculating cashflows.

Parameters:

  • args – Positional arguments supplied to cashflows().

  • kwargs – Keyword arguments supplied to cashflows().

Return type:

DataFrame

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

Aggregate the values derived from a cashflows() method on an Instrument.

Parameters:

  • curves (CurveType, str or list of such, optional) – Argument input to the underlying cashflows method of the Instrument.

  • solver (Solver, optional) – Argument input to the underlying cashflows method of the Instrument.

  • fx (float, FXRates, FXForwards, optional) – Argument input to the underlying cashflows method of the Instrument.

  • base (str, optional) – Argument input to the underlying cashflows method of the Instrument.

  • kwargs (dict) – Additional arguments input the underlying cashflows method of the Instrument.

Return type:

DataFrame

delta(*args, **kwargs)#

Calculate the delta of the Instrument.

For arguments see Sensitivities.delta().

exo_delta(*args, **kwargs)#

Calculate the delta of the Instrument, measured against user defined Variable s.

For arguments see Sensitivities.exo_delta().

fixings_table(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, approximate=False, right=NoInput.blank)#

Return a DataFrame of fixing exposures on the FloatLeg.

Parameters:

  • curves (Curve, str or list of such) –

    A single Curve or id or a list of such. A list defines the following curves in the order:

    • Forecasting Curve for floating leg.

    • Discounting Curve for both legs.

  • solver (Solver, optional) –

    The numerical Solver that constructs Curve from calibrating instruments.

    Note

    The arguments fx and base are unused by single currency derivatives rates calculations.

  • approximate (bool, optional) – Perform a calculation that is broadly 10x faster but potentially loses precision upto 0.1%.

  • right (datetime, optional) – Only calculate fixing exposures upto and including this date.

Return type:

DataFrame

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.

See BaseDerivative.npv().

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

Return the mid-market rate of the FRA.

Only the forecasting curve is required to price an FRA.

Parameters:

  • curves (Curve, str or list of such) –

    A single Curve or id or a list of such. A list defines the following curves in the order:

    • Forecasting Curve for floating leg.

    • Discounting Curve for floating leg.

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

  • fx (unused)

  • base (unused)

Return type:

float, Dual or Dual2