FixedRateBond#

class rateslib.instruments.FixedRateBond(effective=NoInput.blank, termination=NoInput.blank, frequency=NoInput.blank, *, stub=NoInput.blank, front_stub=NoInput.blank, back_stub=NoInput.blank, roll=NoInput.blank, eom=NoInput.blank, modifier=NoInput.blank, calendar=NoInput.blank, payment_lag=NoInput.blank, payment_lag_exchange=NoInput.blank, ex_div=NoInput.blank, convention=NoInput.blank, currency=NoInput.blank, notional=NoInput.blank, fixed_rate=NoInput.blank, curves=NoInput.blank, calc_mode=NoInput.blank, settle=NoInput.blank, spec=NoInput.blank, metric='clean_price')#

Bases: _BaseBondInstrument

A fixed rate bond composed of a FixedLeg.

Examples

In [1]: frb = FixedRateBond(
   ...:     effective=dt(2000, 1, 1),
   ...:     termination="2y",
   ...:     spec="us_gb",
   ...:     fixed_rate=2.0,
   ...: )
   ...: 

In [2]: frb.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 2000-07-03  1000000.0  Regular  ActActICMA  0.5 2000-01-01 2000-07-01  None   -10000.0  None      1.0      USD    None       None   2.0     NaN
     1  FixedPeriod  USD 2001-01-02  1000000.0  Regular  ActActICMA  0.5 2000-07-01 2001-01-01  None   -10000.0  None      1.0      USD    None       None   2.0     NaN
     2  FixedPeriod  USD 2001-07-02  1000000.0  Regular  ActActICMA  0.5 2001-01-01 2001-07-01  None   -10000.0  None      1.0      USD    None       None   2.0     NaN
     3  FixedPeriod  USD 2002-01-02  1000000.0  Regular  ActActICMA  0.5 2001-07-01 2002-01-01  None   -10000.0  None      1.0      USD    None       None   2.0     NaN
     4     Cashflow  USD 2002-01-02  1000000.0      NaN         NaN  NaN        NaT        NaT  None -1000000.0  None      1.0      USD    None       None   NaN     NaN

Pricing

A 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:

. –

Note

The following define generalised scheduling parameters.
effective (datetime, required) – The unadjusted effective date. If given as adjusted, unadjusted alternatives may be inferred.
termination (datetime, str, required) – The unadjusted termination date. If given as adjusted, unadjusted alternatives may be inferred. If given as string tenor will be calculated from effective.
frequency (Frequency, str, required) – The frequency of the schedule. If given as string will derive a Frequency aligning with: monthly (“M”), quarterly (“Q”), semi-annually (“S”), annually(“A”) or zero-coupon (“Z”), or a set number of calendar or business days (“_D”, “_B”), weeks (“_W”), months (“_M”) or years (“_Y”). Where required, the RollDay is derived as per roll and business day calendar as per calendar.
stub (StubInference, str in {“ShortFront”, “LongFront”, “ShortBack”, “LongBack”}, optional) – The stub type used if stub inference is required. If given as string will derive a StubInference.
front_stub (datetime, optional) – The unadjusted date for the start stub period. If given as adjusted, unadjusted alternatives may be inferred.
back_stub (datetime, optional) – The unadjusted date for the back stub period. If given as adjusted, unadjusted alternatives may be inferred. See notes for combining stub, front_stub and back_stub and any automatic stub inference.
roll (RollDay, int in [1, 31], str in {“eom”, “imm”, “som”}, optional) – The roll day of the schedule. If not given or not available in frequency will be inferred for monthly frequency variants.
eom (bool, optional) – Use an end of month preference rather than regular rolls for roll inference. Set by default. Not required if roll is defined.
modifier (Adjuster, str in {“NONE”, “F”, “MF”, “P”, “MP”}, optional) – The Adjuster used for adjusting unadjusted schedule dates into adjusted dates. If given as string must define simple date rolling rules.
calendar (calendar, str, optional) – The business day calendar object to use. If string will call get_calendar().
payment_lag (Adjuster, int, optional) – The Adjuster to use to map adjusted schedule dates into a payment date. If given as integer will define the number of business days to lag payments by.
payment_lag_exchange (Adjuster, int, optional) – The Adjuster to use to map adjusted schedule dates into additional payment date. If given as integer will define the number of business days to lag payments by.
ex_div (Adjuster, int, optional) – The Adjuster to use to map adjusted schedule dates into additional dates, which may be used, for example by fixings schedules. If given as integer will define the number of business days to lag dates by.
convention (str, optional (set by ‘defaults’)) –
The day count convention applied to calculations of period accrual dates. See dcf().

Note

