API Documentation

Yield Curve

class yieldcurves.YieldCurve(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None)

Bases: _YieldCurveAdapter

general financial yield curve

Parameters:

• curve – curve of spot yields

• spot_price – price at time 0 (optional: default 1.0)

• compounding_frequency –

  compounding zero rate frequency

  • None -> continuous compounding

  • 0 -> simple compounding

  • 12 -> monthly compounding

  • 4 -> quarterly compounding

  • 2 -> semi annually compounding

  • 1 -> annually compounding

  (optional, default: None i.e. continuous compouding)

• cash_frequency – cash rate compounding frequency (optional, default: 4 i.e. quarterly compounding)

• swap_frequency – swap coupon frequency (optional, default: 1 i.e. annual payment)

yieldcurves.yieldcurves.YieldCurve class consumes a continuous componding yield curve as mandantory argument and provides a varity of methods to derive financial figures.

>>> from curves.interpolation import linear
>>> from yieldcurves import YieldCurve

>>> yc = YieldCurve(linear([0, 10], [0.01, 0.02]), spot_price=100, compounding_frequency=12)
>>> yc
YieldCurve(linear([0.0, 10.0], [0.01, 0.02]), spot_price=100, compounding_frequency=12)

asset yield related

the forward price \(p(t) = p_0 \cdot e^{t \cdot r(t)}\) of asset with spot price of \(p_0\)

>>> yc.price(9)
118.649074...

forward prices factor \(p(t, t') = \frac{p(t')}{p(t)}\)

>>> f = yc.price(1, 9)
>>> 100 * f * yc.price(0, 1)
118.6490749...

spot rate \(r(t) = f(0, t)\)

>>> yc.spot(2)
0.012000...

and therefor the same as the inner curve

>>> yc.curve(2)
0.012

