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, notional=NoInput.blank, currency=NoInput.blank, amortization=NoInput.blank, convention=NoInput.blank, fixed_rate=NoInput.blank, ex_div=NoInput.blank, settle=NoInput.blank, calc_mode=NoInput.blank, curves=NoInput.blank, spec=NoInput.blank, metric='clean_price')#

Bases: Sensitivities, BondMixin, Metrics

Create a fixed rate bond security.

Parameters:

effective (datetime) – The adjusted or unadjusted effective date.
termination (datetime or str) – The adjusted or unadjusted termination date. If a string, then a tenor must be given expressed in days (“D”), months (“M”) or years (“Y”), e.g. “48M”.
frequency (str in {"M", "B", "Q", "T", "S", "A"}, optional) – The frequency of the schedule. “Z” is not permitted. For zero-coupon-bonds use a fixed_rate of zero and set the frequency according to the yield-to-maturity convention required.
stub (str combining {"SHORT", "LONG"} with {"FRONT", "BACK"}, optional) – The stub type to enact on the swap. Can provide two types, for example “SHORTFRONTLONGBACK”.
front_stub (datetime, optional) – An adjusted or unadjusted date for the first stub period.
back_stub (datetime, optional) – An adjusted or unadjusted date for the back stub period. See notes for combining stub, front_stub and back_stub and any automatic stub inference.
roll (int in [1, 31] or str in {"eom", "imm", "som"}, optional) – The roll day of the schedule. Inferred if not given.
eom (bool, optional) – Use an end of month preference rather than regular rolls for inference. Set by default. Not required if roll is specified.
modifier (str, optional) – The modification rule, in {“F”, “MF”, “P”, “MP”}
calendar (calendar or str, optional) – The holiday calendar object to use. If str, looks up named calendar from static data.
payment_lag (int, optional) – The number of business days to lag payments by.
notional (float, optional) – The leg notional, which is applied to each period.
currency (str, optional) – The currency of the leg (3-digit code).
amortization (float, optional) – The amount by which to adjust the notional each successive period. Should have sign equal to that of notional if the notional is to reduce towards zero.
convention (str, optional) – The day count convention applied to calculations of period accrual dates. See dcf().
fixed_rate (float, optional) – The coupon rate applied to determine cashflows. Can be set to None and designated later, perhaps after a mid-market rate for all periods has been calculated.
ex_div (int) – The number of business days prior to a cashflow which determines the last settlement date for which a coupon payment is still receivable. See BondMixin.ex_div().
settle (int) – The number of business days for regular settlement time, i.e, 1 is T+1.
calc_mode (str or BondCalcMode) – A calculation mode for dealing with bonds under different conventions. See notes.
curves (CurveType, str or list of such, optional) –
A single Curve or string id or a list of such.

A list defines the following curves in the order:
- Forecasting Curve for leg1.
- Discounting Curve for leg1.
spec (str, optional) – An identifier to pre-populate many field with conventional values. See here for more info and available values.
metric (str, optional) – The pricing metric returned by the rate method of the Instrument.

ex_div_days#

Type:: int

settle#

Type:: int

curves#

Type:: str, list, CurveType

leg1#

Type:: FixedLeg

Notes

Calculation Modes

The calc_mode parameter allows the calculation for yield-to-maturity and accrued interest to branch depending upon the particular convention of different bonds. See the documentation for the BondCalcMode class.

Calculation modes that have been preconfigured, and are available, can be found at Securities Defaults.

Examples

This example is taken from the UK debt management office (DMO) website. A copy of which is available here.

We demonstrate the use of analogue methods which do not need Curves or Solvers, price(), ytm(), ex_div(), accrued(), repo_from_fwd() fwd_from_repo() duration(), convexity().

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,
   ...:     settle=1,
   ...:     fixed_rate=8.0,
   ...:     notional=-1e6,  # negative notional receives fixed, i.e. buys a bond
   ...:     curves="gilt_curve",
   ...: )
   ...: 

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

