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)#
Bases:
Sensitivities
,BondMixin
,BaseMixin
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
andback_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 days prior to a cashflow during which the bond is considered ex-dividend.
settle (int) – The number of business days for regular settlement time, i.e, 1 is T+1.
calc_mode (str) – 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
forleg1
.
spec (str, optional) – An identifier to pre-populate many field with conventional values. See here for more info and available values.
- ex_div_days#
- Type:
int
- settle#
- Type:
int
- curves#
- Type:
str, list, CurveType
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.The following modes are currently available with a brief description of its particular action:
“ukg”: UK Gilt convention. Accrued is linearly proportioned, as are stub periods. Stub yields are compounded.
“ust”: US Treasury street convention. Same as “ukg” except long stub periods have linear proportioning only in the segregated short stub part.
“ust_31bii”: US Treasury convention that reprices examples in federal documents: Section 31-B-ii). Otherwise referred to as the ‘Treasury’ method.
“sgb”: Swedish government bond convention. Accrued ignores the convention and calculates using 30e360, also for back stubs.
“cadgb” Canadian government bond convention. Accrued is calculated using an ACT365F convention. Yield calculations are still derived with linearly proportioned compounded coupons.
More details available in supplementary materials. The table below outlines the rateslib price result relative to the calculation examples provided from official sources.
In [1]: from pandas import option_context In [2]: with option_context("display.float_format", lambda x: '%.6f' % x): ...: print(data) ...: Source Example Expected clean Expected dirty Calc mode Rateslib clean Rateslib dirty 0 Riksgalden Website Nominal Bond 116.514000 119.868393 sgb 116.514226 119.868393 1 UK DMO Website Ex 1, Scen 1 NaN 145.012268 ukg 141.319961 145.012268 2 UK DMO Website Ex 1, Scen 2 NaN 145.047301 ukg 141.311037 145.047301 3 UK DMO Website Ex 1, Scen 3 NaN 141.070132 ukg 141.311890 141.070132 4 UK DMO Website Ex 1, Scen 4 NaN 141.257676 ukg 141.257676 141.257676 5 UK DMO Website Ex 2, Scen 1 NaN 113.315543 ukg 110.238886 113.315543 6 UK DMO Website Ex 2, Scen 2 NaN 113.415969 ukg 110.208786 113.415969 7 UK DMO Website Ex 2, Scen 3 NaN 110.058738 ukg 110.207909 110.058738 8 UK DMO Website Ex 2, Scen 4 NaN 110.170218 ukg 110.170218 110.170218 9 Title-31 Subtitle-B II Ex A (reg) 99.057893 99.057893 ust_31bii 99.057893 99.057893 10 Title-31 Subtitle-B II Ex B (stub) 99.838183 99.838183 ust_31bii 99.838183 99.838183 11 Title-31 Subtitle-B II Ex C (stub) 99.805118 99.805118 ust_31bii 99.805118 99.805118 12 Title-31 Subtitle-B II Ex D (reg) 99.730918 100.098321 ust_31bii 99.730918 100.098321 13 Title-31 Subtitle-B II Ex E (stub) 102.214586 105.887384 ust_31bii 102.214586 105.887384 14 Title-31 Subtitle-B II Ex F (stub) 99.777074 102.373541 ust_31bii 99.777073 102.373541 15 Title-31 Subtitle-B II Ex G (stub) 99.738045 100.563865 ust_31bii 99.738045 100.563865
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 [3]: 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 [4]: gilt.ex_div(dt(1999, 5, 27)) Out[4]: True In [5]: gilt.price(ytm=4.445, settlement=dt(1999, 5, 27), dirty=True) Out[5]: 141.07013154004537 In [6]: gilt.ytm(price=141.070132, settlement=dt(1999, 5, 27), dirty=True) Out[6]: 4.444999968624668 In [7]: gilt.accrued(dt(1999, 5, 27)) Out[7]: -0.24175824175824176 In [8]: 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[8]: 141.82994306695892 In [9]: 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[9]: 4.499999936695988 In [10]: gilt.duration(settlement=dt(1999, 5, 27), ytm=4.445, metric="risk") Out[10]: 14.65975398077815 In [11]: gilt.duration(settlement=dt(1999, 5, 27), ytm=4.445, metric="modified") Out[11]: 10.39181988471933 In [12]: gilt.convexity(settlement=dt(1999, 5, 27), ytm=4.445) Out[12]: 2.03673015861093
The following digital methods consistent with the library’s ecosystem are also available,
analytic_delta()
,rate()
,npv()
,cashflows()
,delta()
,gamma()
.In [13]: gilt_curve = Curve({dt(1999, 5, 26): 1.0, dt(2019, 5, 26): 1.0}, id="gilt_curve") In [14]: instruments = [ ....: (gilt, (), {"metric": "ytm"}), ....: ] ....: In [15]: 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.6605195631838073e-17, `time`: 0.0475s In [16]: gilt.npv(solver=solver) Out[16]: <Dual: 1410531.560143, (gilt_curve0, gilt_curve1), [660978.5, 1805464.9]> In [17]: gilt.analytic_delta(disc_curve=gilt_curve) Out[17]: <Dual: -1158.813446, (gilt_curve0, gilt_curve1), [-721.5, -1053.4]> In [18]: gilt.rate(solver=solver, metric="clean_price") Out[18]: <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 [19]: gilt.delta(solver=solver) Out[19]: local_ccy gbp display_ccy gbp type solver label instruments gilt_solver 8% Dec15 -1466.18 In [20]: gilt.gamma(solver=solver) Out[20]: type instruments solver gilt_solver label 8% Dec15 local_ccy display_ccy type solver label gbp gbp instruments gilt_solver 8% Dec15 2.04
The DataFrame of cashflows.
In [21]: gilt.cashflows(solver=solver) Out[21]: Type Period Ccy Acc Start Acc End Payment Convention DCF Notional DF Collateral Rate Spread Cashflow NPV FX Rate NPV Ccy 0 FixedPeriod Regular GBP 1998-12-07 1999-06-07 1999-06-07 ActActICMA 0.50 -1000000.00 1.00 None 8.00 None 40000.00 0.00 1.00 0.00 1 FixedPeriod Regular GBP 1999-06-07 1999-12-07 1999-12-07 ActActICMA 0.50 -1000000.00 0.98 None 8.00 None 40000.00 39072.26 1.00 39072.26 2 FixedPeriod Regular GBP 1999-12-07 2000-06-07 2000-06-07 ActActICMA 0.50 -1000000.00 0.96 None 8.00 None 40000.00 38221.20 1.00 38221.20 3 FixedPeriod Regular GBP 2000-06-07 2000-12-07 2000-12-07 ActActICMA 0.50 -1000000.00 0.93 None 8.00 None 40000.00 37388.67 1.00 37388.67 4 FixedPeriod Regular GBP 2000-12-07 2001-06-07 2001-06-07 ActActICMA 0.50 -1000000.00 0.91 None 8.00 None 40000.00 36578.68 1.00 36578.68 5 FixedPeriod Regular GBP 2001-06-07 2001-12-07 2001-12-07 ActActICMA 0.50 -1000000.00 0.89 None 8.00 None 40000.00 35781.93 1.00 35781.93 6 FixedPeriod Regular GBP 2001-12-07 2002-06-07 2002-06-07 ActActICMA 0.50 -1000000.00 0.88 None 8.00 None 40000.00 35006.75 1.00 35006.75 7 FixedPeriod Regular GBP 2002-06-07 2002-12-09 2002-12-09 ActActICMA 0.50 -1000000.00 0.86 None 8.00 None 40000.00 34236.00 1.00 34236.00 8 FixedPeriod Regular GBP 2002-12-09 2003-06-09 2003-06-09 ActActICMA 0.50 -1000000.00 0.84 None 8.00 None 40000.00 33494.30 1.00 33494.30 9 FixedPeriod Regular GBP 2003-06-09 2003-12-08 2003-12-08 ActActICMA 0.50 -1000000.00 0.82 None 8.00 None 40000.00 32768.68 1.00 32768.68 10 FixedPeriod Regular GBP 2003-12-08 2004-06-07 2004-06-07 ActActICMA 0.50 -1000000.00 0.80 None 8.00 None 40000.00 32058.78 1.00 32058.78 11 FixedPeriod Regular GBP 2004-06-07 2004-12-07 2004-12-07 ActActICMA 0.50 -1000000.00 0.78 None 8.00 None 40000.00 31360.48 1.00 31360.48 12 FixedPeriod Regular GBP 2004-12-07 2005-06-07 2005-06-07 ActActICMA 0.50 -1000000.00 0.77 None 8.00 None 40000.00 30681.08 1.00 30681.08 13 FixedPeriod Regular GBP 2005-06-07 2005-12-07 2005-12-07 ActActICMA 0.50 -1000000.00 0.75 None 8.00 None 40000.00 30012.79 1.00 30012.79 14 FixedPeriod Regular GBP 2005-12-07 2006-06-07 2006-06-07 ActActICMA 0.50 -1000000.00 0.73 None 8.00 None 40000.00 29362.59 1.00 29362.59 15 FixedPeriod Regular GBP 2006-06-07 2006-12-07 2006-12-07 ActActICMA 0.50 -1000000.00 0.72 None 8.00 None 40000.00 28723.02 1.00 28723.02 16 FixedPeriod Regular GBP 2006-12-07 2007-06-07 2007-06-07 ActActICMA 0.50 -1000000.00 0.70 None 8.00 None 40000.00 28100.77 1.00 28100.77 17 FixedPeriod Regular GBP 2007-06-07 2007-12-07 2007-12-07 ActActICMA 0.50 -1000000.00 0.69 None 8.00 None 40000.00 27488.68 1.00 27488.68 18 FixedPeriod Regular GBP 2007-12-07 2008-06-09 2008-06-09 ActActICMA 0.50 -1000000.00 0.67 None 8.00 None 40000.00 26883.46 1.00 26883.46 19 FixedPeriod Regular GBP 2008-06-09 2008-12-08 2008-12-08 ActActICMA 0.50 -1000000.00 0.66 None 8.00 None 40000.00 26301.05 1.00 26301.05 20 FixedPeriod Regular GBP 2008-12-08 2009-06-08 2009-06-08 ActActICMA 0.50 -1000000.00 0.64 None 8.00 None 40000.00 25731.26 1.00 25731.26 21 FixedPeriod Regular GBP 2009-06-08 2009-12-07 2009-12-07 ActActICMA 0.50 -1000000.00 0.63 None 8.00 None 40000.00 25173.82 1.00 25173.82 22 FixedPeriod Regular GBP 2009-12-07 2010-06-07 2010-06-07 ActActICMA 0.50 -1000000.00 0.62 None 8.00 None 40000.00 24628.45 1.00 24628.45 23 FixedPeriod Regular GBP 2010-06-07 2010-12-07 2010-12-07 ActActICMA 0.50 -1000000.00 0.60 None 8.00 None 40000.00 24092.00 1.00 24092.00 24 FixedPeriod Regular GBP 2010-12-07 2011-06-07 2011-06-07 ActActICMA 0.50 -1000000.00 0.59 None 8.00 None 40000.00 23570.07 1.00 23570.07 25 FixedPeriod Regular GBP 2011-06-07 2011-12-07 2011-12-07 ActActICMA 0.50 -1000000.00 0.58 None 8.00 None 40000.00 23056.67 1.00 23056.67 26 FixedPeriod Regular GBP 2011-12-07 2012-06-07 2012-06-07 ActActICMA 0.50 -1000000.00 0.56 None 8.00 None 40000.00 22554.45 1.00 22554.45 27 FixedPeriod Regular GBP 2012-06-07 2012-12-07 2012-12-07 ActActICMA 0.50 -1000000.00 0.55 None 8.00 None 40000.00 22063.18 1.00 22063.18 28 FixedPeriod Regular GBP 2012-12-07 2013-06-07 2013-06-07 ActActICMA 0.50 -1000000.00 0.54 None 8.00 None 40000.00 21585.20 1.00 21585.20 29 FixedPeriod Regular GBP 2013-06-07 2013-12-09 2013-12-09 ActActICMA 0.50 -1000000.00 0.53 None 8.00 None 40000.00 21109.95 1.00 21109.95 30 FixedPeriod Regular GBP 2013-12-09 2014-06-09 2014-06-09 ActActICMA 0.50 -1000000.00 0.52 None 8.00 None 40000.00 20652.62 1.00 20652.62 31 FixedPeriod Regular GBP 2014-06-09 2014-12-08 2014-12-08 ActActICMA 0.50 -1000000.00 0.51 None 8.00 None 40000.00 20205.20 1.00 20205.20 32 FixedPeriod Regular GBP 2014-12-08 2015-06-08 2015-06-08 ActActICMA 0.50 -1000000.00 0.49 None 8.00 None 40000.00 19767.48 1.00 19767.48 33 FixedPeriod Regular GBP 2015-06-08 2015-12-07 2015-12-07 ActActICMA 0.50 -1000000.00 0.48 None 8.00 None 40000.00 19339.23 1.00 19339.23 34 Cashflow Exchange GBP NaT NaT 2015-12-07 None NaN -1000000.00 0.48 None NaN None 1000000.00 483480.80 1.00 483480.80
Attributes Summary
If set will also set the
fixed_rate
of the contained leg1.If set will also set the
float_spread
of contained leg1.If set will also set the
index_base
of the contained leg1.If set will also set the
fixed_rate
of the contained leg2.If set will also set the
float_spread
of contained leg2.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])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.
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
andleg2_float_spread
are attributes only applicable to certainInstruments
. 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
andleg2_index_base
are attributes only applicable to certainInstruments
. 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
andleg2_index_base
are attributes only applicable to certainInstruments
. 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
forleg1
.Discounting
Curve
forleg1
.
solver (Solver, optional) – The numerical
Solver
that constructsCurves
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
orFXForwards
object, converts from local currency intobase
.base (str, optional) – The base currency to convert cashflows into (3-digit code), set by default. Only used if
fx_rate
is anFXRates
orFXForwards
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 discountcurves
.
- Return type:
DataFrame
- cashflows_table(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#
- 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 [22]: 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 [23]: gilt.convexity(4.445, dt(1999, 5, 27)) Out[23]: 2.03673015861093
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 [24]: gilt.duration(4.445, dt(1999, 5, 27)) Out[24]: 14.65975398077815 In [25]: gilt.duration(4.455, dt(1999, 5, 27)) Out[25]: 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 [26]: 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 [27]: gilt.duration(4.445, dt(1999, 5, 27), "risk") Out[27]: 14.65975398077815 In [28]: gilt.duration(4.445, dt(1999, 5, 27), "modified") Out[28]: 10.39181988471933 In [29]: gilt.duration(4.445, dt(1999, 5, 27), "duration") Out[29]: 10.622778081657216
This result is interpreted as cents. If the yield is increased by 1bp the price will fall by 14.65 cents.
In [30]: gilt.price(4.445, dt(1999, 5, 27)) Out[30]: 141.31188978180361 In [31]: gilt.price(4.455, dt(1999, 5, 27)) Out[31]: 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.Some
calc_mode
options return True ifsettlement
is on 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, asettlement
that occurs on the coupon payment date will be classified as ex-dividend and not receive that coupon.With an
ex_div
of 0, asettlement
that occurs on the coupon payment date will not be classified as ex-dividend and will receive that coupon (in the default calculation mode).
- 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:
Notes
Any intermediate (non ex-dividend) cashflows between
settlement
andforward_settlement
will also be assumed to accrue atrepo_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
forleg1
.Discounting
Curve
forleg1
.
solver (Solver, optional) – The numerical
Solver
that constructsCurves
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
orFXForwards
object, converts from local currency intobase
.base (str, optional) – The base currency to convert cashflows into (3-digit code), set by default. Only used if
fx
is anFXRates
orFXForwards
object.local (bool, optional) – If True will ignore the
base
request and return a dict identifying local currency NPV.
- Return type:
Notes
The
settlement
date of the bond is inferred from the objectssettle
days parameter and the initial date of the suppliedcurves
. 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, dirty=False)#
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
forleg1
.Discounting
Curve
forleg1
.
solver (Solver, optional) – The numerical
Solver
that constructsCurves
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
orFXForwards
object, converts from local currency intobase
.base (str, optional) – The base currency to convert cashflows into (3-digit code), set by default. Only used if
fx
is anFXRates
orFXForwards
object.price (float, Dual, Dual2) – The price of the bond to match.
dirty (bool) – Whether the price is given clean or dirty.
- Return type:
- 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:
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.07013154004537
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.21164383561643835 In [7]: bond.price( ...: ytm=0.815, ...: settlement=dt(2017, 8, 23), ...: dirty=False ...: ) ...: Out[7]: 99.3348737576038
- rate(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, metric='clean_price', 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
forleg1
.Discounting
Curve
forleg1
.
solver (Solver, optional) – The numerical
Solver
that constructsCurves
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
orFXForwards
object, converts from local currency intobase
.base (str, optional) – The base currency to convert cashflows into (3-digit code), set by default. Only used if
fx
is anFXRates
orFXForwards
object.metric (str, optional) – Metric returned by the method. Available options are {“clean_price”, “dirty_price”, “ytm”}
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:
- 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:
Notes
Any intermediate (non ex-dividend) cashflows between
settlement
andforward_settlement
will also be assumed to accrue atrepo_rate
.
- ytm(price, settlement, dirty=False)#
Calculate the yield-to-maturity of the security given its price.
- Parameters:
price (float) – 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:
Notes
If
price
is given asDual
orDual2
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.445000002731656 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], [[...]]>