forward spot rate \(f(t, t') = \frac{r(t') - r(t)}{t' - t}\)

>>> yc.spot(2, 4)
0.015999...

short rate or instantanuous forward rate \(s(t) = \lim_{t' \to t} f(t, t')\) s.th. \(r(t, t') (t' - t) = \int_t^{t'} s(\tau)\ d \tau\)

>>> yc.short(2)
0.0139999...

interest rate related

discount factor \(P(t, t') = p(t, t')^{-1}\)

>>> yc.df(1, 9)
0.852143...

>>> 1 / yc.price(1, 9)
0.852143...

zero rate \(P(0, t) = \prod_{i=1}^{m * t} (1 + r(t) / m)^{m \cdot t}\) with compounding_frequency \(m\)

>>> yc.zero(9)
0.019015...

forward zero rate

>>> yc.zero(1, 9)
0.020016...

simple compounded cash rate \(L(t) = \frac{1}{\tau} ( P(t) - P(t + \tau) ) P(t, t + \tau)^{-1}\) with cash_frequency \(n\) and tenor \(\tau = 1 / n\)

>>> yc.cash(5)
0.020301...

swap annuity \(A(t) = \sum_{i=1}^{k \cdot t} P(0, \frac{i}{k})\) mit swap_frequency \(k\) as fixed coupon frequency

>>> yc.annuity(10)
9.124091...

forward swap annuity \(A(t, t') = \sum_{i=1}^{k \cdot t'} P(t, t + \frac{i}{k})\) mit swap_frequency \(k\) as fixed coupon frequency

>>> yc.annuity(5, 10)
4.660460...

forward swap annuity with list argument \(T = (t_0, \dots, t_n)\) \(A(T) = \sum_{i=1}^{n} P(t_0, t_i) \cdot (t_i - t_{i-1})\) and therefor ignoring swap_frequency

>>> yc.annuity([5, 6, 7, 8, 9, 10])
4.660460...

forward swap par rate \(c(t) = \frac{1 - P(0, t)}{A(t)}\) with swap annuity \(A(t)\).

>>> yc.swap(10)
0.019867...

>>> yc.swap(5, 10)
0.025212765324721546

>>> yc.swap([5, 6, 7, 8, 9, 10])
0.025212...

credit related

survival probability $P(t, t’) = e^{t cdot r(t) - t’ cdot r(t’))}

>>> yc.prob(5, 10)
0.882496...

intensity \(\lambda(t) = r(t)\)

>>> yc.intensity(5)
0.015000...

>>> yc.intensity(5, 10)
0.025000...

hazard rate \(h(t) = \lim_{t' \to t} \lambda(t, t')\)

>>> yc.hz(5)
0.020000...

probability of default \(pd(t, t') = 1 - P(t, t')\)

>>> yc.pd(5, 10)
0.117503...

>>> 1 - yc.prob(5, 10)
0.117503...

marginal or annual survival probability \(\Pi(t) = P(t, t + 1)\)

>>> yc.marginal(5)
0.979218...

>>> yc.prob(5, 6)
0.979218...

marginal or annual probability of default \(Pd(t) = 1 - \Pi(t)\)

>>> yc.marginal_pd(5)
0.0207810...

>>> 1 - yc.prob(5, 6)
0.0207810...

class from_prices(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None)

Bases: _YieldCurveAdapter

yield curve from curve of prices

>>> from curves.interpolation import linear
>>> from yieldcurves import YieldCurve

>>> c = linear([0, 10], [100, 120])
>>> yc = YieldCurve.from_prices(c)
>>> yc(5)  # spot rate
0.01906203596086498

>>> yc.price(10)
120.0

price(x, y=None)

price at x or price factor from x to y

class from_spot_rates(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None)

Bases: _YieldCurveAdapter

yield curve from curve of spot rates

>>> from curves.interpolation import linear
>>> from yieldcurves import YieldCurve

>>> c = linear([0, 10], [0.05, 0.06])
>>> yc = YieldCurve.from_spot_rates(c)
>>> yc(5)  # spot rate
0.055

>>> yc.spot(7.5)
0.0574999...

>>> yc.price(10)
1.8221188...

class from_short_rates(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None)

Bases: _YieldCurveAdapter

yield curve from curve of short rates

>>> from curves.interpolation import linear
>>> from yieldcurves import YieldCurve

>>> c = linear([0, 10], [0.05, 0.06])
>>> yc = YieldCurve.from_short_rates(c)
>>> yc(5)  # spot rate
0.052500000000000005

>>> yc.short(10)
0.06

>>> yc.price(10)
1.7332530178673953

short(x, y=None)

short rate aka. instantaneous forward rate

class from_df(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None)

Bases: _YieldCurveAdapter

yield curve from curve of discount factors

>>> from curves.interpolation import linear
>>> from yieldcurves import YieldCurve

>>> c = linear([0, 10], [0.99, 0.9])
>>> yc = YieldCurve.from_df(c)
>>> yc(5)  # spot rate
0.009304003126978563

>>> yc.df(10)
0.9

>>> yc.price(10)
1.0999999999999999

df(x, y=None)

continuous compounded discount factor, i.e. 1 / price(x, y)

class from_zero_rates(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None, frequency=None)

Bases: _CompoundingYieldCurveAdapter

yield curve from curve of zero coupon bond rates

>>> from curves.interpolation import linear
>>> from yieldcurves import YieldCurve

>>> c = linear([0, 10], [0.05, 0.06])
>>> yc = YieldCurve.from_zero_rates(c, frequency=12, compounding_frequency=4)
>>> yc(5)  # spot rate
0.054874...

>>> yc.zero(10)
0.06

>>> yc.price(10)
1.819396...

zero(x, y=None)

zero coupon bond rate, compounded with frequency

class from_cash_rates(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None, frequency=None)

Bases: _CompoundingYieldCurveAdapter

yield curve from curve of simple compound cash rates

cash(x, y=None)

simple compound cash rate with tenor 1/cash_frequency

class from_swap_rates(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None, frequency=None)

Bases: _CompoundingYieldCurveAdapter

yield curve from curve of swap par rates

swap(x, y=None)

swap par rate

class from_probs(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None)

Bases: _YieldCurveAdapter

yield curve from curve of survival probabilities

prob(x, y=None)

survival probability

class from_intensities(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None)

Bases: _YieldCurveAdapter

yield curve from curve of intensities

class from_hazard_rates(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None)

Bases: _YieldCurveAdapter

yield curve from curve of hazard rates

hz(x, y=None)

hazard rate

class from_pd(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None)

Bases: _YieldCurveAdapter

yield curve from curve of probabilities of default

pd(x, y=None)

probability of default

class from_marginal_probs(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None)

Bases: _YieldCurveAdapter

yield curve from curve of annual survival probabilities

marginal(x, y=None)

annual survival probability

class from_marginal_pd(curve, *, spot_price=None, compounding_frequency=None, cash_frequency=None, swap_frequency=None)

Bases: _YieldCurveAdapter

yield curve from curve of annual probabilities of default

marginal_pd(x, y=None)

annual probability of default

class yieldcurves.operators.YieldCurveOperator(curve: YieldCurve)

Bases: object

Operator turning yieldcurves.yieldcurves.YieldCurve into simple callable

>>> from curves.interpolation import linear
>>> from yieldcurves import YieldCurve
>>> yc = YieldCurve(linear([0, 10], [0.01, 0.02]), spot_price=10)

Turn yield curve into general finanical curve like …

… a price curve

>>> from yieldcurves import Price
>>> p = Price(yc)

>>> p(1.234)
10.139592895598932

>>> yc.price(1.234) == p(1.234)
True

… a spot rate curve

>>> from yieldcurves import Spot
>>> s = Spot(yc)

>>> s(1.234)
0.011233999999999886

>>> yc.spot(1.234) == s(1.234)
True

… a short rate curve

>>> from yieldcurves import Short
>>> sh = Short(yc)

>>> sh(1.234)
0.012468004483236131

>>> yc.short(1.234) == sh(1.234)
True

… or into interest rate related curve like …

… a discount factor curve

>>> from yieldcurves import Df
>>> df = Df(yc)

>>> df(1.234)
0.9862328895216768

>>> yc.df(1.234) == df(1.234)
True

… a zero rate curve

>>> from yieldcurves import Zero
>>> z = Zero(yc)

>>> z(1.234)
0.011233999999999886

>>> yc.zero(1.234) == z(1.234)
True

… a cash rate curve

>>> from yieldcurves import Cash
>>> ch = Cash(yc)

>>> ch(1.234)
0.012738239885720759

>>> yc.cash(1.234) == ch(1.234)
True

… a swap annuity curve

>>> from yieldcurves import Annuity
>>> an = Annuity(yc)

>>> an(1.234)
1.2198387749234412

>>> yc.annuity(1.234) == an(1.234)
True

… a swap par rate curve

>>> from yieldcurves import Swap
>>> sw = Swap(yc)

>>> sw(1.234)
0.01128600825071107

>>> yc.swap(1.234) == sw(1.234)
True

… or into credit related curve like …

… a survival probability curve

>>> from yieldcurves import Prob
>>> pb = Prob(yc)

>>> pb(1.234)
0.9862328895216768

>>> yc.prob(1.234) == pb(1.234)
True

… a intensity curve

>>> from yieldcurves import Intensity
>>> it = Intensity(yc)

>>> it(1.234)
0.011233999999999886

>>> yc.intensity(1.234) == it(1.234)
True

… a hazard rate curve

>>> from yieldcurves import Hz
>>> hz = Hz(yc)

>>> hz(1.234)
0.012468004483236131

>>> yc.hz(1.234) == hz(1.234)
True

… a probalility of default curve

>>> from yieldcurves import Pd
>>> pd = Pd(yc)

>>> pd(1.234)
0.013767110478323241

>>> yc.pd(1.234) == pd(1.234)
True

… a marginal/annual survival probalility curve

>>> from yieldcurves import Marginal
>>> mg = Marginal(yc)

>>> mg(1.234)
0.9866222877257945

>>> yc.marginal(1.234) == mg(1.234)
True

… a marginal/annual probalility of default curve

>>> from yieldcurves import MarginalPd
>>> md = MarginalPd(yc)

>>> md(1.234)
0.013377712274205478

>>> yc.marginal_pd(1.234) == md(1.234)
True

Yield Curve Models

class yieldcurves.NelsonSiegelSvensson(*, beta0=0.0, beta1=0.0, beta2=0.0, beta3=0.0, tau1=1.0, tau2=1.0, timestamp=None)

Bases: object

Nelson Siegel Svensson interest term structure cruve

Parameters:

• beta0 – \(\beta_0\) parameter

• beta1 – \(\beta_1\) parameter

• beta2 – \(\beta_2\) parameter

• beta3 – \(\beta_3\) parameter

• tau1 – \(\tau_1\) decay parameter

• tau2 – \(\tau_2\) decay parameter

• timestamp – timestamp of curve

>>> from yieldcurves import NelsonSiegelSvensson

downloads = {}

dictionary of downloaded curves with keys as dates as string

spot(x)

spot interest rate

Parameters:

x – maturity

Returns:

spot rate \(R(x)\) at x

\[R(x) = \beta_0 + \beta_1 \left( \frac{1 - e^{-\frac{x}{\tau_1}}}{\frac{x}{\tau_1}} \right) + \beta_2 \left( \frac{1 - e^{-\frac{x}{\tau_1}}}{\frac{x}{\tau_1}} - e^{-\frac{x}{\tau_1}} \right) + \beta_3 \left( \frac{1 - e^{-\frac{x}{\tau_2}}}{\frac{x}{\tau_2}} - e^{-\frac{x}{\tau_2}} \right)\]

short(x)

short rate (instantaneous spot rate)

Parameters:

x – maturity

Returns:

short rate \(r(x)\) at x

\[r(x) = \beta_0 + \beta_1 \left( e^{-\frac{x}{\tau_1}} \right) + \beta_2 \left( e^{-\frac{x}{\tau_1}} \frac{x}{\tau_1} \right) + \beta_3 \left( e^{-\frac{x}{\tau_2}} \frac{x}{\tau_2} \right)\]

classmethod download(t=None)

build curve with parameters from ecb :param t: date of parameters or (if of integer) latest parameter :return:

>>> from yieldcurves import NelsonSiegelSvensson
>>> nss = NelsonSiegelSvensson.download('2024-08-01')
>>> nss
NelsonSiegelSvensson(beta0=0.3930624673, beta1=3.0642695848, beta2=-6.0856376597, beta3=9.3989699383, tau1=4.0804649054, tau2=9.9328952349, timestamp='2024-08-01')

or load a bulk of curves, here the last of the last 10 days

>>> _ = NelsonSiegelSvensson.download(10)

to get all already loaded curves

>>> len(NelsonSiegelSvensson.downloads)
11

class yieldcurves.HullWhite(mean_reversion=0.0, volatility=0.0, terminal_date=1.0, *, domestic=None, fx_volatility=0.0, domestic_correlation=0.0, fx_correlation=0.0, domestic_fx_correlation=0.0)

Bases: _HullWhiteModel

>>> from yieldcurves import HullWhite
>>> hw = HullWhite.Curve(0.02, mean_reversion=0.1, volatility=0.01)
>>> hw.model.random.seed(101)

>>> hw(2)
0.020000...

>>> hw.evolve(1)
>>> hw(2)
0.010080...

>>> hw.evolve(2)
>>> hw(2)
0.005147...

class Curve(curve, *, model=None, **kwargs)

Bases: _HullWhiteCurve

class Fx(curve, *, model=None, domestic_curve=0.0, foreign_curve=0.0, **kwargs)

Bases: _HullWhiteFx

class Global(factors, correlation=None)

Bases: _HullWhiteGlobal

init global HullWhite model from factors and correlation

Parameters:

• factors

• correlation

>>> from yieldcurves import HullWhite

>>> rate_corr = [[1.0, 0.6], [0.6, 1.0]]
>>> fx_corr = [[1.0]]
>>> rate_fx_corr = [[0.22], [0.33]]
>>> corr = HullWhite.Global.foreign_correlation(rate_corr, fx_corr, rate_fx_corr)

>>> domestic = HullWhite(0.1, 0.05).curve(0.02)
>>> foreign =  HullWhite(0.2, 0.02, domestic=domestic, fx_volatility=0.2).curve(0.05)
>>> fx = foreign.model.fx(2.2)

>>> g = HullWhite.Global([domestic, foreign, fx], correlation=corr)

>>> d, f, x = g.factors
>>> d(.5), f(.5), d(1.5), f(1.5), float(x)
(0.019999..., 0.050000..., 0.020000..., 0.050000..., 2.2)

>>> g.evolve()
>>> dict(f.items())
{0.25: 0.008438...}

>>> d(.5), f(.5), d(1.5), f(1.5), float(x)
(0.048727..., 0.038701..., 0.060689..., 0.049152..., 2.089911...)

>>> g.evolve()
>>> dict(f.items())
{0.25: 0.008438..., 0.5: 0.010379...}

>>> d(.5), f(.5), d(1.5), f(1.5), float(x)
(0.039533..., 0.029960..., 0.057559..., 0.044305..., 2.161724...)

>>> g.clear()
>>> dict(f.items())
{}

>>> d(.5), f(.5), d(1.5), f(1.5), float(x)
(0.019999..., 0.050000..., 0.020000..., 0.050000..., 2.2)

Yield Curves for Option Pricing

class yieldcurves.OptionPricingCurve(curve: Callable, *, formula: OptionPricingFormula = None, volatility: Callable = None, bump_greeks: bool = False, bump_binary: float | bool | None = 0.0001)

Bases: object

curve extension for option pricing

Parameters:

• curve – forward curve to derives forward values

• formula – call option pricing formula callable which must provide float consuming signature formula(tau, strike, forward, volatility) here tau is the time to expiry y-x

• volatility – volatility curve

• bump_greeks – bool - if True Greeks, i.e. sensitivities/derivatives, are derived numerically. If False analytics functions are used, if given. See also yieldcurves.optionpricing.OptionPricingFormula. (optional; default is False)

• bump_binary – finite difference to calculate Binary option payoffs numerically i.e. digital options are derived numerically via call/ put spreads. If False, None or 0.0 analytics functions are used, e.g. formula.binary_call if present. See also yieldcurves.optionpricing.OptionPricingFormula. (optional; default is 0.0001)

DELTA_SHIFT = 0.0001

finite difference to calculate numerical delta sensitivities

DELTA_SCALE = 0.0001

factor to express numerical delta sensitivities usually in a value of a basis point (bpv)

Let \(\delta\) be the DELTA_SHIFT and \(\epsilon\) be the DELTA_SCALE and \(f\) a forward \(F\) sensitive function such that

\[f' = \frac{df}{dF} \approx \Delta_f(F) = \frac{f(F+\delta) - f(x)}{\delta/\epsilon}.\]

VEGA_SHIFT = 0.01

finite difference to calculate numerical vega sensitivities

VEGA_SCALE = 0.01

factor to express numerical vega sensitivities

Let \(\delta\) be the VEGA_SHIFT and \(\epsilon\) be the VEGA_SCALE and \(f\) a volatility \(\nu\) sensitive function such that

\[f'_\nu = \frac{df}{d\nu} \approx \mathcal{V}_f(\nu) = \frac{f(\nu+\delta) - f(\nu)}{\delta/\epsilon}.\]

THETA_SHIFT = 0.0027378507871321013

finite difference to calculate numerical theta sensitivities usually one day (1/365.25)

THETA_SCALE = 0.0027378507871321013

factor to express numerical theta sensitivities usually one day (1/365.25)

Let \(\delta\) be the THETA_SHIFT and \(\epsilon\) be the THETA_SCALE and \(f\) a tau \(\tau(t,T)\) sensitive function with valuation date \(t\) and option maturity date \(T\) such that

\[\dot{f} = \frac{df}{dt} \approx \Theta_f(t) = \frac{f(\tau(t,T)+\delta) - f(\tau(t,T))}{\delta/\epsilon}.\]

classmethod intrinsic(curve, volatility=None)

classmethod bachelier(curve, volatility=None)

classmethod black76(curve, volatility=None)

classmethod displaced_black76(curve, volatility=None, *, displacement=0.0)

forward(x, y=None)

details(x, y=None, *, strike=None, **__)

model parameter details

Parameters:

• x – option valuation date

• y – option expiry date (also fixing date) (optional; if not given x will be expiry date)

• strike – option strike value (optional; default None, i.e. at-the-money)

Returns:

dict()

call(x, y=None, *, strike=None)

value of a call option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F(T)\)

Returns:

\(C_K(F(T))=E[\max(F(T)-K, 0)]\)

put(x, y=None, *, strike=None)

value of a put option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(P_K(F(T))=E[\max(K-F(T), 0)]\)

Note \(P_K(F(T))\) is derived by put-call parity:

\[P_K(F(T)) = K - F(T) + C_K(F(T))\]

call_delta(x, y=None, *, strike=None)

delta sensitivity of a call option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Delta_{C_K(F)} = \frac{d}{d F} C_K(F)\)

\(\Delta_{C_K(F)}\) is the first derivative of \(C_K(F)\) in unterlying direction \(F\).

put_delta(x, y=None, *, strike=None)

delta sensitivity of a put option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Delta_{P_K(F)} = \frac{d}{d F} P_K(F)\)

\(\Delta_{P_K(F)}\) is the first derivative of \(P_K(F)\) in underlying direction \(F\) and is derived by put-call parity, too:

\[\Gamma_{P_K(F)} = \Delta_{C_K(F)} - 1\]

Note, here \(1\) is actualy scaled by yieldcurves.optioncurves.OptionPricingCurve.DELTA_SCALE.

call_gamma(x, y=None, *, strike=None)

gamma sensitivity of a call option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Gamma_{C_K(F)} = \frac{d^2}{d F^2} C_K(F)\)

