BondCalcMode#

class rateslib.instruments.BondCalcMode(settle_accrual_type, ytm_accrual_type, v1_type, v2_type, v3_type)#

Bases: object

Define calculation conventions for FixedRateBond, IndexFixedRateBond and FloatRateNote types.

Parameters:

  • settle_accrual_type (str,) – The calculation type for accrued interest for physical settlement.

  • ytm_accrual_type (str) – The calculation method for accrued interest used in the YTM formula. Often the same as above but not always (e.g. Canadian GBs).

  • v1_type (str) – The calculation function that defines discounting of the first period of the YTM formula.

  • v2_type (str) – The calculation function that defines discounting of the regular periods of the YTM formula.

  • v3_type (str) – The calculation function that defines discounting of the last period of the YTM formula.

Notes

Accrual Functions

These functions return the fraction of a bond cashflow that is attributed to the settlement date, in order to determine accrued interest. The available input options are;

  • “linear_days”: Measures a calendar day, linear proportion between unadjusted start and end coupon dates of the coupon period, and applies that proportion to the cashflow, which is calculated separately using the conventions for the bond. (Typically used by many bonds, e.g. UK and German GBs)

    \[\begin{split}&\text{Accrual fraction} = r / s \\ &\text{where,} \\ &r = \text{Calendar days between last coupon (unadjusted) and settlement} \\ &s = \text{Calendar days between unadjusted coupon dates} \\\end{split}\]

  • “linear_days_long_front_split”: Is the same as above, except in the case of long stub periods, which are treated as front stubs. (Primarily implemented to satisfy the US Treasury calculations in Section 31B ii A.356)

  • “30e360”: Ignores the coupon convention on the bond and calculates accrued from the unadjusted last coupon date to settlement with a 30e360 day count convention, except stubs revert to ‘linear_days’. (Used by Swedish GBs)

    \[\begin{split}&\text{Accrual fraction} = 1 - d f \\ &\text{where,} \\ &d = \text{30e360 DCF between settlement and next unadjusted coupon date} \\ &f = \text{Number of regular coupon periods per year} \\\end{split}\]

  • “Act365_1y”: Ignores the coupon convention on the bond and calculates accrued from the unadjusted last coupon date to settlement with an Act365F day count convention. Stub periods are adjusted to use ‘linear_days’ and periods longer than 1y have additional adjustment. (Used by Canadian GBs)

    \[\begin{split}& r = s \qquad \implies \quad \text{Accrual fraction} = 1.0 \\ & r > 365 / f \qquad \implies \quad \text{Accrual fraction} = 1.0 - f(s-r) / 365 \\ & r \le 365 / f \qquad \implies \quad \text{Accrual fraction} = rf / 365 \\\end{split}\]

Discounting Functions for YTM Calculation

Yield-to-maturity is calculated using the below formula, where specific functions derive some values based on the conventions of a given bond.

\[\begin{split}P &= v_1 \left ( c_1 + 100 \right ), \quad n = 1 \\ P &= v_1 \left ( c_1 + v3(c_2 + 100) \right ), \quad n = 2 \\ P &= v_1 \left ( \sum_{i=1}^{n-1} c_i v_2^{i-1} + c_nv_2^{n-2}v_3 + 100 v_2^{n-2}v_3 \right ), \quad n > 1 \\\end{split}\]

where,

\[\begin{split}P &= \text{Dirty price}, \; n = \text{Coupon periods remaining} \\ c_1 &= \text{Cashflow (per 100) on next coupon date (may be zero if ex-dividend)} \\ c_i &= i \text{'th cashflow (per 100) on subsequent coupon dates} \\ v_1 &= \text{Discount value for the initial, possibly stub, period} \\ v_2 &= \text{Discount value for the interim regular periods} \\ v_3 &= \text{Discount value for the final, possibly stub, period} \\\end{split}\]

v1 Functions

  • “compounding”: the exponent is defined by the generated ytm accrual fraction.

  • “compounding_stub_act365f”: stub exponents use act365f convention to derive.

  • “compounding_final_simple”: uses simple method only for the final period of the bond.

  • “simple”: calculation uses a simple interest formula.

  • “simple_long_stub_compounding”: uses simple interest formula except for long stubs which are combined with compounding formula for the regular period of the stub.

v2 Functions

  • “regular”: uses the traditional discounting function per the frequency of coupons:

    \[v_2 = \frac{1}{1 + \frac{y}{f}}\]

  • “annual”: assumes an annually expressed YTM disregarding the actual coupon frequency:

    \[v_2 = \left ( \frac{1}{1 + y} \right ) ^ {\frac{1}{f}}\]

v3 Functions

  • “compounding”

  • “simple”

  • “simple_30e360”: the final period uses simple interest with a DCF calculated under 30e360 convention, irrespective of the bond’s underlying convention.

Attributes Summary

kwargs

String representation of the parameters for the calculation convention.

Attributes Documentation

kwargs#

String representation of the parameters for the calculation convention.