BondFuture#

class rateslib.instruments.BondFuture(coupon=NoInput.blank, delivery=NoInput.blank, basket=NoInput.blank, nominal=NoInput.blank, contracts=NoInput.blank, calendar=NoInput.blank, currency=NoInput.blank, calc_mode=NoInput.blank, curves=NoInput.blank, spec=NoInput.blank, metric=NoInput.blank)#

Bases: _BaseInstrument

A bond future derivative containing a basket of FixedRateBond.

Examples

In [1]: bf = BondFuture(
   ...:      delivery=(dt(2000, 6, 1), dt(2000, 6, 30)),
   ...:      coupon=7.0,
   ...:      basket=[
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2009, 12, 7), spec="uk_gb", fixed_rate=5.75),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2011, 7, 12), spec="uk_gb", fixed_rate=9.00),
   ...:      ],
   ...:      nominal=100000,
   ...:      currency="gbp",
   ...:      calc_mode="ytm"
   ...: )
   ...: 

In [2]: bf.cfs
Out[2]: (0.9142254519590043, 1.152570524483184)

Pricing

The curves on individual bonds can be set directly on those Instruments, or the curves for the BondFuture will act, if given, as an override.

Any FixedRateBond requires one disc curve. The following input formats are allowed:

curves = curve | [curve]           #  a single curve is repeated for all required curves
curves = {"disc_curve": disc_curve}  # dict form is explicit

Parameters:

coupon (float) – The nominal coupon rate set on the contract specifications.
delivery (datetime or 2-tuple of datetimes) – The delivery window first and last delivery day, or a single delivery day.
basket (tuple of FixedRateBond) – The bonds that are available as deliverables.
nominal (float, optional) – The nominal amount of the contract.
contracts (int, optional) – The number of contracts owned or short.
calendar (str, optional) – The calendar to define delivery days within the delivery window.
currency (str, optional) – The currency (3-digit code) of the settlement contract.
calc_mode (str or BondCalcMode) – A calculation mode for determining conversion factors. See notes.
curves (_BaseCurve, str, dict, _Curves, Sequence, optional) – Pricing objects passed directly to the Instrument’s digital methods’ curves argument. See Pricing.
metric (str, optional (set as ‘clean_price’)) – The pricing metric returned by rate().
spec (str, optional) – A collective group of parameters. See default argument specifications.

Notes

Conversion factors (CFs) calc_mode are:

“ytm” which calculates the CF as the clean price percent of par with the bond having a yield-to-maturity on the first delivery day in the delivery window.
“ust_short” which applies to CME 2y, 3y and 5y treasury futures. See CME Treasury Conversion Factors.
“ust_long” which applies to CME 10y and 30y treasury futures.
“eurex_eur” which applies to EUREX EUR denominated government bond futures, except Italian BTPs which require a different CF formula.
“eurex_chf” which applies to EUREX CHF denominated government bond futures.
“ice_gbp” which applies to ICE Gilt futures.

Attributes Summary

`cfs`	Return the conversion factors for each bond in the ordered `basket`.
`kwargs`	The `_KWArgs` container for the Instrument.
`notional`	the number of contracts multiplied by contract nominal.
`rate_scalar`	A scaling quantity associated with the `Solver` risk calculations.
`settlement_params`	The default `_SettlementParams` of the Instrument.

Methods Summary