In [4]: gilt.ytm(price=141.070132, settlement=dt(1999, 5, 27), dirty=True)
Out[4]: 4.444999968624832

In [5]: gilt.accrued(dt(1999, 5, 27))
Out[5]: -0.24175824175824176

In [6]: gilt.fwd_from_repo(
   ...:     price=141.070132,
   ...:     settlement=dt(1999, 5, 27),
   ...:     forward_settlement=dt(2000, 2, 27),
   ...:     repo_rate=4.5,
   ...:     convention="Act365F",
   ...:     dirty=True,
   ...: )
   ...: 
Out[6]: 141.82994306695892

In [7]: gilt.repo_from_fwd(
   ...:     price=141.070132,
   ...:     settlement=dt(1999, 5, 27),
   ...:     forward_settlement=dt(2000, 2, 27),
   ...:     forward_price=141.829943,
   ...:     convention="Act365F",
   ...:     dirty=True,
   ...: )
   ...: 
Out[7]: 4.499999936695988

In [8]: gilt.duration(settlement=dt(1999, 5, 27), ytm=4.445, metric="risk")
Out[8]: np.float64(14.659753980778154)

In [9]: gilt.duration(settlement=dt(1999, 5, 27), ytm=4.445, metric="modified")
Out[9]: np.float64(10.39181988471933)

In [10]: gilt.convexity(settlement=dt(1999, 5, 27), ytm=4.445)
Out[10]: np.float64(2.0367301586109305)

The following digital methods consistent with the library’s ecosystem are also available, analytic_delta(), rate(), npv(), cashflows(), delta(), gamma().

In [11]: gilt_curve = Curve({dt(1999, 5, 26): 1.0, dt(2019, 5, 26): 1.0}, id="gilt_curve")

In [12]: instruments = [
   ....:     (gilt, (), {"metric": "ytm"}),
   ....: ]
   ....: 

In [13]: solver = Solver(
   ....:     curves=[gilt_curve],
   ....:     instruments=instruments,
   ....:     s=[4.445],
   ....:     instrument_labels=["8% Dec15"],
   ....:     id="gilt_solver",
   ....: )
   ....: 
SUCCESS: `func_tol` reached after 6 iterations (levenberg_marquardt), `f_val`: 2.660504903222461e-17, `time`: 0.0273s

In [14]: gilt.npv(solver=solver)
Out[14]: <Dual: 1410531.560143, (gilt_curve0, gilt_curve1), [660978.5, 1805464.9]>

In [15]: gilt.analytic_delta(disc_curve=gilt_curve)
Out[15]: <Dual: -1158.813446, (gilt_curve0, gilt_curve1), [-721.5, -1053.4]>

In [16]: gilt.rate(solver=solver, metric="clean_price")
Out[16]: <Dual: 141.311890, (gilt_curve0, gilt_curve1), [-74.9, 180.5]>

The sensitivities are also available. In this case the Solver is calibrated with instruments priced in yield terms so sensitivities are measured in basis points (bps).

In [17]: gilt.delta(solver=solver)
Out[17]: 
local_ccy                                 gbp
display_ccy                               gbp
type        solver      label                
instruments gilt_solver 8% Dec15 -1466.176691

In [18]: gilt.gamma(solver=solver)
Out[18]: 
type                                                   instruments
solver                                                 gilt_solver
label                                                     8% Dec15
local_ccy display_ccy type        solver      label               
gbp       gbp         instruments gilt_solver 8% Dec15    2.037289

The DataFrame of cashflows.