\(\Gamma_{C_K(F)}\) is the second derivative of \(C_K(F)\) in unterlying direction \(F\).

put_gamma(x, y=None, *, strike=None)

gamma sensitivity of a put option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Gamma_{P_K(F)} = \frac{d^2}{d F^2} P_K(F)\)

\(\Gamma_{P_K(F)}\) is the second derivative of \(P_K(F)\) in unterlying direction \(F\) and is derived by put-call parity, too:

\[\Gamma_{P_K(F)} = \Gamma_{C_K(F)}\]

call_vega(x, y=None, *, strike=None)

vega sensitivity of a call option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\mathcal{V}_{C_K(F)} = \frac{d}{d v} C_K(F)\)

\(\mathcal{V}_{C_K(F)}\) is the first derivative of \(C_K(F)\) in volatility parameter direction \(v\).

put_vega(x, y=None, *, strike=None)

vega sensitivity of a put option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\mathcal{V}_{P_K(F)} = \frac{d}{d v} P_K(F)\)

\(\mathcal{V}_{P_K(F)}\) is the first derivative of \(P_K(F)\) in volatility parameter direction \(v\) and is derived by put-call parity, too:

\[\mathcal{V}_{P_K(F)} = \mathcal{V}_{C_K(F)}\]

call_theta(x, y=None, *, strike=None)