`analytic_delta`(*[, curves, solver, fx, vol, ...])	Calculate the analytic rate delta of a Leg of the Instrument.
`cashflows`(*[, curves, solver, fx, vol, ...])	Return aggregated cashflow data for the Instrument.
`cashflows_table`(*[, curves, solver, fx, ...])	Aggregate the values derived from a `cashflows()`, grouped by date, settlement currency and collateral.
`cms`(prices, settlement, shifts[, delivery, ...])	Perform CTD multi-security analysis.
`convexity`(future_price[, delivery])	Return the second derivative of `price` w.r.t.
`ctd_index`(future_price, prices, settlement)	Determine the index (base 0) of the CTD in the basket from implied repo rate.
`delta`(*[, curves, solver, fx, vol, base, ...])	Calculate delta risk of an Instrument against the calibrating instruments in a `Solver`.
`dlv`(future_price, prices, repo_rate, settlement)	Return an aggregated DataFrame of deliverable (dlv) metrics.
`duration`(future_price[, metric, delivery])	Return the (negated) derivative of `price` w.r.t.
`exo_delta`(*[, curves, solver, fx, vol, ...])	Calculate delta risk of an Instrument against some exogenous user created Variables, via a `Solver`.
`gamma`(*[, curves, solver, fx, vol, base, ...])	Calculate cross-gamma risk of an Instrument against the calibrating instruments of a `Solver`.
`gross_basis`(future_price, prices[, ...])	Calculate the gross basis of each bond in the basket.
`implied_repo`(future_price, prices, settlement)	Calculate the implied repo of each bond in the basket using the proceeds method.
`local_analytic_rate_fixings`(*[, curves, ...])	Calculate the sensitivity to rate fixings of the Instrument, expressed in local settlement currency per basis point.
`local_fixings`(identifiers[, scalars, ...])	Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.
`net_basis`(future_price, prices, repo_rate, ...)	Calculate the net basis of each bond in the basket via the proceeds method of repo.
`npv`(*[, curves, solver, fx, vol, base, ...])	Determine the monetary value of the bond future position.
`rate`(*[, curves, solver, fx, vol, base, ...])	Return various pricing metrics of the security calculated from `Curve` s.
`reset_fixings`([state])	Resets any fixings values of the Instrument derived using the given data state.
`spread`(*[, curves, solver, fx, vol, base, ...])	Calculate some pricing spread metric for the Instrument.
`ytm`(future_price[, delivery])	Calculate the yield-to-maturity of the bond future.

Attributes Documentation

cfs#

Return the conversion factors for each bond in the ordered basket.

Examples

In [1]: bf = BondFuture(
   ...:     delivery=(dt(2000, 6, 1), dt(2000, 6, 30)),
   ...:     coupon=7.0,
   ...:     basket=[
   ...:         FixedRateBond(dt(1999, 1, 1), dt(2009, 12, 7), fixed_rate=5.75, spec="uk_gb"),
   ...:         FixedRateBond(dt(1999, 1, 1), dt(2011, 7, 12), fixed_rate=9.00, spec="uk_gb"),
   ...:         FixedRateBond(dt(1999, 1, 1), dt(2010, 11, 25), fixed_rate=6.25, spec="uk_gb"),
   ...:         FixedRateBond(dt(1999, 1, 1), dt(2012, 8, 6), fixed_rate=9.00, spec="uk_gb"),
   ...:     ]
   ...: )
   ...: 

In [2]: bf.cfs
Out[2]: (0.9142254519590043, 1.152570524483184, 0.9449311626312816, 1.1619558330528528)

Return type:: tuple

Notes

The determination of conversion factors depend upon the calc_mode given at initialization. These values, under the appropriate method, can be compared with officially published exchange data such as that for UK gilts under the “ytm” method: ICE-LIFFE Jun23 Long Gilt, and values under the ‘eurex_eur’ see EUREX Jun23 Bond Futures.

kwargs#: The _KWArgs container for the Instrument.

notional#

the number of contracts multiplied by contract nominal.

Return type:: float, Dual, Dual2, Variable
Type:: The effective notional

rate_scalar#: A scaling quantity associated with the Solver risk calculations.

settlement_params#

The default _SettlementParams of the Instrument.

This is used to define a base currency when one is not specified.

Methods Documentation

analytic_delta(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, local=False, settlement=NoInput.blank, forward=NoInput.blank, leg=1)#

Calculate the analytic rate delta of a Leg of the Instrument.

Examples

In [1]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75})

In [2]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=1.0, curves=[curve])

In [3]: irs.analytic_delta()
Out[3]: 287.14750127899316

In [4]: irs.analytic_delta(local=True)
Out[4]: {'usd': 287.14750127899316}

Parameters:

curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.
fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.
vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.
local (bool, optional (set as False)) – An override flag to return a dict of NPV values indexed by string currency.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.
leg (int, optional (set as 1)) – The Leg over which to calculate the analytic rate delta.

Return type:

float, Dual, Dual2, Variable or dict of such indexed by string currency.

cashflows(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Return aggregated cashflow data for the Instrument.

Warning

This method is a convenience method to provide a visual representation of all associated calculation data. Calling this method to extract certain values should be avoided. It is more efficient to source relevant parameters or calculations from object attributes or other methods directly.

Examples

In [1]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=1.0)

In [2]: irs.cashflows()
Out[2]: 
               Type  Ccy    Payment   Notional   Period Convention       DCF  Acc Start    Acc End    DF      Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  Rate  Spread
leg1 0  FixedPeriod  USD 2001-01-04  1000000.0  Regular     Act360  1.013889 2000-01-03 2001-01-02  None -10138.888889  None      1.0      USD    None       None   1.0     NaN
     1  FixedPeriod  USD 2002-01-04  1000000.0  Regular     Act360  1.013889 2001-01-02 2002-01-02  None -10138.888889  None      1.0      USD    None       None   1.0     NaN
     2  FixedPeriod  USD 2003-01-06  1000000.0  Regular     Act360  1.013889 2002-01-02 2003-01-02  None -10138.888889  None      1.0      USD    None       None   1.0     NaN
leg2 0  FloatPeriod  USD 2001-01-04 -1000000.0  Regular     Act360  1.013889 2000-01-03 2001-01-02  None           NaN  None      1.0      USD    None       None   NaN     0.0
     1  FloatPeriod  USD 2002-01-04 -1000000.0  Regular     Act360  1.013889 2001-01-02 2002-01-02  None           NaN  None      1.0      USD    None       None   NaN     0.0
     2  FloatPeriod  USD 2003-01-06 -1000000.0  Regular     Act360  1.013889 2002-01-02 2003-01-02  None           NaN  None      1.0      USD    None       None   NaN     0.0

Providing relevant pricing objects will ensure all data that can be calculated is returned.

In [3]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75})

In [4]: irs.cashflows(curves=[curve])
Out[4]: 
               Type  Ccy    Payment   Notional   Period Convention       DCF  Acc Start    Acc End        DF      Cashflow           NPV  FX Rate Base Ccy       NPV Ccy Collateral      Rate  Spread
leg1 0  FixedPeriod  USD 2001-01-04  1000000.0  Regular     Act360  1.013889 2000-01-03 2001-01-02  0.971359 -10138.888889  -9848.496702      1.0      USD  -9848.496702       None  1.000000     NaN
     1  FixedPeriod  USD 2002-01-04  1000000.0  Regular     Act360  1.013889 2001-01-02 2002-01-02  0.943835 -10138.888889  -9569.435745      1.0      USD  -9569.435745       None  1.000000     NaN
     2  FixedPeriod  USD 2003-01-06  1000000.0  Regular     Act360  1.013889 2002-01-02 2003-01-02  0.916946 -10138.888889  -9296.817681      1.0      USD  -9296.817681       None  1.000000     NaN
leg2 0  FloatPeriod  USD 2001-01-04 -1000000.0  Regular     Act360  1.013889 2000-01-03 2001-01-02  0.971359  29161.694029  28326.461668      1.0      USD  28326.461668       None  2.876222     0.0
     1  FloatPeriod  USD 2002-01-04 -1000000.0  Regular     Act360  1.013889 2001-01-02 2002-01-02  0.943835  29161.694029  27523.820438      1.0      USD  27523.820438       None  2.876222     0.0
     2  FloatPeriod  USD 2003-01-06 -1000000.0  Regular     Act360  1.013889 2002-01-02 2003-01-02  0.916946  29161.694029  26739.710399      1.0      USD  26739.710399       None  2.876222     0.0

Parameters:

curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.
fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.
vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

cashflows_table(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Aggregate the values derived from a cashflows(), grouped by date, settlement currency and collateral.

Examples

In [5]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=1.0)

In [6]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75})