In [19]: gilt.cashflows(solver=solver)
Out[19]: 
           Type    Period  Ccy  Acc Start    Acc End    Payment  Convention  DCF   Notional        DF Collateral  Rate  Spread   Cashflow            NPV  FX Rate        NPV Ccy
 FixedPeriod   Regular  GBP 1998-12-07 1999-06-07 1999-06-07  ActActICMA  0.5 -1000000.0  0.998557       None   8.0     NaN    40000.0       0.000000      1.0       0.000000
 FixedPeriod   Regular  GBP 1999-06-07 1999-12-07 1999-12-07  ActActICMA  0.5 -1000000.0  0.976807       None   8.0     NaN    40000.0   39072.262568      1.0   39072.262568
 FixedPeriod   Regular  GBP 1999-12-07 2000-06-07 2000-06-07  ActActICMA  0.5 -1000000.0  0.955530       None   8.0     NaN    40000.0   38221.197977      1.0   38221.197977
 FixedPeriod   Regular  GBP 2000-06-07 2000-12-07 2000-12-07  ActActICMA  0.5 -1000000.0  0.934717       None   8.0     NaN    40000.0   37388.671114      1.0   37388.671114
 FixedPeriod   Regular  GBP 2000-12-07 2001-06-07 2001-06-07  ActActICMA  0.5 -1000000.0  0.914467       None   8.0     NaN    40000.0   36578.679869      1.0   36578.679869
 FixedPeriod   Regular  GBP 2001-06-07 2001-12-07 2001-12-07  ActActICMA  0.5 -1000000.0  0.894548       None   8.0     NaN    40000.0   35781.930023      1.0   35781.930023
 FixedPeriod   Regular  GBP 2001-12-07 2002-06-07 2002-06-07  ActActICMA  0.5 -1000000.0  0.875169       None   8.0     NaN    40000.0   35006.747349      1.0   35006.747349
 FixedPeriod   Regular  GBP 2002-06-07 2002-12-09 2002-12-09  ActActICMA  0.5 -1000000.0  0.855900       None   8.0     NaN    40000.0   34235.996008      1.0   34235.996008
 FixedPeriod   Regular  GBP 2002-12-09 2003-06-09 2003-06-09  ActActICMA  0.5 -1000000.0  0.837358       None   8.0     NaN    40000.0   33494.304576      1.0   33494.304576
 FixedPeriod   Regular  GBP 2003-06-09 2003-12-08 2003-12-08  ActActICMA  0.5 -1000000.0  0.819217       None   8.0     NaN    40000.0   32768.681208      1.0   32768.681208