tau sensitivity of a call option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Theta_{C_K(F)} = \frac{d}{d t} C_K(F)\)

\(\Theta_{C_K(F)}\) is the first derivative of \(C_K(F)\) in tau parameter direction, i.e. valuation date \(t\).

put_theta(x, y=None, *, strike=None)

tau sensitivity of a put option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Theta_{P_K(F)} = \frac{d}{d t} P_K(F)\)

\(\Theta_{P_K(F)}\) is the first derivative of \(P_K(F)\) in tau parameter direction, i.e. valuation date \(t\).

binary_call(x, y=None, *, strike=None)

value of a binary call option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\delta C_K(F(T))=E[ ]\)

binary_put(x, y=None, *, strike=None)

value of a put option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\delta P_K(F(T))=E[ ]\)

Note \(P_K(F(T))\) is derived by put-call parity:

\[\delta P_K(F(T)) = 1.0 - \delta C_K(F(T))\]

binary_call_delta(x, y=None, *, strike=None)

delta sensitivity of a binary call option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Delta_{ \delta C_K(F)} = \frac{d}{d F} \delta C_K(F)\)

\(\Delta_{ \delta C_K(F)}\) is the first derivative of \(\delta C_K(F)\) in underlying direction \(F\).

binary_put_delta(x, y=None, *, strike=None)