The following define generalised settlement parameters.
currency (str, optional (set by ‘defaults’)) – The local settlement currency of the Instrument (3-digit code).
notional (float, Dual, Dual2, Variable, optional (set by ‘defaults’)) –
The initial leg notional, defined in units of reference currency.

Note

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

Note

The following are meta parameters.
curves (_BaseCurve, str, dict, _Curves, Sequence, optional) – Pricing objects passed directly to the Instrument’s methods’ curves argument. See Pricing.
calc_mode (str or BondCalcMode) – A calculation mode for dealing with bonds under different conventions. See notes.
settle (int) – The number of days by which to lag ‘today’ to arrive at standard settlement.
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.

Attributes Summary

`fixed_rate`	The fixed rate parameter of the composited `FixedLeg`.
`kwargs`	The `_KWArgs` container for the Instrument.
`leg1`	The `FixedLeg` of the Instrument.
`legs`	A list of the Legs of the Instrument.
`rate_scalar`	A scaling quantity associated with the `Solver` risk calculations.
`settlement_params`	The default `_SettlementParams` of the Instrument.

Methods Summary

`accrued`(settlement)	Calculate the accrued amount per nominal par value of 100.
`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.
`convexity`(ytm, settlement[, metric])	Return the second derivative of `price` w.r.t.
`delta`(*[, curves, solver, fx, vol, base, ...])	Calculate delta risk of an Instrument against the calibrating instruments in a `Solver`.
`duration`(ytm, settlement[, metric])	Return the (negated) derivative of `price` w.r.t.
`ex_div`(settlement)	Return a boolean whether the security is ex-div at the given settlement.
`exo_delta`(*[, curves, solver, fx, vol, ...])	Calculate delta risk of an Instrument against some exogenous user created Variables, via a `Solver`.
`fwd_from_repo`(price, settlement, ...[, ...])	Return a forward price implied by a given repo rate.
`gamma`(*[, curves, solver, fx, vol, base, ...])	Calculate cross-gamma risk of an Instrument against the calibrating instruments of a `Solver`.
`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.
`npv`(*[, curves, solver, fx, vol, base, ...])	Calculate the NPV of the Instrument converted to any other base accounting currency.
`oaspread`(*[, curves, solver, fx, vol, base, ...])	The option adjusted spread added to the discounting Curve to value the security at `price`.
`price`(ytm, settlement[, dirty])	Calculate the price of the security per nominal value of 100, given yield-to-maturity.
`rate`(*[, curves, solver, fx, vol, base, ...])	Calculate some pricing rate metric for the Instrument.
`repo_from_fwd`(price, settlement, ...[, ...])	Return an implied repo rate from a forward price.
`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`(price, settlement[, dirty, rate_curve, ...])	Calculate the yield-to-maturity of the security given its price.

Attributes Documentation

fixed_rate#: The fixed rate parameter of the composited FixedLeg.

kwargs#: The _KWArgs container for the Instrument.

leg1#: The FixedLeg of the Instrument.

legs#: A list of the Legs of the Instrument.

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

accrued(settlement)#

Calculate the accrued amount per nominal par value of 100.

Parameters:: settlement (datetime) – The settlement date which to measure accrued interest against.

Notes

The amount of accrued interest is calculated using the following formula:

\[\begin{split}&AI = \xi c_i \qquad \text{if not ex-dividend} \\ &AI = (\xi - 1) c_i \qquad \text{if ex-dividend} \\\end{split}\]

where \(c_i\) is the physical cashflow related to the period in which settlement falls, and \(\xi\) is a fraction of that amount determined according to the calculation mode specific to the BondCalcMode.

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 [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", fixed_rate=1.0, curves=[curve])

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

In [6]: irs.analytic_delta(local=True)
Out[6]: {'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 [7]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=1.0)

In [8]: irs.cashflows()
Out[8]: 
               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 [9]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75})

In [10]: irs.cashflows(curves=[curve])
Out[10]: 
               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 [11]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=1.0)

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

In [13]: irs.cashflows_table(curves=[curve])
Out[13]: 
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

convexity(ytm, settlement, metric='risk')#

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

Parameters:

ytm (float) – The yield-to-maturity for the bond.
settlement (datetime) – The settlement date of the bond.
metric (str, optional)

Return type:

float

Notes

The default metric is similar to the duration() method and is ‘risk’ based, but the traditional calculation is available.

“risk”: the second derivative of price w.r.t. ytm, scaled to -1bp.

\[risk = \frac{\partial^2 P }{\partial y^2}\]
“convexity”: the standard formula for convexity which is the above scaled by price.

\[convexity = \frac{1}{P} \frac{\partial P^2 }{\partial y^2}\]

Examples

