Bill#

class rateslib.instruments.Bill(effective=NoInput.blank, termination=NoInput.blank, modifier=NoInput.blank, calendar=NoInput.blank, payment_lag=NoInput.blank, notional=NoInput.blank, currency=NoInput.blank, convention=NoInput.blank, settle=NoInput.blank, calc_mode=NoInput.blank, curves=NoInput.blank, spec=NoInput.blank)#

Bases: FixedRateBond

Create a discount 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.
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).
convention (str, optional) – The day count convention applied to calculations of period accrual dates. See dcf().
settle (int) – The number of business days for regular settlement time, i.e, 1 is T+1. calc_mode : str in {“ukg”, “ust”, “sgb”} A calculation mode for dealing with bonds that are in short stub or accrual periods. All modes give the same value for YTM at issue date for regular bonds but differ slightly for bonds with stubs or with accrued.
calc_mode (str in {"ukg", "ust", "sgb"}) – A calculation mode for dealing with bonds that are in short stub or accrual periods. All modes give the same value for YTM at issue date for regular bonds but differ slightly for bonds with stubs or with accrued.
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.

Examples

This example is taken from the US Treasury Federal website. A copy of which is available here.

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

In [1]: bill = Bill(
   ...:     effective=dt(2004, 1, 22),
   ...:     termination=dt(2004, 2, 19),
   ...:     calendar="nyc",
   ...:     modifier="NONE",
   ...:     currency="usd",
   ...:     convention="Act360",
   ...:     settle=1,
   ...:     notional=-1e6,  # negative notional receives fixed, i.e. buys a bill
   ...:     curves="bill_curve",
   ...:     calc_mode="ustb",
   ...: )
   ...: 

In [2]: bill.ex_div(dt(2004, 1, 22))
Out[2]: False

In [3]: bill.price(rate=0.80, settlement=dt(2004, 1, 22))
Out[3]: 99.93777777777778

In [4]: bill.simple_rate(price=99.937778, settlement=dt(2004, 1, 22))
Out[4]: 0.8004952269972267

In [5]: bill.discount_rate(price=99.937778, settlement=dt(2004, 1, 22))
Out[5]: 0.7999971428571513

In [6]: bill.ytm(price=99.937778, settlement=dt(2004, 1, 22))
Out[6]: 0.8197045966975937

In [7]: bill.accrued(dt(2004, 1, 22))
Out[7]: 0.0

In [8]: bill.fwd_from_repo(
   ...:     price=99.937778,
   ...:     settlement=dt(2004, 1, 22),
   ...:     forward_settlement=dt(2004, 2, 19),
   ...:     repo_rate=0.8005,
   ...:     convention="Act360",
   ...: )
   ...: 
Out[8]: 100.00000037100256

In [9]: bill.repo_from_fwd(
   ...:     price=99.937778,
   ...:     settlement=dt(2004, 1, 22),
   ...:     forward_settlement=dt(2004, 2, 19),
   ...:     forward_price=100.00,
   ...:     convention="Act360",
   ...: )
   ...: 
Out[9]: 0.8004952269973565

In [10]: bill.duration(settlement=dt(2004, 1, 22), ytm=0.8005, metric="risk")
Out[10]: 0.07777777777777778

In [11]: bill.duration(settlement=dt(2004, 1, 22), ytm=0.8005, metric="modified")
Out[11]: 0.07782623325533848

In [12]: bill.convexity(settlement=dt(2004, 1, 22), ytm=0.8005)
Out[12]: -0.0

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

In [13]: bill_curve = Curve({dt(2004, 1, 21): 1.0, dt(2004, 3, 21): 1.0}, id="bill_curve")

In [14]: instruments = [
   ....:     (bill, (), {"metric": "ytm"}),
   ....: ]
   ....: 

In [15]: solver = Solver(
   ....:     curves=[bill_curve],
   ....:     instruments=instruments,
   ....:     s=[0.8005],
   ....:     instrument_labels=["Feb04 Tbill"],
   ....:     id="bill_solver",
   ....: )
   ....: 
SUCCESS: `func_tol` reached after 2 iterations (levenberg_marquardt), `f_val`: 7.316927923948108e-14, `time`: 0.0197s

In [16]: bill.npv(solver=solver)
Out[16]: <Dual: 999370.628211, (bill_curve0, bill_curve1), [516341.5, 483658.7]>