In [7]: irs.cashflows_table(curves=[curve])
Out[7]: 
local_ccy               USD
collateral_ccy          NaN
payment                    
2001-01-04      19022.80514
2002-01-04      19022.80514
2003-01-06      19022.80514

Parameters:

curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.
fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.
vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.
local (bool, optional (set as False)) – An override flag to return a dict of NPV values indexed by string currency.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

cms(prices, settlement, shifts, delivery=NoInput.blank, dirty=False)#

Perform CTD multi-security analysis.

Parameters:

prices (sequence of float, Dual, Dual2) – The prices of the bonds in the deliverable basket (ordered).
settlement (datetime) – The settlement date of the bonds.
shifts (Sequence[float]) – The scenarios to analyse.
delivery (datetime, optional) – The date of the futures delivery. If not given uses the final delivery day.
dirty (bool) – Whether the bond prices are given including accrued interest. Default is False.

Return type:

DataFrame

Notes

This method only operates when the CTD basket has multiple securities

convexity(future_price, delivery=NoInput.blank)#

Return the second derivative of price w.r.t. ytm .

Examples

In [1]: bf = BondFuture(
   ...:      delivery=(dt(2000, 6, 1), dt(2000, 6, 30)),
   ...:      coupon=7.0,
   ...:      basket=[
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2009, 12, 7), spec="uk_gb", fixed_rate=5.75),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2011, 7, 12), spec="uk_gb", fixed_rate=9.00),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2010, 11, 25), spec="uk_gb", fixed_rate=6.25),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2012, 8, 6), spec="uk_gb", fixed_rate=9.00),
   ...:      ],
   ...: )
   ...: 

In [2]: bf.convexity(future_price=112.98)
Out[2]: 
(0.7283734047260152,
 0.8301477419737853,
 0.8327576470088758,
 0.9509416768492502)

Parameters:

future_price (float) – The price of the future.
delivery (datetime, optional) – The delivery date of the contract. If not given uses the last delivery day in the delivery window.

Return type:

float

See also

FixedRateBond.duration: Calculation the risk of a FixedRateBond.

Example

In [3]: risk = future.duration(112.98)

In [4]: risk
Out[4]: (8.201785461109342, 8.501520935517126, 8.690350869656765, 9.041578306005308)

The difference in yield is shown to be 1bp for the CTD (index: 0) when the futures price is adjusted by the risk amount.

In [5]: future.ytm(112.98)
Out[5]: (5.301960107613952, 5.339807671821682, 5.391831098267723, 5.4375666033125265)

In [6]: future.ytm(112.98 + risk[0] / 100)
Out[6]: (5.291964545446789, 5.330164780163671, 5.382397556481121, 5.428499740157343)

exo_delta(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank, vars, vars_scalar=NoInput.blank, vars_labels=NoInput.blank)#

Calculate delta risk of an Instrument against some exogenous user created Variables, via a Solver.

See What are exogenous variables? in the cookbook.

Examples

This example calculates the risk of the fixed rate increasing by 1bp and the notional increasing by 1mm. Mathematically this should be equivalent to the npv and the analytic delta (although the calculation is based on AD and is completely independent of the solver).

In [7]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2002, 1, 1): 0.85, dt(2010, 1, 1): 0.75})

In [8]: solver = Solver(
   ...:     curves=[curve],
   ...:     instruments=[
   ...:         IRS(dt(2000, 1, 1), "2Y", spec="usd_irs", curves=[curve]),
   ...:         IRS(dt(2000, 1, 1), "5Y", spec="usd_irs", curves=[curve]),
   ...:     ],
   ...:     s=[2.0, 2.25],
   ...:     instrument_labels=["2Y", "5Y"],
   ...:     id="US_RATES"
   ...: )
   ...: 
SUCCESS: `func_tol` reached after 6 iterations (levenberg_marquardt), `f_val`: 8.499591036903249e-16, `time`: 0.0032s

In [9]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=Variable(3.0, ["R"]), notional=Variable(1e6, ["N"]), curves=[curve])