In [14]: gilt = FixedRateBond(
   ....:     effective=dt(1998, 12, 7),
   ....:     termination=dt(2015, 12, 7),
   ....:     frequency="S",
   ....:     calendar="ldn",
   ....:     currency="gbp",
   ....:     convention="ActActICMA",
   ....:     ex_div=7,
   ....:     fixed_rate=8.0
   ....: )
   ....: 

In [15]: gilt.convexity(4.445, dt(1999, 5, 27))
Out[15]: np.float64(2.0367301586109305)

This number is interpreted as hundredths of a cent. For a 1bp increase in yield the duration will decrease by 2 hundredths of a cent.

In [16]: gilt.duration(4.445, dt(1999, 5, 27))
Out[16]: np.float64(14.659753980778154)

In [17]: gilt.duration(4.455, dt(1999, 5, 27))
Out[17]: np.float64(14.63940251353963)

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

Calculate delta risk of an Instrument against the calibrating instruments in a Solver.

Examples

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

In [19]: 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.0030s

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

In [21]: irs.delta(solver=solver)
Out[21]: 
local_ccy                          usd
display_ccy                        usd
type        solver   label            
instruments US_RATES 2Y     129.580448
                     5Y     162.173287

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

Delta measures the 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.

duration(ytm, settlement, metric='risk')#

Return the (negated) derivative of price w.r.t. ytm.

Parameters:

ytm (float) – The yield-to-maturity for the bond.
settlement (datetime) – The settlement date of the bond.
metric (str) – The specific duration calculation to return. See notes.

Return type:

float

Notes

The available metrics are:

“risk”: the derivative of price w.r.t. ytm, scaled to -1bp.

\[risk = - \frac{\partial P }{\partial y}\]
“modified”: the modified duration which is risk divided by dirty price.

\[mod \; duration = \frac{risk}{P} = - \frac{1}{P} \frac{\partial P }{\partial y}\]
“duration” (or “macaulay”): the duration which is modified duration reverse modified.

\[duration = mod \; duration \times (1 + y / f)\]

Examples

In [1]: gilt = FixedRateBond(
   ...:     effective=dt(1998, 12, 7),
   ...:     termination=dt(2015, 12, 7),
   ...:     frequency="S",
   ...:     calendar="ldn",
   ...:     currency="gbp",
   ...:     convention="ActActICMA",
   ...:     ex_div=7,
   ...:     fixed_rate=8.0
   ...: )
   ...: 

In [2]: gilt.duration(4.445, dt(1999, 5, 27), "risk")
Out[2]: np.float64(14.659753980778154)

In [3]: gilt.duration(4.445, dt(1999, 5, 27), "modified")
Out[3]: np.float64(10.39181988471933)

In [4]: gilt.duration(4.445, dt(1999, 5, 27), "duration")
Out[4]: np.float64(10.622778081657216)

This result is interpreted as cents. If the yield is increased by 1bp the price will fall by 14.65 cents.

In [5]: gilt.price(4.445, dt(1999, 5, 27))
Out[5]: 141.31188978180364

In [6]: gilt.price(4.455, dt(1999, 5, 27))
Out[6]: 141.16539402571507

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

Uses the UK DMO convention of returning False if settlement is on or before the ex-div date for a regular coupon period.

This is evaluated by analysing the attribute pschedule3 of the associated Schedule object of the Leg.

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.0030s

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, 26e680, 26e681, ...), [0.0, 49.2, 239.9, ...]>

In [12]: irs.npv()
Out[12]: <Dual: -25123.690181, (N, R, 26e680, ...), [-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

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.

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.0031s

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.

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 [17]: curve1 = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75}, id="Eur1mCurve")

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

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

In [20]: irs.local_analytic_rate_fixings()
Out[20]: 
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

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

Calculate the NPV of the Instrument converted to any other base accounting currency.

Examples

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

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

In [23]: irs.npv()
Out[23]: 53875.24237805192

In [24]: irs.npv(local=True)
Out[24]: {'usd': 53875.24237805192}

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 or dict of such indexed by string currency.

Notes

If base is not given then this function will return the value obtained from determining the PV in local settlement currency.

If base is provided this then an FXForwards object may be required to perform conversions. An FXRates object is also allowed for this conversion although best practice does not recommend it due to possible settlement date conflicts.