In [17]: bill.analytic_delta(disc_curve=bill_curve)
Out[17]: <Dual: -7.772883, (bill_curve0, bill_curve1), [-4.0, -3.8]>

In [18]: bill.rate(solver=solver, metric="price")
Out[18]: <Dual: 99.939232, (bill_curve0, bill_curve1), [-46.6, 46.7]>

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]: bill.delta(solver=solver)
Out[19]: 
local_ccy                             usd
display_ccy                           usd
type        solver      label            
instruments bill_solver Feb04 Tbill -7.84

In [20]: bill.gamma(solver=solver)
Out[20]: 
type                                                      instruments
solver                                                    bill_solver
label                                                     Feb04 Tbill
local_ccy display_ccy type        solver      label                  
usd       usd         instruments bill_solver Feb04 Tbill        0.00

The DataFrame of cashflows.

In [21]: bill.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  USD 2004-01-22 2004-02-19 2004-02-19     Act360 0.08 -1000000.00 1.00       None  0.00   None       0.00      0.00     1.00      0.00
1     Cashflow  Exchange  USD        NaT        NaT 2004-02-19       None  NaN -1000000.00 1.00       None   NaN   None 1000000.00 999370.63     1.00 999370.63

Attributes Summary

`dcf`
`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])
`convexity`(ytm, settlement)	Return the second derivative of `price` w.r.t.
`delta`(args, *kwargs)	Calculate the delta of the Instrument.
`discount_rate`(price, settlement)	Return the discount rate of the security from its `price`.
`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`(rate, settlement[, dirty, calc_mode])	Return the price of the bill given the `discount_rate`.
`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.
`simple_rate`(price, settlement)	Return the simple rate of the security from its `price`.
`ytm`(price, settlement[, calc_mode])	Calculate the yield-to-maturity on an equivalent bond with a coupon of 0%.

Attributes Documentation

dcf#

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

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 [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.convexity(4.445, dt(1999, 5, 27))
Out[2]: 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 [3]: gilt.duration(4.445, dt(1999, 5, 27))
Out[3]: 14.65975398077815

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

delta(*args, **kwargs)#

Calculate the delta of the Instrument.

For arguments see Sensitivities.delta().

discount_rate(price, settlement)#

Return the discount rate of the security from its price.

Parameters:

price (float, Dual, or Dual2) – The price of the security.
settlement (datetime) – The settlement date of the security.

Return type:

float, Dual, or Dual2

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]: 14.65975398077815

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

In [4]: gilt.duration(4.445, dt(1999, 5, 27), "duration")
Out[4]: 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.31188978180361

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.

Some calc_mode options return True if settlement 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, 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 (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:

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, 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 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.
dirty (bool) – Whether the price is given clean or dirty.

Return type:

float, Dual, Dual2

price(rate, settlement, dirty=False, calc_mode=NoInput.blank)#

Return the price of the bill given the discount_rate.

Parameters:

rate (float) – The rate used by the pricing formula.
settlement (datetime) – The settlement date.
dirty (bool, not required) – Discount securities have no coupon, the concept of clean or dirty is not relevant. Argument is included for signature consistency with FixedRateBond.price.
calc_mode (str, optional) – A calculation mode to force, which is used instead of that attributed the Bill instance.

Return type:

float, Dual, Dual2

rate(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, metric='price')#

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) – 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.
metric (str in {"price", "discount_rate", "ytm", "simple_rate"}) – Metric returned by the method.

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.

simple_rate(price, settlement)#

Return the simple rate of the security from its price.

Parameters:

price (float, Dual, or Dual2) – The price of the security.
settlement (datetime) – The settlement date of the security.

Return type:

float, Dual, or Dual2

ytm(price, settlement, calc_mode=NoInput.blank)#

Calculate the yield-to-maturity on an equivalent bond with a coupon of 0%.

Parameters:

price (float, Dual, Dual2) – The price of the Bill.
settlement (datetime) – The settlement date of the Bill.
calc_mode (str, optional) – A calculation mode to force, which is used instead of that attributed the Bill instance.

Notes

Maps the following Bill calc_mode to the following Bond specifications:

NoInput -> “ust”
“ustb” -> “ust”
“uktb” -> “ukt”
“sgbb” -> “sgb”

This method calculates by constructing a FixedRateBond with a regular 0% coupon measured from the termination date of the bill.