FixedPeriod   Regular  GBP 2003-12-08 2004-06-07 2004-06-07  ActActICMA  0.5 -1000000.0  0.801469       None   8.0     NaN    40000.0   32058.777804      1.0   32058.777804
FixedPeriod   Regular  GBP 2004-06-07 2004-12-07 2004-12-07  ActActICMA  0.5 -1000000.0  0.784012       None   8.0     NaN    40000.0   31360.479605      1.0   31360.479605
FixedPeriod   Regular  GBP 2004-12-07 2005-06-07 2005-06-07  ActActICMA  0.5 -1000000.0  0.767027       None   8.0     NaN    40000.0   30681.083596      1.0   30681.083596
FixedPeriod   Regular  GBP 2005-06-07 2005-12-07 2005-12-07  ActActICMA  0.5 -1000000.0  0.750320       None   8.0     NaN    40000.0   30012.794070      1.0   30012.794070
FixedPeriod   Regular  GBP 2005-12-07 2006-06-07 2006-06-07  ActActICMA  0.5 -1000000.0  0.734065       None   8.0     NaN    40000.0   29362.594432      1.0   29362.594432
FixedPeriod   Regular  GBP 2006-06-07 2006-12-07 2006-12-07  ActActICMA  0.5 -1000000.0  0.718076       None   8.0     NaN    40000.0   28723.023986      1.0   28723.023986
FixedPeriod   Regular  GBP 2006-12-07 2007-06-07 2007-06-07  ActActICMA  0.5 -1000000.0  0.702519       None   8.0     NaN    40000.0   28100.766033      1.0   28100.766033
FixedPeriod   Regular  GBP 2007-06-07 2007-12-07 2007-12-07  ActActICMA  0.5 -1000000.0  0.687217       None   8.0     NaN    40000.0   27488.680493      1.0   27488.680493
FixedPeriod   Regular  GBP 2007-12-07 2008-06-09 2008-06-09  ActActICMA  0.5 -1000000.0  0.672086       None   8.0     NaN    40000.0   26883.456102      1.0   26883.456102
FixedPeriod   Regular  GBP 2008-06-09 2008-12-08 2008-12-08  ActActICMA  0.5 -1000000.0  0.657526       None   8.0     NaN    40000.0   26301.050699      1.0   26301.050699
FixedPeriod   Regular  GBP 2008-12-08 2009-06-08 2009-06-08  ActActICMA  0.5 -1000000.0  0.643282       None   8.0     NaN    40000.0   25731.262574      1.0   25731.262574
FixedPeriod   Regular  GBP 2009-06-08 2009-12-07 2009-12-07  ActActICMA  0.5 -1000000.0  0.629345       None   8.0     NaN    40000.0   25173.818386      1.0   25173.818386
FixedPeriod   Regular  GBP 2009-12-07 2010-06-07 2010-06-07  ActActICMA  0.5 -1000000.0  0.615711       None   8.0     NaN    40000.0   24628.450715      1.0   24628.450715
FixedPeriod   Regular  GBP 2010-06-07 2010-12-07 2010-12-07  ActActICMA  0.5 -1000000.0  0.602300       None   8.0     NaN    40000.0   24091.998487      1.0   24091.998487
FixedPeriod   Regular  GBP 2010-12-07 2011-06-07 2011-06-07  ActActICMA  0.5 -1000000.0  0.589252       None   8.0     NaN    40000.0   23570.067451      1.0   23570.067451
FixedPeriod   Regular  GBP 2011-06-07 2011-12-07 2011-12-07  ActActICMA  0.5 -1000000.0  0.576417       None   8.0     NaN    40000.0   23056.668725      1.0   23056.668725
FixedPeriod   Regular  GBP 2011-12-07 2012-06-07 2012-06-07  ActActICMA  0.5 -1000000.0  0.563861       None   8.0     NaN    40000.0   22554.452753      1.0   22554.452753
FixedPeriod   Regular  GBP 2012-06-07 2012-12-07 2012-12-07  ActActICMA  0.5 -1000000.0  0.551579       None   8.0     NaN    40000.0   22063.175954      1.0   22063.175954
FixedPeriod   Regular  GBP 2012-12-07 2013-06-07 2013-06-07  ActActICMA  0.5 -1000000.0  0.539630       None   8.0     NaN    40000.0   21585.197496      1.0   21585.197496
FixedPeriod   Regular  GBP 2013-06-07 2013-12-09 2013-12-09  ActActICMA  0.5 -1000000.0  0.527749       None   8.0     NaN    40000.0   21109.951403      1.0   21109.951403
FixedPeriod   Regular  GBP 2013-12-09 2014-06-09 2014-06-09  ActActICMA  0.5 -1000000.0  0.516316       None   8.0     NaN    40000.0   20652.623681      1.0   20652.623681
FixedPeriod   Regular  GBP 2014-06-09 2014-12-08 2014-12-08  ActActICMA  0.5 -1000000.0  0.505130       None   8.0     NaN    40000.0   20205.203543      1.0   20205.203543
FixedPeriod   Regular  GBP 2014-12-08 2015-06-08 2015-06-08  ActActICMA  0.5 -1000000.0  0.494187       None   8.0     NaN    40000.0   19767.476353      1.0   19767.476353
FixedPeriod   Regular  GBP 2015-06-08 2015-12-07 2015-12-07  ActActICMA  0.5 -1000000.0  0.483481       None   8.0     NaN    40000.0   19339.232120      1.0   19339.232120
   Cashflow  Exchange  GBP        NaT        NaT 2015-12-07         NaN  NaN -1000000.0  0.483481       None   NaN     NaN  1000000.0  483480.802990      1.0  483480.802990

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