oaspread(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=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 [25]: bond = FixedRateBond(dt(2000, 1, 1), "3Y", fixed_rate=2.5, spec="us_gb")

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

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

In [28]: bond.oaspread(curves=curve, price=Variable(95.0, ["price"], []))
Out[28]: <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 [29]: bond.oaspread(curves=curve, price=96.0)
Out[29]: -30.541959250658028

In [30]: bond.oaspread(curves=curve, price=94.0)
Out[30]: 54.61556604486857

price(ytm, settlement, dirty=False)#

Calculate the price of the security per nominal value of 100, given yield-to-maturity.

Parameters:

ytm (float) – The yield-to-maturity against which to determine the price.
settlement (datetime) – The settlement date on which to determine the price.
dirty (bool, optional) – If True will include the rateslib.instruments.FixedRateBond.accrued() in the price.

Return type:

float, Dual, Dual2

Examples

This example is taken from the UK debt management office website. The result should be 141.070132 and the bond is ex-div.

In [1]: gilt = FixedRateBond(
   ...:     effective=dt(1998, 12, 7),
   ...:     termination=dt(2015, 12, 7),
   ...:     frequency="S",
   ...:     calendar="ldn",
   ...:     currency="gbp",
   ...:     convention="ActActICMA",
   ...:     ex_div=7,
   ...:     fixed_rate=8.0
   ...: )
   ...: 

In [2]: gilt.ex_div(dt(1999, 5, 27))
Out[2]: True

In [3]: gilt.price(
   ...:     ytm=4.445,
   ...:     settlement=dt(1999, 5, 27),
   ...:     dirty=True
   ...: )
   ...: 
Out[3]: 141.0701315400454

This example is taken from the Swedish national debt office website. The result of accrued should, apparently, be 0.210417 and the clean price should be 99.334778.

In [4]: bond = FixedRateBond(
   ...:     effective=dt(2017, 5, 12),
   ...:     termination=dt(2028, 5, 12),
   ...:     frequency="A",
   ...:     calendar="stk",
   ...:     currency="sek",
   ...:     convention="ActActICMA",
   ...:     ex_div=5,
   ...:     fixed_rate=0.75
   ...: )
   ...: 

In [5]: bond.ex_div(dt(2017, 8, 23))
Out[5]: False

In [6]: bond.accrued(dt(2017, 8, 23))
Out[6]: 0.21049046321525883

In [7]: bond.price(
   ...:     ytm=0.815,
   ...:     settlement=dt(2017, 8, 23),
   ...:     dirty=False
   ...: )
   ...: 
Out[7]: 99.334784546763

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)#

Calculate some pricing rate metric for the Instrument.

Examples

The default metric for an IRS is its fixed ‘rate’.

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", curves=[curve], fixed_rate=2.0)

In [3]: irs.rate()       # <- `fixed_rate` on fixed leg to equate value with float leg
Out[3]: 2.87622187684324

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.
metric (str, optional) – The specific calculation to perform and the value to return. See Pricing on each Instrument for details of allowed inputs.

Return type:

float, Dual, Dual2, Variable

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.

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 [4]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75})

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

In [6]: irs.spread()       # <- `spread` on float leg to equate value with fixed leg
Out[6]: -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(price, settlement, dirty=False, rate_curve=NoInput.blank, calc_mode=NoInput.blank)#

Calculate the yield-to-maturity of the security given its price.

Examples

In [1]: aapl_bond = FixedRateBond(dt(2013, 5, 4), dt(2043, 5, 4), fixed_rate=3.85, spec="us_corp")

In [2]: aapl_bond.ytm(price=87.24, settlement=dt(2014, 3, 5))
Out[2]: 4.653674794785435

In [3]: aapl_bond.ytm(price=87.24, settlement=dt(2014, 3, 5), calc_mode="us_gb_tsy")
Out[3]: 4.653285308320108

Parameters:

price (float, Dual, Dual2, Variable, required) – The price, per 100 nominal, against which to determine the yield.
settlement (datetime, required) – The settlement date on which to determine the price.
dirty (bool, optional (set as False)) – If True will assume the accrued() is included in the price.
rate_curve (_BaseCurve or dict of such, optional) – Used to forecast floating rates if required.
calc_mode (str or BondCalcMode, optional) – An alternative calculation mode to use. The calc_mode is typically set at Instrument initialisation and is not required, but is useful as an override to allow comparisons, e.g. of “us_gb” street convention versus “us_gb_tsy” treasury convention.

Return type:

float, Dual, Dual2

Notes

If price is given as Dual or Dual2 input the result of the yield will be output as the same type with the variables passed through accordingly.

In [4]: aapl_bond.ytm(price=Dual(87.24, ["price", "a"], [1, -0.75]), settlement=dt(2014, 3, 5))
Out[4]: <Dual: 4.653675, (price, a), [-0.1, 0.1]>

In [5]: aapl_bond.ytm(price=Dual2(87.24, ["price", "a"], [1, -0.75], []), settlement=dt(2014, 3, 5))
Out[5]: <Dual2: 4.653675, (price, a), [-0.1, 0.1], [[...]]>

FixedRateBond#

This Page