In [10]: irs.exo_delta(solver=solver, vars=["R", "N"], vars_scalar=[1e-2, 1e6])
Out[10]: 
local_ccy                          usd
display_ccy                        usd
type      solver   label              
exogenous US_RATES R       -291.752073
                   N     -25123.690181

In [11]: irs.analytic_delta()
Out[11]: <Dual: 291.752073, (N, 8aff00, 8aff01, ...), [0.0, 49.2, 239.9, ...]>

In [12]: irs.npv()
Out[12]: <Dual: -25123.690181, (N, R, 8aff00, ...), [-0.0, -29175.2, 982218.9, ...]>

Parameters:

curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, required) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.
fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.
vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.
vars (list[str], required) – The variable tags which to determine sensitivities for.
vars_scalar (list[float], optional) – Scaling factors for each variable, for example converting rates to basis point etc. Defaults to ones.
vars_labels (list[str], optional) – Alternative names to relabel variables in DataFrames.

Return type:

DataFrame

gamma(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate cross-gamma risk of an Instrument against the calibrating instruments of a Solver.

Examples

In [13]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2002, 1, 1): 0.85, dt(2010, 1, 1): 0.75})

In [14]: solver = Solver(
   ....:     curves=[curve],
   ....:     instruments=[
   ....:         IRS(dt(2000, 1, 1), "2Y", spec="usd_irs", curves=[curve]),
   ....:         IRS(dt(2000, 1, 1), "5Y", spec="usd_irs", curves=[curve]),
   ....:     ],
   ....:     s=[2.0, 2.25],
   ....:     instrument_labels=["2Y", "5Y"],
   ....:     id="US_RATES"
   ....: )
   ....: 
SUCCESS: `func_tol` reached after 6 iterations (levenberg_marquardt), `f_val`: 8.499591036903249e-16, `time`: 0.0037s

In [15]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", curves=[curve])

In [16]: irs.gamma(solver=solver)
Out[16]: 
type                                             instruments          
solver                                              US_RATES          
label                                                     2Y        5Y
local_ccy display_ccy type        solver   label                      
usd       usd         instruments US_RATES 2Y      -0.029442 -0.038104
                                           5Y      -0.038104 -0.010190

Parameters:

curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, required) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.
fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.
vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

Notes

Gamma measures the second order cross-sensitivity of the PV to a change in any of the calibrating instruments of the given Solver. Values are returned according to the rate_scalar quantity at an Instrument level and according to the metric used to derive the rate() method of each Instrument.

gross_basis(future_price, prices, settlement=NoInput.blank, dirty=False)#

Calculate the gross basis of each bond in the basket.

Exmaples

In [1]: bf = BondFuture(
   ...:      delivery=(dt(2000, 6, 1), dt(2000, 6, 30)),
   ...:      coupon=7.0,
   ...:      basket=[
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2009, 12, 7), spec="uk_gb", fixed_rate=5.75, calendar="bus"),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2011, 7, 12), spec="uk_gb", fixed_rate=9.00, calendar="bus"),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2010, 11, 25), spec="uk_gb", fixed_rate=6.25, calendar="bus"),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2012, 8, 6), spec="uk_gb", fixed_rate=9.00, calendar="bus"),
   ...:      ],
   ...:      nominal=100000,
   ...:      contracts=10,
   ...:      currency="gbp",
   ...: )
   ...: 

In [2]: bf.gross_basis(
   ...:     future_price=112.98,
   ...:     prices=[102.732, 131.461, 107.877, 134.455],
   ...:     settlement=dt(2000, 3, 16),
   ...: )
   ...: 
Out[2]: 
(-0.5571915623283132,
 1.2435821438898813,
 1.1186772459177945,
 3.177229981688697)

Parameters:

future_price (float, Dual, Dual2) – The price of the future.
prices (sequence of float, Dual, Dual2) – The prices of the bonds in the deliverable basket (ordered).
settlement (datetime) – The settlement date of the bonds, required only if dirty is True.
dirty (bool) – Whether the bond prices are given including accrued interest.

Return type:

tuple