`accrued`(settlement)	Calculate the accrued amount per nominal par value of 100.
`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.
`cashflows_table`([curves, solver, fx, base])	Aggregate the values derived from a `cashflows()` method on an Instrument.
`convexity`(ytm, settlement)	Return the second derivative of `price` w.r.t.
`delta`(args, *kwargs)	Calculate the delta of the Instrument.
`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`(vars[, curves, solver, fx, base, ...])	Calculate delta risk of an Instrument against some exogenous user created Variables.
`fwd_from_repo`(price, settlement, ...[, ...])	Return a forward price implied by a given repo rate.
`gamma`(args, *kwargs)	Calculate the gamma of the Instrument.
`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`.
`price`(ytm, settlement[, dirty])	Calculate the price of the security per nominal value of 100, given yield-to-maturity.
`rate`([curves, solver, fx, base, metric, ...])	Return various pricing metrics of the security calculated from `Curve` s.
`repo_from_fwd`(price, settlement, ...[, ...])	Return an implied repo rate from a forward price.
`ytm`(price, settlement[, dirty])	Calculate the yield-to-maturity of the security given its price.

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

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

Fractionally apportions the coupon payment based on calendar days.

\[\text{Accrued} = \text{Coupon} \times \frac{\text{Settle - Last Coupon}}{\text{Next Coupon - Last Coupon}}\]

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

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

convexity(ytm, settlement)#

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.

Return type:

float

Examples

In [20]: 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 [21]: gilt.convexity(4.445, dt(1999, 5, 27))
Out[21]: 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 [22]: gilt.duration(4.445, dt(1999, 5, 27))
Out[22]: np.float64(14.659753980778154)

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

delta(*args, **kwargs)#

Calculate the delta of the Instrument.

For arguments see Sensitivities.delta().

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

\[mduration = \frac{risk}{P} = - \frac{1}{P} \frac{\partial P }{\partial y}\]
“duration”: the duration which is modified duration reverse modified.

\[duration = mduration \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

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.

exo_delta(vars, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, local=False, vars_scalar=NoInput.blank, vars_labels=NoInput.blank, **kwargs)#

Calculate delta risk of an Instrument against some exogenous user created Variables.

See What are exogenous variables? in the cookbook.

Parameters:

vars (list[str]) – The variable tags which to determine sensitivities for.
curves (Curve, str or list of such, optional) –
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.
- Forecasting Curve for leg2.
- Discounting Curve for leg2.
solver (Solver, optional) – The Solver that calibrates Curves from given 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.
local (bool, optional) – If True will ignore base - this is equivalent to setting base to None. Included only for argument signature consistent with npv.
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(*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 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 [7]: bond = FixedRateBond(dt(2000, 1, 1), "3Y", fixed_rate=2.5, spec="us_gb")

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

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

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

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

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, base=NoInput.blank, metric=NoInput.blank, forward_settlement=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) – Not used by FixedRateBond rate. Output is in local currency.
base (str, optional) – Not used by FixedRateBond rate. Output is in local currency.
metric (str, optional) – Metric returned by the method. Available options are {“clean_price”, “dirty_price”, “ytm”}. Uses the Instrument default if not given.
forward_settlement (datetime, optional) – The forward settlement date. If not given the settlement date is inferred from the discount Curve and the settle attribute.

Return type:

float, Dual, Dual2

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.

ytm(price, settlement, dirty=False)#

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

Parameters:

price (float, Dual, Dual2) – The price, per 100 nominal, against which to determine the yield.
settlement (datetime) – The settlement date on which to determine the price.
dirty (bool, optional) – If True will assume the accrued() is included in the price.

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.

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.ytm(
   ...:     price=141.0701315,
   ...:     settlement=dt(1999,5,27),
   ...:     dirty=True
   ...: )
   ...: 
Out[2]: 4.445000002731812

In [3]: gilt.ytm(Dual(141.0701315, ["price", "a", "b"], [1, -0.5, 2]), dt(1999, 5, 27), True)
Out[3]: <Dual: 4.445000, (price, a, b), [-0.1, 0.0, -0.1]>

In [4]: gilt.ytm(Dual2(141.0701315, ["price", "a", "b"], [1, -0.5, 2], []), dt(1999, 5, 27), True)
Out[4]: <Dual2: 4.445000, (price, a, b), [-0.1, 0.0, -0.1], [[...]]>

FixedRateBond#

This Page