BondMixin#

class rateslib.instruments.BondMixin#

Bases: object

Inheritable class to provide basic functionality.

Methods Summary

analytic_delta([curve, disc_curve, fx, base])

Return the analytic delta of the security via summing all periods.

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

Return the properties of the security used in calculating cashflows.

ex_div(settlement)

Return a boolean whether the security is ex-div at the given settlement.

fwd_from_repo(price, settlement, ...[, ...])

Return a forward price implied by a given repo rate.

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

Return the NPV of the security by summing cashflow valuations.

oaspread([curves, solver, fx, base, price, ...])

The option adjusted spread added to the discounting Curve to value the security at price.

repo_from_fwd(price, settlement, ...[, ...])

Return an implied repo rate from a forward price.

Methods Documentation

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

Return the analytic delta of the security via summing all periods.

For arguments see analytic_delta().

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

Return the properties of the security used in calculating cashflows.

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_rate is an FXRates or FXForwards object.

  • settlement (datetime, optional) – The settlement date of the security. If None adds the regular settle time to the initial node date of the given discount curves.

Return type:

DataFrame

ex_div(settlement)#

Return a boolean whether the security is ex-div at the given settlement.

Parameters:

settlement (datetime) – The settlement date to test.

Return type:

bool

Notes

By default uses the UK DMO convention of returning False if settlement is on or before the ex-div date.

Ex-div dates are determined as measured by the number of ex_div business days prior to the unadjusted coupon end date.

With an ex_div of 1, a settlement that occurs on the coupon payment date will be classified as ex-dividend and not receive that coupon.

With an ex_div of 0, a settlement that occurs on the coupon payment date will not be classified as ex-dividend and will receive that coupon.

Most bonds under this convention have a ex_div parameter of 1. They will still receive the coupon if they settle 1 business day before the coupon end date, and will not receive the coupon if they settle on or after the coupon end date.

fwd_from_repo(price, settlement, forward_settlement, repo_rate, convention=NoInput.blank, dirty=False, method='proceeds')#

Return a forward price implied by a given repo rate.

Parameters:

  • price (float, Dual, or Dual2) – The initial price of the security at settlement.

  • settlement (datetime) – The settlement date of the bond

  • forward_settlement (datetime) – The forward date for which to calculate the forward price.

  • repo_rate (float, Dual or Dual2) – The rate which is used to calculate values.

  • convention (str, optional) – The day count convention applied to the rate. If not given uses default values.

  • dirty (bool, optional) – Whether the input and output price are specified including accrued interest.

  • method (str in {"proceeds", "compounded"}, optional) – The method for determining the forward price.

Return type:

float, Dual or Dual2

Notes

Any intermediate (non ex-dividend) cashflows between settlement and forward_settlement will also be assumed to accrue at repo_rate.

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

Return the NPV of the security by summing cashflow valuations.

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.

  • local (bool, optional) – If True will ignore the base request and return a dict identifying local currency NPV.

Return type:

float, Dual, Dual2 or dict of such

Notes

The settlement date of the bond is inferred from the objects settle days parameter and the initial date of the supplied curves. The NPV returned is for immediate settlement.

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.

oaspread(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, price=NoInput.blank, metric=NoInput.blank, func_tol=NoInput.blank, conv_tol=NoInput.blank)#

The option adjusted spread added to the discounting Curve to value the security at price.

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.

  • price (float, Dual, Dual2) – The price of the bond to match.

  • metric (str, optional) – The metric to use when evaluating the price/rate of the instrument. If not given uses the instrument’s rate() method default.

  • func_tol (float, optional) – The tolerance for the objective function value when iteratively solving. If not given uses defaults.oaspread_func_tol.

  • conv_tol (float, optional) – The tolerance used for stopping criteria of successive iteration values. If not given uses defaults.oaspread_conv_tol.

Return type:

float, Dual, Dual2

Notes

The discount curve must be of type _BaseCurve with a provided shift() method available.

Warning

The sensitivity of variables is preserved for the input argument price, but this function does not preserve AD towards variables associated with the curves or solver.

Examples

In [5]: bond = FixedRateBond(dt(2000, 1, 1), "3Y", fixed_rate=2.5, spec="us_gb")

In [6]: curve = Curve({dt(2000, 7, 1): 1.0, dt(2005, 7, 1): 0.80})

# Add AD variables to the curve without a Solver
In [7]: curve._set_ad_order(1)

In [8]: bond.oaspread(curves=curve, price=Variable(95.0, ["price"], []))
Out[8]: <Dual: 11.809041, (price), [-42.6]>

This result excludes curve sensitivities but includes sensitivity to the constructed ‘price’ variable. Accuracy can be observed through numerical simulation.

In [9]: bond.oaspread(curves=curve, price=96.0)
Out[9]: -30.541959250658007

In [10]: bond.oaspread(curves=curve, price=94.0)
Out[10]: 54.615566044867904
repo_from_fwd(price, settlement, forward_settlement, forward_price, convention=NoInput.blank, dirty=False)#

Return an implied repo rate from a forward price.

Parameters:

  • price (float, Dual, or Dual2) – The initial price of the security at settlement.

  • settlement (datetime) – The settlement date of the bond

  • forward_settlement (datetime) – The forward date for which to calculate the forward price.

  • forward_price (float, Dual or Dual2) – The forward price which iplies the repo rate

  • convention (str, optional) – The day count convention applied to the rate. If not given uses default values.

  • dirty (bool, optional) – Whether the input and output price are specified including accrued interest.

Return type:

float, Dual or Dual2

Notes

Any intermediate (non ex-dividend) cashflows between settlement and forward_settlement will also be assumed to accrue at repo_rate.