implied_repo(future_price, prices, settlement, delivery=NoInput.blank, convention=NoInput.blank, dirty=False)#

Calculate the implied repo of each bond in the basket using the proceeds method.

Examples

In [1]: bf = BondFuture(
   ...:      delivery=(dt(2000, 6, 1), dt(2000, 6, 30)),
   ...:      coupon=7.0,
   ...:      basket=[
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2009, 12, 7), spec="uk_gb", fixed_rate=5.75),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2011, 7, 12), spec="uk_gb", fixed_rate=9.00),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2010, 11, 25), spec="uk_gb", fixed_rate=6.25),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2012, 8, 6), spec="uk_gb", fixed_rate=9.00),
   ...:      ],
   ...: )
   ...: 

In [2]: future.implied_repo(
   ...:     future_price=112.98,
   ...:     prices=[102.732, 131.461, 107.877, 134.455],
   ...:     settlement=dt(2000, 3, 16),
   ...:     convention="Act365F",
   ...: )
   ...: 
Out[2]: 
(7.381345196635331,
 3.5646853481343777,
 2.1997545597624004,
 -1.4146703289488534)

Parameters:

future_price (float, Dual, Dual2) – The price of the future.
prices (sequence of float, Dual, Dual2) – The prices of the bonds in the deliverable basket (ordered).
settlement (datetime) – The settlement date of the bonds.
delivery (datetime, optional) – The date of the futures delivery. If not given uses the final delivery day.
convention (str, optional) – The day count convention used in the rate.
dirty (bool) – Whether the bond prices are given including accrued interest.

Return type:

tuple

local_analytic_rate_fixings(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the sensitivity to rate fixings of the Instrument, expressed in local settlement currency per basis point.

Examples

In [1]: curve1 = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75}, id="Eur1mCurve")

In [2]: curve3 = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.70}, id="Eur3mCurve")

In [3]: irs = IRS(dt(2000, 1, 1), "20m", spec="eur_irs3", curves=[{"1m": curve1, "3m": curve3}, curve1])

In [4]: irs.local_analytic_rate_fixings()
Out[4]: 
identifier  Eur1mCurve Eur3mCurve
local_ccy          eur        eur
display_ccy        eur        eur
frequency           1M         3M
obs_dates                        
1999-12-30     8.81934   7.215824
2000-02-28         NaN  25.251470
2000-05-30         NaN  25.069179
2000-08-30         NaN  24.619619
2000-11-29         NaN  24.177105
2001-02-27         NaN  24.535960
2001-05-30         NaN  24.884455

Parameters:

curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.
fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.
vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

Notes

This analytic method will index the sensitivities with series identifier according to the Curve id which has forecast the fixing.

