FloatRateNote#
- class rateslib.instruments.FloatRateNote(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, float_spread=NoInput.blank, fixings=NoInput.blank, fixing_method=NoInput.blank, method_param=NoInput.blank, spread_compound_method=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 floating rate note (FRN) 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.
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()
.float_spread (float, optional) – The spread applied to determine cashflows. Can be set to None and designated later, perhaps after a mid-market spread for all periods has been calculated.
spread_compound_method (str, optional) – The method to use for adding a floating spread to compounded rates. Available options are {“none_simple”, “isda_compounding”, “isda_flat_compounding”}.
fixings (float or list, optional) – If a float scalar, will be applied as the determined fixing for the first period. If a list of n fixings will be used as the fixings for the first n periods. If any sublist of length m is given as the first m RFR fixings within individual curve and composed into the overall rate.
fixing_method (str, optional) – The method by which floating rates are determined, set by default. See notes.
method_param (int, optional) – A parameter that is used for the various
fixing_method
s. See notes.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.
Notes
Warning
FRNs based on RFR rates which have ex-div days must ensure that fixings are available to define the entire period. This means that ex_div days must be less than the fixing_method method_param lag minus the time to settlement time.
That is, a bond with a method_param of 5 and a settlement time of 2 days can have an ex_div period of at maximum 3.
A bond with a method_param of 2 and a settlement time of 1 day cnan have an ex_div period of at maximum 1.
- ex_div_days#
- Type:
int
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[, curve])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])delta
(*args, **kwargs)Calculate the delta of the Instrument.
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
.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.
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, curve=NoInput.blank)#
Calculate the accrued amount per nominal par value of 100.
- Parameters:
settlement (datetime) – The settlement date which to measure accrued interest against.
curve (Curve, optional) – If
forecast
is True and fixings are future based then must provide a forecast curve.
Notes
The settlement of an FRN will always be a definite amount. The
fixing_method
,method_param
andex_div
will contain a valid combination of parameters such that when payments need to be cleared these definitive amounts can be calculated via previously published fixings.If the coupon is IBOR based then the accrued fractionally apportions the coupon payment based on calendar days, including negative accrued during ex div periods. This rarely poses a problem since IBOR is fixed well in advance of settlement.
\[\text{Accrued} = \text{Coupon} \times \frac{\text{Settle - Last Coupon}}{\text{Next Coupon - Last Coupon}}\]With RFR rates, however, and since
settlement
typically occurs in the future, e.g. T+2, it may be possible, particularly if the bond is ex-div that some fixings are not known today, but they will be known bysettlement
. This is also true if we wish to calculate the forward dirty price of a bond and need to forecast the accrued amount (and also for a forecast IBOR period).Thus, there are two options:
In the analogue mode where very few fixings might be missing, and we require these values to calculate negative accrued in an ex-div period we do not require a
curve
but repeat the last historic fixing.In the digital mode where the
settlement
is likely in the future we use acurve
to forecast rates,
Examples
An RFR based FRN where the fixings are known up to the end of period.
In [1]: fixings = Series(2.0, index=date_range(dt(1999, 12, 1), dt(2000, 6, 2))) In [2]: frn = FloatRateNote( ...: effective=dt(1998, 12, 7), ...: termination=dt(2015, 12, 7), ...: frequency="S", ...: currency="gbp", ...: convention="Act365F", ...: ex_div=3, ...: fixings=fixings, ...: fixing_method="rfr_observation_shift", ...: method_param=5, ...: ) ...: In [3]: frn.accrued(dt(2000, 3, 27)) Out[3]: 0.6100558220310195 In [4]: frn.accrued(dt(2000, 6, 4)) Out[4]: 0.9911540636168727
An IBOR based FRN where the coupon is known in advance.
In [5]: fixings = Series(2.0, index=[dt(1999, 12, 5)]) In [6]: frn = FloatRateNote( ...: effective=dt(1998, 12, 7), ...: termination=dt(2015, 12, 7), ...: frequency="S", ...: currency="gbp", ...: convention="Act365F", ...: ex_div=7, ...: fixings=fixings, ...: fixing_method="ibor", ...: method_param=2, ...: ) ...: In [7]: frn.accrued(dt(2000, 3, 27)) Out[7]: 0.608219178082192 In [8]: frn.accrued(dt(2000, 6, 4)) Out[8]: -0.016438356164383584
- 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)#
- delta(*args, **kwargs)#
Calculate the delta of the Instrument.
For arguments see
Sensitivities.delta()
.
- 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:
- 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”, “spread”}
forward_settlement (datetime, optional) – The forward settlement date. If not give uses the discount Curve and the bond’s
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
.