STIRFuture#

class rateslib.instruments.STIRFuture(*args, price=NoInput.blank, contracts=1, bp_value=NoInput.blank, nominal=NoInput.blank, leg2_float_spread=NoInput.blank, leg2_spread_compound_method=NoInput.blank, leg2_fixings=NoInput.blank, leg2_fixing_method=NoInput.blank, leg2_method_param=NoInput.blank, **kwargs)#

Bases: IRS

Create a short term interest rate (STIR) future.

Parameters:

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

  • price (float) – The traded price of the future. Defined as 100 minus the fixed rate.

  • contracts (int) – The number of traded contracts.

  • bp_value (float.) – The value of 1bp on the contract as specified by the exchange, e.g. SOFR 3M futures are $25 per bp. This is not the same as tick value where the tick size can be different across different futures.

  • nominal (float) – The nominal value of the contract. E.g. SOFR 3M futures are $1mm. If not given will use the default notional.

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

  • leg2_float_spread (float, optional) – 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) – 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 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) – The method by which floating rates are determined, set by default. See notes.

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

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

Examples

Construct a curve to price the example.

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

Create the STIRFuture, and demonstrate the rate(), npv(),

In [2]: stir = STIRFuture(
   ...:      effective=dt(2022, 3, 16),
   ...:      termination=dt(2022, 6, 15),
   ...:      spec="usd_stir",
   ...:      curves=usd,
   ...:      price=99.50,
   ...:      contracts=10,
   ...:  )
   ...: 

In [3]: stir.rate(metric="price")
Out[3]: 96.47043430109322

In [4]: stir.npv()
Out[4]: -75739.14247266948

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 STIRFuture.

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

Return the properties of all legs 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 by summing legs.

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

Return the mid-market rate of the IRS.

spread()

Not implemented for STIRFuture.

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=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#

Return the analytic delta of the STIRFuture.

See BasePeriod.analytic_delta(). For STIRFuture this method requires no arguments.

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

Return the properties of all legs used in calculating cashflows.

See BaseDerivative.cashflows().

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

See BaseDerivative.npv().

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

Return the mid-market rate of the IRS.

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.

  • metric (str in {"rate", "price"}) – The calculation metric that will be returned.

Return type:

float, Dual or Dual2

Notes

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

spread()#

Not implemented for STIRFuture.