FXCallPeriod#

class rateslib.periods.FXCallPeriod(*, delivery, pair, expiry, strike=NoInput.blank, notional=NoInput.blank, delta_type=NoInput.blank, metric=NoInput.blank, option_fixings=NoInput.blank, ex_dividend=NoInput.blank)#

Bases: _BaseFXOptionPeriod

A Period defined by a European FX call option.

The expected unindexed reference cashflow is given by,

\[\begin{split}\mathbb{E^Q}[\bar{C}_t] = \left \{ \begin{matrix} \max(f_d - K, 0) & \text{after expiry} \\ B76(f_d, K, t, \sigma) & \text{before expiry} \end{matrix} \right .\end{split}\]

where \(B76(.)\) is the Black-76 option pricing formula, using log-normal volatility calculations with calendar day time reference.

Examples

In [1]: fxo = FXCallPeriod(
   ...:     delivery=dt(2000, 3, 1),
   ...:     pair="eurusd",
   ...:     expiry=dt(2000, 2, 28),
   ...:     strike=1.10,
   ...:     delta_type="forward",
   ...: )
   ...: 

In [2]: fxo.cashflows()
Out[2]: 
{'Type': 'FXCallPeriod',
 'Ccy': 'USD',
 'Payment': datetime.datetime(2000, 3, 1, 0, 0),
 'Notional': 1000000.0,
 'DF': None,
 'Cashflow': None,
 'NPV': None,
 'FX Rate': 1.0,
 'Base Ccy': 'USD',
 'NPV Ccy': None,
 'Collateral': None}
Parameters:

  • . –

    Note

    The following define fx option and generalised settlement parameters.

  • delivery (datetime, required) – The settlement date of the underlying FX rate of the option. Also used as the implied payment date of the cashflow valuation date.

  • pair (str, required) – The currency pair of the FXFixing against which the option will settle.

  • expiry (datetime, required) – The expiry date of the option, when the option fixing is determined.

  • strike (float, Dual, Dual2, Variable, optional) – The strike price of the option. Can be set after initialisation.

  • notional (float, Dual, Dual2, Variable, optional (set by ‘defaults’)) – The notional of the option expressed in units of LHS currency of pair.

  • delta_type (FXDeltaMethod, str, optional (set by ‘default’)) – The definition of the delta for the option.

  • metric (FXDeltaMethod, str, optional (set by ‘default’)`) – The metric used by default in the rate() method.

  • option_fixings (float, Dual, Dual2, Variable, Series, str, optional) – The value of the option FXFixing. If a scalar, is used directly. If a string identifier, links to the central fixings object and data loader.

  • ex_dividend (datetime, optional (set as ‘delivery’)) –

    The ex-dividend date of the settled cashflow.

    Note

    This Period type has not implemented indexation or non-deliverability.

Attributes Summary

fx_option_params

The _FXOptionParams of the Period.

index_params

The _IndexParams of the Period, if any.

is_indexed

Check whether the Period has indexation applied, which means it has index_params.

is_non_deliverable

Check whether the Period is non-deliverable, which means it has non_deliverable_params.

non_deliverable_params

The _NonDeliverableParams of the Period., if any.

period_params

This Period type has no _PeriodParams.

rate_params

This Period type has no rate parameters.

settlement_params

The _SettlementParams of the Period.

Methods Summary

analytic_delta(*[, rate_curve, index_curve, ...])

Calculate the analytic rate delta of the Period converted to any other base accounting currency.

analytic_greeks(rate_curve, disc_curve, fx)

Return the different greeks for the FX Option.

cashflow(*[, rate_curve, disc_curve, ...])

Calculate the cashflow for the Period with settlement currency adjustment and indexation.

cashflows(*[, rate_curve, disc_curve, ...])

Return aggregated cashflow data for the Period.

convert_deliverable(value, fx)

Apply settlement currency conversion to a Static Period using its non_deliverable_params.

immediate_local_npv(*[, rate_curve, ...])

Calculate the NPV of the Period in local settlement currency.

implied_vol(rate_curve, disc_curve, fx, premium)

Calculate the implied volatility of the FX option.

index_up(value, index_curve)

Apply indexation to a Static Period value using its index_params.

local_analytic_rate_fixings(*[, rate_curve, ...])

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in local settlement currency of the Period.

local_fixings(identifiers[, scalars, ...])

Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.

local_npv(*[, rate_curve, index_curve, ...])

Calculate the NPV of the Period in local settlement currency.

npv(*[, rate_curve, index_curve, ...])

Calculate the NPV of the Period converted to any other base accounting currency.

rate(*, rate_curve, disc_curve[, fx, ...])

Return the pricing metric of the FXOption.

reference_cashflow(*[, rate_curve, ...])

Calculate the cashflow for the Static Period before settlement currency adjustment but after indexation.

reset_fixings([state])

Resets any fixings values of the Period derived using the given data state.

try_cashflow(*[, rate_curve, disc_curve, ...])

Replicate cashflow() with lazy exception handling.

try_cashflow_analytic_delta(*[, rate_curve, ...])

Calculate the cashflow for the Period with settlement currency adjustment and indexation.

try_cashflow_analytic_rate_fixings(*[, ...])

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in settlement currency of the Period, adjusted for indexation but unadjusted by timing of the cashflow.

try_convert_deliverable(value, fx)

Replicate convert_deliverable() with lazy exception handling.

try_immediate_analytic_rate_fixings([...])

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in local settlement currency of the Period with immediate value, with lazy error raising.

try_immediate_local_analytic_delta(*[, ...])

Calculate the immediate, analytic rate delta of a Period expressed in local settlement currency, with lazy error raising.

try_immediate_local_npv(*[, rate_curve, ...])

Replicate immediate_local_npv() with lazy exception handling.

try_index_up(value, index_curve)

Replicate index_up() with lazy exception handling.

try_local_analytic_delta(*[, rate_curve, ...])

Calculate the analytic rate delta of a Period expressed in local settlement currency, with lazy error raising.

try_local_npv(*[, rate_curve, index_curve, ...])

Replicate local_npv() with lazy exception handling.

try_rate(rate_curve, disc_curve[, fx, ...])

Return the pricing metric of the FXOption, with lazy error handling.

try_reference_cashflow(*[, rate_curve, ...])

Replicate reference_cashflow() with lazy exception handling.

try_reference_cashflow_analytic_delta(*[, ...])

Calculate the cashflow analytic delta for the Static Period before settlement currency adjustment but after indexation, with lazy error raising.

try_reference_cashflow_analytic_rate_fixings(*)

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in reference currency of the Period,adjusted for indexation but unadjusted by timing of the cashflow.

try_unindexed_cashflow(*[, rate_curve, ...])

Replicate unindexed_cashflow() with lazy exception handling.

try_unindexed_cashflow_analytic_delta(*[, ...])

Calculate the cashflow analytic delta for the Static Period with settlement currency adjustment but without indexation, with lazy error raising.

try_unindexed_cashflow_analytic_rate_fixings(*)

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in settlement currency of the Period, unadjusted by timing of the cashflow and indexation.

try_unindexed_reference_cashflow(*[, ...])

Replicate unindexed_reference_cashflow() with lazy exception handling.

try_unindexed_reference_cashflow_analytic_delta(*)

Calculate the cashflow analytic delta for the Static Period before settlement currency adjustment and indexation, with lazy error raising.

try_unindexed_reference_cashflow_analytic_rate_fixings(*)

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in reference currency of the Period, unadjusted by timing of the cashflow and by indexation.

unindexed_cashflow(*[, rate_curve, ...])

Calculate the cashflow for the Static Period with settlement currency adjustment but without indexation.

unindexed_reference_cashflow(*[, ...])

Calculate the cashflow for the Static Period before settlement currency and indexation adjustments.

Attributes Documentation

fx_option_params#

The _FXOptionParams of the Period.

index_params#

The _IndexParams of the Period, if any.

is_indexed#

Check whether the Period has indexation applied, which means it has index_params.

is_non_deliverable#

Check whether the Period is non-deliverable, which means it has non_deliverable_params.

non_deliverable_params#

The _NonDeliverableParams of the Period., if any.

period_params#

This Period type has no _PeriodParams.

rate_params#

This Period type has no rate parameters.

settlement_params#

The _SettlementParams of the Period.

Methods Documentation

analytic_delta(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, base=NoInput.blank, local=False, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the analytic rate delta of the Period converted to any other base accounting currency.

This method converts a local settlement currency value to a base accounting currency according to:

\[A^{bas}(m_s, m_f) = f_{loc:bas}(m_f) A(m_s, m_f)\]

Hint

If the cashflows are unspecified or incalculable due to missing information this method will raise an exception. For a function that returns a Result indicating success or failure use try_local_analytic_delta().

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

  • base (str, optional) – The currency to convert the local settlement NPV to.

  • local (bool, optional) – An override flag to return a dict of values indexed by string currency.

  • settlement (datetime, optional, (set as immediate date)) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional, (set as settlement)) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable or dict

analytic_greeks(rate_curve, disc_curve, fx, fx_vol=NoInput.blank, premium=NoInput.blank, premium_payment=NoInput.blank)#

Return the different greeks for the FX Option.

Parameters:

  • rate_curve (_BaseCurve) – The discount Curve for the LHS currency of pair.

  • disc_curve (_BaseCurve) – The discount Curve for the RHS currency of pair.

  • fx (FXForwards, optional) – The FXForward object used for forecasting the fx_fixing for deliverable cashflows, if necessary.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

  • premium (float, Dual, Dual2, optional) – The premium value of the option paid at the appropriate payment date. Premium should be expressed in domestic currency. If not given calculates and assumes a mid-market premium.

  • premium_payment (datetime, optional) – The date that the premium is paid. If not given is assumed to be equal to the payment associated with the option period settlement_params.

Return type:

dict

Notes

Delta \(\Delta\)

This is the percentage value of the domestic notional in either the forward or spot FX rate. The choice of which is defined by the option’s delta_type.

Delta is also expressed in nominal domestic currency amount.

Gamma \(\Gamma\)

This defines by how much delta will change for a 1.0 increase in either the forward or spot FX rate. Which rate is determined by the option’s delta_type.

Gamma is also expressed in nominal domestic currency amount for a +1% change in FX rates.

Vanna \(\Delta_{\nu}\)

This defines by how much delta will change for a 1.0 increase (i.e. 100 log-vols) in volatility. The additional

Vega \(\nu\)

This defines by how much the PnL of the option will change for a 1.0 increase in volatility for a nominal of 1 unit of domestic currency.

Vega is also expressed in foreign currency for a 0.01 (i.e. 1 log-vol) move higher in vol.

Vomma (Volga) \(\nu_{\nu}\)

This defines by how much vega will change for a 1.0 increase in volatility.

These values can be used to estimate PnL for a change in the forward or spot FX rate and the volatility according to,

\[\delta P \approx v_{deli} N^{dom} \left ( \Delta \delta f + \frac{1}{2} \Gamma \delta f^2 + \Delta_{\nu} \delta f \delta \sigma \right ) + N^{dom} \left ( \nu \delta \sigma + \frac{1}{2} \nu_{\nu} \delta \sigma^2 \right )\]

where \(v_{deli}\) is the date of FX settlement for forward or spot rate.

Kappa \(\kappa\)

This defines by how much the PnL of the option will change for a 1.0 increase in strike for a nominal of 1 unit of domestic currency.

Kega \(\left . \frac{dK}{d\sigma} \right|_{\Delta}\)

This defines the rate of change of strike with respect to volatility for a constant delta.

Raises:

ValueError – if the strike is not set on the Option.:

cashflow(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Calculate the cashflow for the Period with settlement currency adjustment and indexation.

\[I_r f(m_d)\mathbb{E^Q}[\bar{C}_t]\]
Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows, if necessary.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

float, Dual, Dual2, Variable

cashflows(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Return aggregated cashflow data for the Period.

Warning

This method is a convenience method to provide a visual representation of all associated calculation data. Calling this method to extracting certain values should be avoided. It is more efficient to source relevant parameters or calculations from object attributes or other methods directly.

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

  • base (str, optional) – The currency to convert the local settlement NPV to.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

dict of values

convert_deliverable(value, fx)#

Apply settlement currency conversion to a Static Period using its non_deliverable_params.

Parameters:

  • value (float, Dual, Dual2, Variable) – The possible value to apply settlement currency conversion to.

  • fx (FXForwards, optional) – The object used to forecast forward FX rates, if necessary.

Return type:

float, Dual, Dual2, Variable

immediate_local_npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Calculate the NPV of the Period in local settlement currency.

This method does not adjust for ex-dividend and is an immediate measure according to,

\[P_0 = v(m_t) I_r f(m_d) \mathbb{E^Q} [\bar{C}_t]\]

for non-deliverable delivery, \(m_d\), and index ratio, \(I_r\).

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an class:~rateslib.fx.FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

float, Dual, Dual2, Variable

implied_vol(rate_curve, disc_curve, fx, premium, metric=NoInput.blank)#

Calculate the implied volatility of the FX option.

Parameters:

  • rate_curve (Curve) – Not used by implied_vol.

  • disc_curve (Curve) – The discount Curve for the RHS currency.

  • fx (FXForwards) – The object to project the currency pair FX rate at delivery.

  • premium (float, Dual, Dual2) – The premium value of the option paid at the appropriate payment date. Expressed either in ‘pips’ or ‘percent’ of notional. Must align with metric.

  • metric (str in {"pips", "percent"}, optional) – The manner in which the premium is expressed.

Return type:

float, Dual or Dual2

index_up(value, index_curve)#

Apply indexation to a Static Period value using its index_params.

Parameters:

  • value (float, Dual, Dual2, Variable) – The possible value to apply indexation to.

  • index_curve (_BaseCurve, optional) – The index curve used to forecast index values, if necessary.

Return type:

float, Dual, Dual2, Variable

local_analytic_rate_fixings(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in local settlement currency of the Period.

If the Period has no sensitivity to rates fixings this DataFrame is empty.

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

local_fixings(identifiers, scalars=NoInput.blank, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.

Parameters:

  • indentifiers (Sequence of tuple[str, Series], required) – These are the series string identifiers and the data values that will be used in each Series to determine the sensitivity against.

  • scalars (Sequence of floats, optional (each set as 1.0)) – A sequence of scalars to multiply the sensitivities by for each on of the identifiers.

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an class:~rateslib.fx.FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

  • settlement (datetime, optional (set as immediate date)) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional (set as settlement)) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

local_npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the NPV of the Period in local settlement currency.

This method adjusts the immediate NPV for ex-dividend, settlement and forward projected value, according to,

\[\begin{split}P(m_s, m_f) = \mathbb{I}(m_s) \frac{1}{v(m_f)} P_0, \qquad \; \mathbb{I}(m_s) = \left \{ \begin{matrix} 0 & m_s > m_{ex} \\ 1 & m_s \leq m_{ex} \end{matrix} \right .\end{split}\]

for forward, \(m_f\), settlement, \(m_s\), and ex-dividend, \(m_{ex}\).

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an class:~rateslib.fx.FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

  • settlement (datetime, optional (set as immediate date)) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional (set as settlement)) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable

npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, base=NoInput.blank, local=False, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the NPV of the Period converted to any other base accounting currency.

This method converts a local settlement currency value to a base accounting currency according to:

\[P^{bas}(m_s, m_f) = f_{loc:bas}(m_f) P(m_s, m_f)\]

Hint

If the cashflows are unspecified or incalculable due to missing information this method will raise an exception. For a function that returns a Result indicating success or failure use try_local_npv().

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

  • base (str, optional) – The currency to convert the local settlement NPV to.

  • local (bool, optional) – An override flag to return a dict of NPV values indexed by string currency.

  • settlement (datetime, optional, (set as immediate date)) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional, (set as settlement)) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable or dict of such indexed by string currency.

Notes

If base is not provided then this function will return the value obtained from local_npv().

If base is provided this then an FXForwards object may be required to perform conversions. An FXRates object is also allowed for this conversion although best practice does not recommend it due to possible settlement date conflicts.

rate(*, rate_curve, disc_curve, fx=NoInput.blank, fx_vol=NoInput.blank, metric=NoInput.blank, forward=NoInput.blank)#

Return the pricing metric of the FXOption.

This is priced according to the payment date of the OptionPeriod.

Parameters:

  • rate_curve (Curve) – The discount Curve for the LHS currency. (Not used).

  • disc_curve (Curve) – The discount Curve for the RHS currency.

  • fx (float, FXRates, FXForwards, optional) – The object to project the currency pair FX rate at delivery.

  • base (str, optional) – Not used by rate.

  • fx_vol (float, Dual, Dual2) – The percentage log-normal volatility to price the option.

  • metric (str in {"pips", "percent"}) – The metric to return. If “pips” assumes the premium is in foreign (rhs) currency. If “percent”, the premium is assumed to be domestic (lhs).

  • forward (datetime, optional (set as payment date of option)) – The date to project the cashflow value to using the disc_curve if RHS (“pips”) or using rate_curve if LHS (“percent”).

Return type:

float, Dual, Dual2 or dict of such.

reference_cashflow(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Calculate the cashflow for the Static Period before settlement currency adjustment but after indexation.

\[I_r\mathbb{E^Q}[\bar{C}_t]\]
Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows, if necessary.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

float, Dual, Dual2, Variable

reset_fixings(state=NoInput.blank)#

Resets any fixings values of the Period derived using the given data state.

Examples

In [3]: fp = FloatPeriod(
   ...:     start=dt(2026, 1, 12),
   ...:     end=dt(2026, 1, 16),
   ...:     payment=dt(2026, 1, 16),
   ...:     frequency="M",
   ...:     fixing_method="rfr_payment_delay",
   ...:     method_param=0,
   ...:     rate_fixings="sofr"
   ...: )
   ...: 

In [4]: fixings.add(
   ...:     name="sofr_1B",
   ...:     series=Series(
   ...:         index=[dt(2026, 1, 12), dt(2026, 1, 13), dt(2026, 1, 14), dt(2026, 1, 15)],
   ...:         data=[3.1, 3.2, 3.3, 3.4]
   ...:     )
   ...: )
   ...: 

# value is populated from given data
In [5]: assert 3.245 < fp.rate_params.rate_fixing.value < 3.255

In [6]: fp.reset_fixings()

# private data related to fixing is removed and requires new data lookup
In [7]: fp.rate_params.rate_fixing._value
Out[7]: <NoInput.blank: 0>

In [8]: fp.rate_params.rate_fixing._populated
Out[8]: Series([], dtype: float64)
Parameters:

state (int, optional) – The state id of the data series that set the fixing. Only fixings determined by this data will be reset. If not given resets all fixings.

try_cashflow(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Replicate cashflow() with lazy exception handling.

Return type:

Result[float, Dual, Dual2, Variable]

try_cashflow_analytic_delta(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Calculate the cashflow for the Period with settlement currency adjustment and indexation.

\[I_r f(m_d) \frac{\partial \mathbb{E^Q}[\bar{C}_t]}{\partial \xi}\]
Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

Result[float, Dual, Dual2, Variable]

try_cashflow_analytic_rate_fixings(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in settlement currency of the Period, adjusted for indexation but unadjusted by timing of the cashflow.

If the Period has no sensitivity to rates fixings this DataFrame is empty.

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

Result[DataFrame]

try_convert_deliverable(value, fx)#

Replicate convert_deliverable() with lazy exception handling.

Parameters:

  • value (Result[float, Dual, Dual2, Variable]) – The possible value to apply settlement currency conversion to.

  • fx (FXForwards, optional) – The object used to forecast forward FX rates, if necessary.

Return type:

Result[float, Dual, Dual2, Variable]

try_immediate_analytic_rate_fixings(rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in local settlement currency of the Period with immediate value, with lazy error raising.

If the Period has no sensitivity to rates fixings this DataFrame is empty.

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

Result[DataFrame]

try_immediate_local_analytic_delta(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Calculate the immediate, analytic rate delta of a Period expressed in local settlement currency, with lazy error raising.

This method does not adjust for ex-dividend and is an immediate measure according to,

\[A_0 = \frac{\partial P_0}{\partial \xi}, \quad \text{for some, } \xi\]
Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForward object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an class:~rateslib.fx.FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

Result[float, Dual, Dual2, Variable]

try_immediate_local_npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Replicate immediate_local_npv() with lazy exception handling.

Return type:

Result[float, Dual, Dual2, Variable]

try_index_up(value, index_curve)#

Replicate index_up() with lazy exception handling.

Parameters:

  • value (Result[float, Dual, Dual2, Variable]) – The possible value to apply indexation to.

  • index_curve (_BaseCurve, optional) – The index curve used to forecast index values, if necessary.

Return type:

Result[float, Dual, Dual2, Variable]

try_local_analytic_delta(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the analytic rate delta of a Period expressed in local settlement currency, with lazy error raising.

This method adjusts the immediate NPV for ex-dividend and forward projected value, according to,

\[\begin{split}A(m_s, m_f) = \mathbb{I}(m_s) \frac{1}{v(m_f)} A_0, \qquad \; \mathbb{I}(m_s) = \left \{ \begin{matrix} 0 & m_s > m_{ex} \\ 1 & m_s \leq m_{ex} \end{matrix} \right .\end{split}\]

for forward, \(m_f\), settlement, \(m_s\), and ex-dividend, \(m_{ex}\).

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForward object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an class:~rateslib.fx.FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

Result[float, Dual, Dual2, Variable]

try_local_npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Replicate local_npv() with lazy exception handling.

Return type:

Result[float, Dual, Dual2, Variable]

try_rate(rate_curve, disc_curve, fx=NoInput.blank, fx_vol=NoInput.blank, metric=NoInput.blank, forward=NoInput.blank)#

Return the pricing metric of the FXOption, with lazy error handling.

See rate().

try_reference_cashflow(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Replicate reference_cashflow() with lazy exception handling.

Return type:

Result[float, Dual, Dual2, Variable]

try_reference_cashflow_analytic_delta(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank)#

Calculate the cashflow analytic delta for the Static Period before settlement currency adjustment but after indexation, with lazy error raising.

\[I_r \frac{\partial \mathbb{E^Q}[\bar{C}_t]}{\partial \xi}\]
Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

Return type:

Result[float, Dual, Dual2, Variable]

try_reference_cashflow_analytic_rate_fixings(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in reference currency of the Period,adjusted for indexation but unadjusted by timing of the cashflow.

If the Period has no sensitivity to rates fixings this DataFrame is empty.

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

Result[DataFrame]

try_unindexed_cashflow(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Replicate unindexed_cashflow() with lazy exception handling.

Return type:

Result[float, Dual, Dual2, Variable]

try_unindexed_cashflow_analytic_delta(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank)#

Calculate the cashflow analytic delta for the Static Period with settlement currency adjustment but without indexation, with lazy error raising.

\[f(m_d) \frac{\partial \mathbb{E^Q}[\bar{C}_t]}{\partial \xi}\]
Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

Return type:

Result[float, Dual, Dual2, Variable]

try_unindexed_cashflow_analytic_rate_fixings(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in settlement currency of the Period, unadjusted by timing of the cashflow and indexation.

If the Period has no sensitivity to rates fixings this DataFrame is empty.

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

Result[DataFrame]

try_unindexed_reference_cashflow(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Replicate unindexed_reference_cashflow() with lazy exception handling.

Return type:

Result[float, Dual, Dual2, Variable]

try_unindexed_reference_cashflow_analytic_delta(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank)#

Calculate the cashflow analytic delta for the Static Period before settlement currency adjustment and indexation, with lazy error raising.

\[\frac{\partial \mathbb{E^Q}[\bar{C}_t]}{\partial \xi}\]
Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

Return type:

Result[float, Dual, Dual2, Variable]

try_unindexed_reference_cashflow_analytic_rate_fixings(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in reference currency of the Period, unadjusted by timing of the cashflow and by indexation.

If the Period has no sensitivity to rates fixings this DataFrame is empty.

Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

Result[DataFrame]

unindexed_cashflow(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Calculate the cashflow for the Static Period with settlement currency adjustment but without indexation.

\[f(m_d)\mathbb{E^Q}[\bar{C}_t]\]
Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows, if necessary.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

float, Dual, Dual2, Variable

unindexed_reference_cashflow(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, **kwargs)#

Calculate the cashflow for the Static Period before settlement currency and indexation adjustments.

\[\mathbb{E^Q}[\bar{C}_t]\]
Parameters:

  • rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.

  • index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.

  • disc_curve (_BaseCurve, optional) – Used to discount cashflows, if necessary.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.

  • fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

float, Dual, Dual2, Variable

On this page

This Page