local_fixings(identifiers, scalars=NoInput.blank, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.

Parameters:

identifiers (Sequence of tuple[str, Series], required) – These are the series string identifiers and the data values that will be used in each Series to determine the sensitivity against.
scalars (Sequence of floats, optional (each set as 1.0)) – A sequence of scalars to multiply the sensitivities by for each on of the identifiers.
curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.
fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.
vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

net_basis(future_price, prices, repo_rate, settlement, delivery=NoInput.blank, convention=NoInput.blank, dirty=False)#

Calculate the net basis of each bond in the basket via the proceeds method of repo.

Examples

In [1]: bf = BondFuture(
   ...:     delivery=(dt(2000, 6, 1), dt(2000, 6, 30)),
   ...:     coupon=7.0,
   ...:     basket=[
   ...:         FixedRateBond(dt(1999, 1, 1), dt(2009, 12, 7), fixed_rate=5.75, spec="uk_gb"),
   ...:         FixedRateBond(dt(1999, 1, 1), dt(2011, 7, 12), fixed_rate=9.00, spec="uk_gb"),
   ...:         FixedRateBond(dt(1999, 1, 1), dt(2010, 11, 25), fixed_rate=6.25, spec="uk_gb"),
   ...:         FixedRateBond(dt(1999, 1, 1), dt(2012, 8, 6), fixed_rate=9.00, spec="uk_gb"),
   ...:     ]
   ...: )
   ...: 

In [2]: bf.net_basis(
   ...:     future_price=112.98,
   ...:     prices=[102.732, 131.461, 107.877, 134.455],
   ...:     settlement=dt(2000, 3, 16),
   ...:     repo_rate=6.24,
   ...:     convention="Act365F",
   ...: )
   ...: 
Out[2]: 
(-0.3436542561467064,
 1.0336684511125043,
 1.275866135927373,
 3.0103709249974315)

Parameters:

future_price (float, Dual, Dual2) – The price of the future.
prices (sequence of float, Dual, Dual2) – The prices of the bonds in the deliverable basket (ordered).
repo_rate (float, Dual, Dual2 or list/tuple of such) – The repo rates of the bonds to delivery.
settlement (datetime) – The settlement date of the bonds, required only if dirty is True.
delivery (datetime, optional) – The date of the futures delivery. If not given uses the final delivery day.
convention (str, optional) – The day count convention applied to the repo rates.
dirty (bool) – Whether the bond prices are given including accrued interest.

Return type:

tuple

npv(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, local=False, settlement=NoInput.blank, forward=NoInput.blank)#

Determine the monetary value of the bond future position.

This method is mainly included to calculate risk sensitivities. The monetary value of bond futures is not usually a metric worth considering. The profit or loss of a position based on entry level is a more common metric, however the initial value of the position does not affect the risk.

See BaseDerivative.npv().

rate(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank, metric=NoInput.blank)#

Return various pricing metrics of the security calculated from Curve s.

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 leg1.
- Discounting Curve for leg1.
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), set by default. Only used if fx is an FXRates or FXForwards object.
metric (str in {"future_price", "ytm"}, optional) – Metric returned by the method.
delivery (datetime, optional) – The date of the futures delivery. If not given uses the final delivery day.

Return type:

float, Dual, Dual2

Notes

This method determines the ‘futures_price’ and ‘ytm’ by assuming a net basis of zero and pricing from the cheapest to delivery (CTD).

reset_fixings(state=NoInput.blank)#

Resets any fixings values of the Instrument derived using the given data state.

Parameters:: state (int, optional) – The state id of the data series that set the fixing. Only fixings determined by this data will be reset. If not given resets all fixings.
Return type:: None

spread(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate some pricing spread metric for the Instrument.

This calculation may be an alias for rate() with a specific metric and is designated at an Instrument level.

Examples

The ‘spread’ on an IRS is the float leg spread to equate value with the fixed leg.

In [3]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75})

In [4]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", curves=[curve], fixed_rate=2.0)

In [5]: irs.spread()       # <- `spread` on float leg to equate value with fixed leg
Out[5]: -87.62218768432399

Parameters:

curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.
fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.
vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.
local (bool, optional (set as False)) – An override flag to return a dict of NPV values indexed by string currency.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable

ytm(future_price, delivery=NoInput.blank)#

Calculate the yield-to-maturity of the bond future.

The relevant ytm should be selected according to the CTD index.

Examples

In [1]: bf = BondFuture(
   ...:      delivery=(dt(2000, 6, 1), dt(2000, 6, 30)),
   ...:      coupon=7.0,
   ...:      basket=[
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2009, 12, 7), spec="uk_gb", fixed_rate=5.75),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2011, 7, 12), spec="uk_gb", fixed_rate=9.00),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2010, 11, 25), spec="uk_gb", fixed_rate=6.25),
   ...:          FixedRateBond(dt(1999, 1, 1), dt(2012, 8, 6), spec="uk_gb", fixed_rate=9.00),
   ...:      ],
   ...: )
   ...: 

In [2]: bf.ytm(future_price=112.98)
Out[2]: (5.301960107613952, 5.339807671821682, 5.391831098267723, 5.4375666033125265)

Parameters:

future_price (float, Dual, Dual2) – The price of the future.
delivery (datetime, optional) – The future delivery day on which to calculate the yield. If not given aligns with the last delivery day specified on the future.

Return type:

tuple

BondFuture#

This Page