delta sensitivity of a binary put option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Delta_{ \delta P_K(F)} = \frac{d}{d F} \delta P_K(F)\)

\(\Delta_{ \delta P_K(F)}\) is the first derivative of \(P_K(F)\) in unterlying direction \(F\) and is derived by put-call parity, too:

\[\Gamma_{P_K(F)} = \Delta_{ \delta C_K(F)} - 1\]

Note, here \(1\) is actually scaled by yieldcurves.optioncurves.OptionPricingCurve.DELTA_SCALE.

binary_call_gamma(x, y=None, *, strike=None)

gamma sensitivity of a binary call option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Gamma_{ \delta C_K(F)} = \frac{d^2}{d F^2} \delta C_K(F)\)

\(\Gamma_{ \delta C_K(F)}\) is the second derivative of $ \delta C_K(F)$ in underlying direction \(F\).

binary_put_gamma(x, y=None, *, strike=None)

gamma sensitivity of a binary put option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Gamma_{ \delta P_K(F)} = \frac{d^2}{d F^2} \delta P_K(F)\)

\(\Gamma_{ \delta P_K(F)}\) is the second derivative of $ \delta P_K(F)$ in unterlying direction \(F\) and is derived by put-call parity, too:

\[\Gamma_{ \delta P_K(F)} = \Gamma_{ \delta C_K(F)}\]

binary_call_vega(x, y=None, *, strike=None)

vega sensitivity of a binary call option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\mathcal{V}_{ \delta C_K(F)} = \frac{d}{d v} \delta C_K(F)\)

\(\mathcal{V}_{ \delta C_K(F)}\) is the first derivative of $ \delta C_K(F)$ in volatility parameter direction \(v\).

binary_put_vega(x, y=None, *, strike=None)

vega sensitivity of a binary put option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\mathcal{V}_{ \delta P_K(F)} = \frac{d}{d v} \delta P_K(F)\)

\(\mathcal{V}_{ \delta P_K(F)}\) is the first derivative of \(\delta P_K(F)\) in volatility parameter direction \(v\) and is derived by put-call parity, too:

\[\mathcal{V}_{ \delta P_K(F)} = \mathcal{V}_{ \delta C_K(F)}\]

binary_call_theta(x, y=None, *, strike=None)

tau sensitivity of a binary call option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Theta_{ \delta C_K(F)} = \frac{d}{d t} \delta C_K(F)\)

\(\Theta_{ \delta C_K(F)}\) is the first derivative of \(\delta C_K(F)\) in tau parameter direction, i.e. valuation date \(t\).

binary_put_theta(x, y=None, *, strike=None)

tau sensitivity of a binary put option

Parameters:

• x – valuation date \(t\)

• y – expiry date \(T\)

• strike – option strike price \(K\) of underlying \(F\)

Returns:

\(\Theta_{ \delta P_K(F)} = \frac{d}{d t} \delta P_K(F)\)

\(\Theta_{ \delta P_K(F)}\) is the first derivative of \(\delta P_K(F)\) in tau parameter direction, i.e. valuation date \(t\).

Yield Curves with Dates

class yieldcurves.DateCurve(curve, *, origin=None, yf=None)

Bases: DateCurve

Curve class with date type arguments

Parameters:

• curve – inner curve with float arguments

• origin – curve start date (optional, default is yieldcurves.datecurves.DateCurve.BASEDATE)

• yf – year fraction callable yf(start: date, end: date) -> float to derive float argument y from a date x via y = yf(origin, x). (optional, default is actual/365.25)

>>> from datetime import date
>>> from yieldcurves import DateCurve

>>> eye = lambda x: x  # identity curve

>>> yc = DateCurve(eye, origin=date(2024,1,1))
>>> yc(date(2025,1,1))
1.002053388090349

>>> from businessdate import BusinessDate  # date extension for finance
>>> from businessdate.daycount import get_30_360  # handles date

>>> yc = DateCurve(eye, origin=date(2024,1,1), yf=get_30_360)
>>> yc(date(2025,1,1))
1.0
>>> yc(BusinessDate(20250101))  # BusinessDate behaves like date
1.0

>>> byc = DateCurve(eye, origin=BusinessDate(20240101), yf=get_30_360)
>>> byc(BusinessDate(20250101))
1.0

BASEDATE = None

default origin (if not None otherwise default origin will be current date)

year_fraction(x)

year fraction function

Parameters:

x – date argument

Returns:

float result

calculates year fraction y of period from origin and x as y = yf(origin, x) with yf as given.

origin defaults to yieldcurves.datecurves.DateCurve.BASEDATE or current date

yf defaults to default year fraction function which calculates the number of days between \(t_s\) and \(t_e\) expressed as a fraction of a year, i.e.

\[\tau(t_s, t_e) = \frac{t_e-t_s}{365.25}\]

as an average year has nearly \(365.25\) days.

Since different date packages have different concepts to derive the number of days between two dates, day_count tries to adopt at least some of them. As there are:

• dates given already as year fractions as a float so \(\tau(t_s, t_e) = t_e - t_s\).

• datetime the native Python package, so \(\delta = t_e - t_s\) is a timedelta object with attribute days which is used.

• businessdate a specialised package for banking business calendar and time period calculations, so the BusinessDate object start has a method start.diff_in_days which is used.

>>> from businessdate import BusinessRange, BusinessDate
>>> from businessdate.daycount import get_act_act
>>> from yieldcurves import DateCurve

>>> eye = lambda x: x  # identity curve

>>> today = BusinessDate(20240101)
>>> yc = DateCurve(eye, origin=today, yf=get_act_act)

>>> yc.year_fraction(today)
0.0

>>> yc.year_fraction(today + '1w')
0.01912568306010929

>>> yc.year_fraction(today + '1m')
0.08469945355191257

>>> yc.year_fraction(today + '3m')
0.24863387978142076

>>> yc.year_fraction(today + '1y')
1.0

inverse(y)

inverse function of year fraction function

Parameters:

y – float argument

Returns:

date result with y = yf(origin, x)

as year fraction functions are in general not injektiv, i.e. have unique relation between input and output s.th. there are dates a and b with

yf(origin, a) = yf(origin, b)

Hence, this method provides the smallest date x s.th. y = yf(origin, x).

Note, this method relies heavily on caching and caches also results of yieldcurves.datecurves.DateCurve.year_fraction() which might result in conflicts to the late minimal condition.

>>> from businessdate import BusinessDate
>>> from businessdate.daycount import get_30_360
>>> from yieldcurves import DateCurve

>>> eye = lambda x: x  # identity curve

>>> today = BusinessDate(20241231)
>>> yc = DateCurve(eye, origin=today, yf=get_30_360)
>>> yc.inverse(1.7)
BusinessDate(20260912)

>>> yc.inverse(0.25)
BusinessDate(20250331)

>>> yc.inverse(1.7)
BusinessDate(20260912)

>>> y = yc.year_fraction(BusinessDate(20250331))
>>> y
0.25

>>> yc.inverse(y)
BusinessDate(20250331)

>>> yc._cache[yc._cache_key] = {}  # this clears the cache
>>> y = yc.year_fraction(BusinessDate(20250101))
>>> y
0.002777777777777778

>>> yc.inverse(y)
BusinessDate(20250101)

classmethod from_interpolation(domain, curve, *, origin=None, yf=None, interpolation=None, curve_type=None, **kwargs)

Parameters:

• domain (list[date]) – curve date list

• curve (list[float]) – curve values or callable if callable then values of curve at points of domain are used

• origin (date) – curve start date (optional, default is yieldcurves.datecurves.DateCurve.BASEDATE)

• yf (Callable) – year fraction callable yf(start: date, end: date) -> float to derive float argument y from a date x via y = yf(origin, x). (optional, default is actual/365.25)

• interpolation – interpolation class to build interpolation(domain, curve) to give inner curve, i.e. turning domain and curve into a callable turning float into float. (optional, default is piecewise linear interpolation)

• curve_type ([str, type]) – type of curve (optional, default is yieldcurves.yieldcurves.YieldCurve)

• kwargs (dict) – additional arguments for curve type creation

Returns:

DateCurve with inner curve of curve_type

builds yieldcurves.datecurves.DateCurve with interpolated inner curve.

>>> from businessdate import BusinessDate, BusinessRange
>>> from curves.interpolation import linear
>>> from yieldcurves import DateCurve, YieldCurve

>>> today = BusinessDate(20240101)
>>> domain = BusinessRange(today, today + '6y', '1y')
>>> values = 0.02, 0.022, 0.021, 0.019, 0.02
>>> curve_type = YieldCurve.from_short_rates
>>> yc = DateCurve.from_interpolation(domain, values, origin=today, curve_type=curve_type)
>>> yc
DateCurve(YieldCurve.from_short_rates(piecewise_linear([0.0, 1.002053388090349, 2.001368925393566, 3.0006844626967832, 4.0], [0.02, 0.022, 0.021, 0.019, 0.02])), origin=BusinessDate(20240101))

>>> yc(today + '6m')
0.020497267759562843

>>> yc.spot(today + '6m')
0.020497267759562673

Fundamentals

Compounding

yieldcurves.compounding.simple_compounding(rate_value, maturity_value)

simple compounded discount factor

Parameters:

• rate_value – interest rate \(r\)

• maturity_value – loan maturity \(\tau\)

Returns:

\(\frac{1}{1+r\cdot \tau}\)

yieldcurves.compounding.simple_rate(df, period_fraction)

interest rate from simple compounded dicount factor

Parameters:

• df – discount factor \(df\)

• period_fraction – interest rate period \(\tau\)

Returns:

\(\frac{1}{df-1}\cdot \frac{1}{\tau}\)

yieldcurves.compounding.continuous_compounding(rate_value, maturity_value)

continuous compounded discount factor

Parameters:

• rate_value – interest rate \(r\)

• maturity_value – loan maturity \(\tau\)

Returns:

\(\exp(-r\cdot \tau)\)

yieldcurves.compounding.continuous_rate(df, period_fraction)

interest rate from continuous compounded dicount factor

Parameters:

• df – discount factor \(df\)

• period_fraction – interest rate period \(\tau\)

Returns:

\(-\log(df)\cdot \frac{1}{\tau}\)

yieldcurves.compounding.periodic_compounding(rate_value, maturity_value, frequency)

periodically compounded discount factor

Parameters:

• rate_value – interest rate \(r\)

• maturity_value – loan maturity \(\tau\)

• frequency – number of interest rate periods \(m\)

Returns:

\((1+\frac{r}{m})^{-\tau\cdot m}\)

yieldcurves.compounding.periodic_rate(df, period_fraction, frequency)

interest rate from continuous compounded discount factor

Parameters:

• df – discount factor \(df\)

• period_fraction – interest rate period \(\tau\)

• frequency – number of interest rate periods \(m\)

Returns:

\((df^{-\frac{1}{\tau\cdot m}}-1) \cdot m\)

yieldcurves.compounding.annually_compounding(rate_value, maturity_value)

annually compounded discount factor

Parameters:

• rate_value – interest rate \(r\)

• maturity_value – loan maturity \(\tau\)

Returns:

\((1+r)^{-\tau}\)

yieldcurves.compounding.semi_compounding(rate_value, maturity_value)

semi compounded discount factor

Parameters:

• rate_value – interest rate \(r\)

• maturity_value – loan maturity \(\tau\)

Returns:

\((1+\frac{r}{2})^{-\tau\cdot 2}\)

yieldcurves.compounding.quarterly_compounding(rate_value, maturity_value)

quarterly compounded discount factor

Parameters:

• rate_value – interest rate \(r\)

• maturity_value – loan maturity \(\tau\)

Returns:

\((1+\frac{r}{4})^{-\tau\cdot 4}\)

yieldcurves.compounding.monthly_compounding(rate_value, maturity_value)

monthly compounded discount factor

Parameters:

• rate_value – interest rate \(r\)

• maturity_value – loan maturity \(\tau\)

Returns:

\((1+\frac{r}{12})^{-\tau\cdot 12}\)

yieldcurves.compounding.daily_compounding(rate_value, maturity_value)

daily compounded discount factor

Parameters:

• rate_value – interest rate \(r\)

• maturity_value – loan maturity \(\tau\)

Returns:

\((1+\frac{r}{365})^{-\tau\cdot 365}\)

yieldcurves.compounding.compounding_factor(rate_value, maturity_value, frequency=None)

compounded discount factor

Parameters:

• rate_value – interest rate \(r\) per year

• maturity_value – maturity \(\tau\) in years

• frequency – number of interest rate periods per year as in yieldcurves.compounding.periodic_compounding() if frequency is None yieldcurves.compounding.continuous_compounding() is used and if period_value is 0 yieldcurves.compounding.simple_compounding() is used.

Returns:

yieldcurves.compounding.compounding_rate(df, period_fraction, frequency)

interest rate from compounded discount factor

Parameters:

• df – discount factor \(df\)

• period_fraction – interest rate period \(\tau\) in years

• frequency – number of interest rate periods \(m\) per year as in yieldcurves.compounding.periodic_rate() if frequency is None yieldcurves.compounding.continuous_rate() is used and if frequency is 0 yieldcurves.compounding.simple_rate() is used.

Option Pricing Formulas

class yieldcurves.optionpricing.OptionPricingFormula

Bases: object

abstract base class for option pricing formulas

A yieldcurves.optionpricing.OptionPricingFormula \(f\) serves as a kind of supply template to enhance yieldcurves.optioncurves.OptionPricingCurve by a new methodology.

To do so, \(f\) should at least implement a method __call__(time, strike, forward, volatility) to provide the expected payoff of an European call option.

These and all following method are only related to call options since put options will be derived by the use of put-call parity.

Moreover, the volatility argument should be understood as a general input of model parameters which ar in case of classical option pricing formulas like yieldcurves.optionpricing.Black76 the volatility.

To provide non-numerical derivatives implement

delta \(\Delta_f\), the first derivative along the underlying

gamma \(\Gamma_f\), the second derivative along the underlying

vega \(\mathcal{V}_f\), the first derivative along the volatility parameters

theta \(\Theta_f\), the first derivative along the time parameter time

Moreover, similar methods for binary options may be provided.

delta(time, strike, forward, volatility)

gamma(time, strike, forward, volatility)

vega(time, strike, forward, volatility)

theta(time, strike, forward, volatility)

binary(time, strike, forward, volatility)

binary_delta(time, strike, forward, volatility)

binary_gamma(time, strike, forward, volatility)

binary_vega(time, strike, forward, volatility)

binary_theta(time, strike, forward, volatility)

class yieldcurves.optionpricing.Intrinsic

Bases: OptionPricingFormula

intrisic option pricing formula

implemented for call options (see more on intrisic option values)

Let \(F\) be the current forward value. Let \(K\) be the option strike value, \(\tau\) the time to matruity, i.e. the option expitry date.

Then

• call price:

  \[\max(F-K, 0)\]

• call delta:

  \[0 \text{ if } F < K \text{ else } 1\]

• call gamma:

  \[0\]

• call vega:

  \[0\]

• binary call price:

  \[0 \text{ if } F < K \text{ else } 1\]

• binary call delta:

  \[0\]

• binary call gamma:

  \[0\]

• binary call vega:

  \[0\]

delta(time, strike, forward, volatility)

gamma(time, strike, forward, volatility)

vega(time, strike, forward, volatility)

theta(time, strike, forward, volatility)

binary(time, strike, forward, volatility)

binary_delta(time, strike, forward, volatility)

binary_gamma(time, strike, forward, volatility)

binary_vega(time, strike, forward, volatility)

binary_theta(time, strike, forward, volatility)

class yieldcurves.optionpricing.Bachelier

Bases: OptionPricingFormula

Bachelier option pricing formula

implemented for call options (see more on Bacheliers model)

Let \(f\) be a normaly distributed random variable with expectation \(F=E[f]\), the current forward value and \(\Phi\) the standard normal cummulative distribution function s.th. \(\phi=\Phi'\) is its density function.

Let \(K\) be the option strike value, \(\tau\) the time to matruity, i.e. the option expitry date, and \(\sigma\) the volatility parameter, i.e. the standard deviation of \(f\). Moreover, let

\[d = \frac{F-K}{\sigma \cdot \sqrt{\tau}}\]

Then

• call price:

  \[(F-K) \cdot \Phi(d) + \sigma \cdot \sqrt{\tau} \cdot \phi(d)\]

• call delta:

  \[\Phi(d)\]

• call gamma:

  \[\frac{\phi(d)}{\sigma \cdot \sqrt{\tau}}\]

• call vega:

  \[\sqrt{\tau} \cdot \phi(d)\]

• binary call price:

  \[\Phi(d)\]

• binary call delta:

  \[\frac{\phi(d)}{\sigma \cdot \sqrt{\tau}}\]

• binary call gamma:

  \[d \cdot \frac{\phi(d)}{\sigma^2 \cdot \tau}\]

• binary call vega:

  \[\sqrt{\tau} \cdot \phi(d)\]

delta(time, strike, forward, volatility)

gamma(time, strike, forward, volatility)

vega(time, strike, forward, volatility)

binary(time, strike, forward, volatility)

binary_delta(time, strike, forward, volatility)

binary_gamma(time, strike, forward, volatility)

binary_vega(time, strike, forward, volatility)

class yieldcurves.optionpricing.Black76

Bases: OptionPricingFormula

Black 76 option pricing formula

implemented for call options (see more on Black 76 model which is closly related to the Black-Scholes model)

Let \(f\) be a log-normaly distributed random variable with expectation \(F=E[f]\), the current forward value and \(\Phi\) the standard normal cummulative distribution function s.th. \(\phi=\Phi'\) is its density function.

Let \(K\) be the option strike value, \(\tau\) the time to maturity, i.e. the option expiry date, and \(\sigma\) the volatility parameter, i.e. the standard deviation of \(\log(f)\). Moreover, let

\[d =\frac{\log(F/K) + (\sigma^2 \cdot \tau)/2}{\sigma \cdot \sqrt{\tau}}\]

Then

• call price:

  \[F \cdot \Phi(d) - K \cdot \Phi(d-\sigma \cdot \sqrt{\tau})\]

• call delta:

  \[\Phi(d)\]

• call gamma:

  \[\frac{\phi(d)}{F \cdot \sigma \cdot \sqrt{\tau}}\]

• call vega:

  \[F \cdot \sqrt{\tau} \cdot \phi(d)\]

• binary call price:

  \[\Phi(d)\]

• binary call delta:

  \[\frac{\phi(d-\sigma \cdot \sqrt{\tau})}{\sigma \cdot \sqrt{\tau}}\]

• binary call gamma:

  \[d \cdot \frac{\phi(d)}{\sigma^2 \cdot \tau}\]

• binary call vega:

  \[(d/\sigma - \sqrt{\tau}) \cdot \phi(d)\]

delta(time, strike, forward, volatility)

gamma(time, strike, forward, volatility)

vega(time, strike, forward, volatility)

binary(time, strike, forward, volatility)

binary_delta(time, strike, forward, volatility)

binary_gamma(time, strike, forward, volatility)

binary_vega(time, strike, forward, volatility)

class yieldcurves.optionpricing.DisplacedBlack76(displacement=0.0)

Bases: OptionPricingFormula

displaced Black 76 option pricing formula

implemented for call options (see also yieldcurves.optionpricing.Black76)

The displaced Black 76 is adopted to handel moderate negative underlying forward prices or rates \(f\), e.g. as see for interest rates in the past. To do so, rather than \(f\) a shifted or displaced version \(f + \alpha\) is assumed to be log-normally distributed for some negative value of \(\alpha\).

Hence, let \(f + \alpha\) be a log-normally distributed random variable with expectation \(F + \alpha=E[f + \alpha]\), where \(F=E[f]\) is the current forward value and \(\Phi\) the standard normal cumulative distribution function s.th. \(\phi=\Phi'\) is its density function.

Uses yieldcurves.optionpricing.Black76 formulas with

• displaced forward \(F+\alpha\)

and

• displaced strike \(K+\alpha\)

Let \(K\) be the option strike value, \(\tau\) the time to maturity, i.e. the option expiry date, and \(\sigma\) the volatility parameter, i.e. the standard deviation of \(\log(f + \alpha)\). Moreover, let

\[d =\frac{\log((F+\alpha)/(K+\alpha)) + (\sigma^2 \cdot \tau)/2}{\sigma \cdot \sqrt{\tau}}\]

Then

• call price:

  \[(F+\alpha) \cdot \Phi(d) - (K+\alpha) \cdot \Phi(d-\sigma \cdot \sqrt{\tau})\]

• call delta:

  \[\Phi(d)\]

• call gamma:

  \[\frac{\phi(d)}{(F+\alpha) \cdot \sigma \cdot \sqrt{\tau}}\]

• call vega:

  \[(F+\alpha) \cdot \sqrt{\tau} \cdot \phi(d)\]

• binary call price:

• binary call delta:

• binary call gamma:

• binary call vega:

INNER = Black76()

delta(time, strike, forward, volatility)

gamma(time, strike, forward, volatility)

vega(time, strike, forward, volatility)

theta(time, strike, forward, volatility)

binary(time, strike, forward, volatility)

binary_delta(time, strike, forward, volatility)

binary_gamma(time, strike, forward, volatility)

binary_vega(time, strike, forward, volatility)

binary_theta(time, strike, forward, volatility)