FXStraddle#
- class rateslib.instruments.FXStraddle(expiry, strike, pair=NoInput.blank, *, notional=NoInput.blank, eval_date=NoInput.blank, calendar=NoInput.blank, modifier=NoInput.blank, eom=NoInput.blank, delivery_lag=NoInput.blank, premium=(NoInput.blank, NoInput.blank), premium_ccy=NoInput.blank, payment_lag=NoInput.blank, option_fixings=NoInput.blank, delta_type=NoInput.blank, metric=NoInput.blank, curves=NoInput.blank, vol=NoInput.blank, spec=NoInput.blank)#
Bases:
_BaseFXOptionStratAn FX Straddle
_BaseFXOptionStrat.A Straddle is composed of a
FXPutandFXCallwith the same strike.Examples
In [1]: fxs = FXStraddle( ...: expiry="3m", ...: strike=1.10, # <- "atm_delta" is also a common input ...: eval_date=dt(2020, 1, 1), ...: spec="eurusd_call", ...: notional=1000000, ...: ) ...: In [2]: fxs.cashflows() Out[2]: Type Ccy Payment Notional DF Cashflow NPV FX Rate Base Ccy NPV Ccy Collateral inst0 leg1 0 FXPutPeriod USD 2020-04-03 1000000.0 None NaN None 1.0 USD None None leg2 0 Cashflow USD 2020-04-03 0.0 None -0.0 None 1.0 USD None None inst1 leg1 0 FXCallPeriod USD 2020-04-03 1000000.0 None NaN None 1.0 USD None None leg2 0 Cashflow USD 2020-04-03 0.0 None -0.0 None 1.0 USD None None
Pricing
The pricing mirrors that for an
FXCall. All options use the samecurves. Allowable inputs are:curves = [rate_curve, disc_curve] # two curves are applied in the given order curves = {"rate_curve": rate_curve, "disc_curve": disc_curve} # dict form is explicit
Any FXOption also requires an
FXForwardsas input to thefxargument.A
volargument must be provided to each Instrument. This can either be a single value universally used for all, or an individual item as part of a sequence. Allowed inputs are:vol = 12.0 | vol_obj # a single item universally applied vol = [12.0, 12.0] # values for the Put and Call respectively
The following pricing
metricare available, with examples:In [3]: eur = Curve({dt(2020, 1, 1): 1.0, dt(2021, 1, 1): 0.98}) In [4]: usd = Curve({dt(2020, 1, 1): 1.0, dt(2021, 1, 1): 0.96}) In [5]: fxf = FXForwards( ...: fx_rates=FXRates({"eurusd": 1.10}, settlement=dt(2020, 1, 3)), ...: fx_curves={"eureur": eur, "eurusd": eur, "usdusd": usd}, ...: ) ...: In [6]: fxvs = FXDeltaVolSmile( ...: nodes={0.25: 11.0, 0.5: 9.8, 0.75: 10.7}, ...: expiry=dt(2020, 4, 1), ...: eval_date=dt(2020, 1, 1), ...: delta_type="forward", ...: ) ...:
‘vol’: the implied volatility value of the straddle from a volatility object. ‘single_vol’ is also an alias for this, since both options assume the same volatility.
In [7]: fxs.rate(vol=fxvs, curves=[eur, usd], fx=fxf, metric="vol") Out[7]: <Dual: 9.881643, (fx_eurusd), [18.5]>
‘premium’: the summed cash premium amount, of both options, applicable to the ‘payment’ date.
In [8]: fxs.rate(vol=fxvs, curves=[eur, usd], fx=fxf, metric="premium") Out[8]: <Dual: 43645.775769, (fx_eurusd), [183607.4]> In [9]: fxs.instruments[0].rate(vol=fxvs, curves=[eur, usd], fx=fxf, metric="premium") Out[9]: <Dual: 18995.988452, (fx_eurusd), [-410766.2]> In [10]: fxs.instruments[1].rate(vol=fxvs, curves=[eur, usd], fx=fxf, metric="premium") Out[10]: <Dual: 24649.787316, (fx_eurusd), [594373.6]>
‘pips_or_%’: if the premium currency is LHS of
pairthis is a % of notional, whilst if the premium currency is RHS this gives a number of pips of the FX rate. Summed over both options.In [11]: fxs.rate(vol=fxvs, curves=[eur, usd], fx=fxf, metric="pips_or_%") Out[11]: <Dual: 436.457758, (fx_eurusd), [1836.1]> In [12]: fxs.instruments[0].rate(vol=fxvs, curves=[eur, usd], fx=fxf, metric="pips_or_%") Out[12]: <Dual: 189.959885, (fx_eurusd), [-4107.7]> In [13]: fxs.instruments[1].rate(vol=fxvs, curves=[eur, usd], fx=fxf, metric="pips_or_%") Out[13]: <Dual: 246.497873, (fx_eurusd), [5943.7]>
- Parameters:
. –
Note
The following define fx option and generalised settlement parameters.
expiry (datetime, str, required) – The expiry of the option. If given in string tenor format, e.g. “1M” requires an
eval_date. See Notes.strike (float, Variable, str, required) – The strike of the put and the call.
pair (str, required) – The currency pair for the FX rate which settles the option, in 3-digit codes, e.g. “eurusd”. May be included as part of
spec.notional (float, optional (set by ‘defaults’)) – The notional amount of each option expressed in units of LHS of
pair.eval_date (datetime, optional) – Only required if
expiryis given as string tenor. Should be entered as today (also called horizon) and not spot. Spot is derived fromdelivery_lagandcalendar.modifier (str, optional (set by ‘defaults’)) – The modification rule, in {“F”, “MF”, “P”, “MP”} for date evaluation.
eom (bool, optional (set by ‘defaults’)) – Whether to use end-of-month rolls when expiry is given as a month or year tenor.
calendar (calendar or str, optional) – The holiday calendar object to use. If str, looks up named calendar from static data.
delivery_lag (int, optional (set by ‘defaults’)) – The number of business days after expiry that the physical settlement of the FX exchange occurs.
payment_lag (int or datetime, optional (set by ‘defaults’)) – The number of business days after expiry to pay premium. If a datetime is given this will set the premium date explicitly.
premium_ccy (str, optional (set as RHS of ‘pair’)) – The currency in which the premium is paid. Can only be one of the two currencies in pair.
delta_type (FXDeltaMethod, str, optional (set by ‘defaults’)) –
When deriving strike from delta use the equation associated with ‘spot’ or ‘forward’ delta. If premium currency is LHS of
pairthen this will produce premium adjusted delta values. If the premium_ccy is RHS ofpairthen delta values are unadjusted.Note
The following define additional rate parameters.
premium (2-tuple of float, optional) – The amount paid for the put and call in order. If not given assumes unpriced Options and sets this as mid-market premium during pricing.
option_fixings (2-tuple of float, Dual, Dual2, Variable, Series, str, optional) –
The value of each option’s
FXFixing. If a scalar, is used directly. If a string identifier, links to the centralfixingsobject and data loader.Note
The following are meta parameters.
metric (str, optional (set as “pips_or_%”)) – The pricing metric returned by the
ratemethod. See Pricing.curves (_BaseCurve, str, dict, _Curves, Sequence, optional) – Pricing objects passed directly to the Instrument’s methods’
curvesargument. See Pricing.vol (str, Smile, Surface, float, Dual, Dual2, Variable, Sequence) – Pricing objects passed directly to the Instrument’s methods’
volargument. See Pricing.spec (str, optional) – An identifier to pre-populate many field with conventional values. See here for more info and available values.
Attributes Summary
The
_KWArgsof the Instrument.The
CustomLegof the Instrument containing theFXOptionPeriod.The
CustomLegof the Instrument containing the premiumCashflow.A list of the Legs of the Instrument.
A scaling quantity associated with the
Solverrisk calculations.The default
_SettlementParamsof the Instrument.Methods Summary
analytic_delta(*args[, leg])Not implemented for Option types.
analytic_greeks([curves, solver, fx, vol])Return various pricing metrics of the FX Option.
cashflows(*[, curves, solver, fx, vol, ...])Return aggregated cashflow data for the Instrument.
cashflows_table(*[, curves, solver, fx, ...])Aggregate the values derived from a
cashflows(), grouped by date, settlement currency and collateral.delta(*[, curves, solver, fx, vol, base, ...])Calculate delta risk of an Instrument against the calibrating instruments in a
Solver.exo_delta(*[, curves, solver, fx, vol, ...])Calculate delta risk of an Instrument against some exogenous user created Variables, via a
Solver.gamma(*[, curves, solver, fx, vol, base, ...])Calculate cross-gamma risk of an Instrument against the calibrating instruments of a
Solver.local_analytic_rate_fixings(*[, curves, ...])Calculate the sensitivity to rate fixings of the Instrument, expressed in local settlement currency per basis point.
local_fixings(identifiers[, scalars, ...])Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.
npv(*[, curves, solver, fx, vol, base, ...])Calculate the NPV of the Instrument converted to any other base accounting currency.
plot_payoff([range, curves, solver, fx, ...])Return a plot of the payoff at expiry, indexed by the FXFixing value.
rate(*[, curves, solver, fx, vol, base, ...])Calculate some pricing rate metric for the Instrument.
reset_fixings([state])Resets any fixings values of the Instrument derived using the given data state.
spread(*[, curves, solver, fx, vol, base, ...])Not implemented for Option types.
Attributes Documentation
- instruments#
- legs#
A list of the Legs of the Instrument.
- settlement_params#
The default
_SettlementParamsof the Instrument.This is used to define a
basecurrency when one is not specified.
Methods Documentation
- analytic_delta(*args, leg=1, **kwargs)#
Not implemented for Option types. Use
analytic_greeks().
- analytic_greeks(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank)#
Return various pricing metrics of the FX Option.
Examples
In [14]: eur = Curve({dt(2020, 1, 1): 1.0, dt(2021, 1, 1): 0.98}) In [15]: usd = Curve({dt(2020, 1, 1): 1.0, dt(2021, 1, 1): 0.96}) In [16]: fxf = FXForwards( ....: fx_rates=FXRates({"eurusd": 1.10}, settlement=dt(2020, 1, 3)), ....: fx_curves={"eureur": eur, "eurusd": eur, "usdusd": usd}, ....: ) ....: In [17]: fxvs = FXDeltaVolSmile( ....: nodes={0.25: 11.0, 0.5: 9.8, 0.75: 10.7}, ....: delta_type="forward", ....: eval_date=dt(2020, 1, 1), ....: expiry=dt(2020, 4, 1) ....: ) ....: In [18]: fxc = FXCall( ....: expiry="3m", ....: strike=1.10, ....: eval_date=dt(2020, 1, 1), ....: spec="eurusd_call", ....: ) ....: In [19]: fxc.analytic_greeks(fx=fxf, curves=[eur, usd], vol=fxvs) Out[19]: {'gamma': <Dual: 7.253419, (fx_eurusd), [-37.2]>, 'vega': <Dual: 0.216177, (fx_eurusd), [-0.3]>, '_kega': <Dual: -0.043519, (fx_eurusd), [-10.0]>, '_kappa': <Dual: -0.526091, (fx_eurusd), [-7.2]>, '_delta_index': <Dual: 0.448847, (fx_eurusd), [-7.2]>, '__delta_type': <FXDeltaMethod.Spot: 1>, '__vol': <Dual: 0.098816, (fx_eurusd), [0.2]>, '__strike': 1.1, '__forward': <Dual: 1.105654, (fx_eurusd), [1.0]>, '__sqrt_t': 0.49931459871823364, '__bs76': <Dual: 0.024395, (fx_eurusd), [0.6]>, '__notional': 1000000.0, '__class': 'FXCallPeriod', 'delta': <Dual: 0.548391, (fx_eurusd), [7.2]>, 'delta_eur': <Dual: 548391.021065, (fx_eurusd), [7195052.9]>, 'gamma_eur_1%': <Dual: 79787.606331, (fx_eurusd), [-336787.9]>, 'vega_usd': <Dual: 2161.767238, (fx_eurusd), [-3114.7]>, 'delta_sticky': <Dual: 0.588371, (fx_eurusd), [10.9]>, 'vomma': <Dual: 0.022286, (fx_eurusd), [8.2]>, 'vanna': <Dual: -0.315659, (fx_eurusd), [-71.1]>}
- Parameters:
curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A
Solverobject containing Curve, Smile, Surface, or Cube mappings for pricing.fx (FXForwards, optional) – The
FXForwardsobject used for forecasting FX rates, if necessary.vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
- Return type:
dict
- cashflows(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#
Return aggregated cashflow data for the Instrument.
Warning
This method is a convenience method to provide a visual representation of all associated calculation data. Calling this method to extract certain values should be avoided. It is more efficient to source relevant parameters or calculations from object attributes or other methods directly.
Examples
In [20]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=1.0) In [21]: irs.cashflows() Out[21]: Type Ccy Payment Notional Period Convention DCF Acc Start Acc End DF Cashflow NPV FX Rate Base Ccy NPV Ccy Collateral Rate Spread leg1 0 FixedPeriod USD 2001-01-04 1000000.0 Regular Act360 1.013889 2000-01-03 2001-01-02 None -10138.888889 None 1.0 USD None None 1.0 NaN 1 FixedPeriod USD 2002-01-04 1000000.0 Regular Act360 1.013889 2001-01-02 2002-01-02 None -10138.888889 None 1.0 USD None None 1.0 NaN 2 FixedPeriod USD 2003-01-06 1000000.0 Regular Act360 1.013889 2002-01-02 2003-01-02 None -10138.888889 None 1.0 USD None None 1.0 NaN leg2 0 FloatPeriod USD 2001-01-04 -1000000.0 Regular Act360 1.013889 2000-01-03 2001-01-02 None NaN None 1.0 USD None None NaN 0.0 1 FloatPeriod USD 2002-01-04 -1000000.0 Regular Act360 1.013889 2001-01-02 2002-01-02 None NaN None 1.0 USD None None NaN 0.0 2 FloatPeriod USD 2003-01-06 -1000000.0 Regular Act360 1.013889 2002-01-02 2003-01-02 None NaN None 1.0 USD None None NaN 0.0
Providing relevant pricing objects will ensure all data that can be calculated is returned.
In [22]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75}) In [23]: irs.cashflows(curves=[curve]) Out[23]: Type Ccy Payment Notional Period Convention DCF Acc Start Acc End DF Cashflow NPV FX Rate Base Ccy NPV Ccy Collateral Rate Spread leg1 0 FixedPeriod USD 2001-01-04 1000000.0 Regular Act360 1.013889 2000-01-03 2001-01-02 0.971359 -10138.888889 -9848.496702 1.0 USD -9848.496702 None 1.000000 NaN 1 FixedPeriod USD 2002-01-04 1000000.0 Regular Act360 1.013889 2001-01-02 2002-01-02 0.943835 -10138.888889 -9569.435745 1.0 USD -9569.435745 None 1.000000 NaN 2 FixedPeriod USD 2003-01-06 1000000.0 Regular Act360 1.013889 2002-01-02 2003-01-02 0.916946 -10138.888889 -9296.817681 1.0 USD -9296.817681 None 1.000000 NaN leg2 0 FloatPeriod USD 2001-01-04 -1000000.0 Regular Act360 1.013889 2000-01-03 2001-01-02 0.971359 29161.694029 28326.461668 1.0 USD 28326.461668 None 2.876222 0.0 1 FloatPeriod USD 2002-01-04 -1000000.0 Regular Act360 1.013889 2001-01-02 2002-01-02 0.943835 29161.694029 27523.820438 1.0 USD 27523.820438 None 2.876222 0.0 2 FloatPeriod USD 2003-01-06 -1000000.0 Regular Act360 1.013889 2002-01-02 2003-01-02 0.916946 29161.694029 26739.710399 1.0 USD 26739.710399 None 2.876222 0.0
- Parameters:
curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A
Solverobject containing Curve, Smile, Surface, or Cube mappings for pricing.fx (FXForwards, optional) – The
FXForwardsobject used for forecasting FX rates, if necessary.vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – 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:
DataFrame
- cashflows_table(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#
Aggregate the values derived from a
cashflows(), grouped by date, settlement currency and collateral.Examples
In [24]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=1.0) In [25]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75}) In [26]: irs.cashflows_table(curves=[curve]) Out[26]: local_ccy USD collateral_ccy NaN payment 2001-01-04 19022.80514 2002-01-04 19022.80514 2003-01-06 19022.80514
- Parameters:
curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A
Solverobject containing Curve, Smile, Surface, or Cube mappings for pricing.fx (FXForwards, optional) – The
FXForwardsobject used for forecasting FX rates, if necessary.vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.
local (bool, optional (set as False)) – An override flag to return a dict of NPV values indexed by string currency.
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
- delta(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#
Calculate delta risk of an Instrument against the calibrating instruments in a
Solver.Examples
In [27]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2002, 1, 1): 0.85, dt(2010, 1, 1): 0.75}) In [28]: solver = Solver( ....: curves=[curve], ....: instruments=[ ....: IRS(dt(2000, 1, 1), "2Y", spec="usd_irs", curves=[curve]), ....: IRS(dt(2000, 1, 1), "5Y", spec="usd_irs", curves=[curve]), ....: ], ....: s=[2.0, 2.25], ....: instrument_labels=["2Y", "5Y"], ....: id="US_RATES" ....: ) ....: SUCCESS: `func_tol` reached after 6 iterations (levenberg_marquardt), `f_val`: 8.499591036903249e-16, `time`: 0.0029s In [29]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", curves=[curve]) In [30]: irs.delta(solver=solver) Out[30]: local_ccy usd display_ccy usd type solver label instruments US_RATES 2Y 129.580448 5Y 162.173287
- Parameters:
curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, required) – A
Solverobject containing Curve, Smile, Surface, or Cube mappings for pricing.fx (FXForwards, optional) – The
FXForwardsobject used for forecasting FX rates, if necessary.vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – 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:
DataFrame
Notes
Delta measures the sensitivity of the PV to a change in any of the calibrating instruments of the given
Solver. Values are returned according to therate_scalarquantity at an Instrument level and according to themetricused to derive therate()method of each Instrument.
- exo_delta(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank, vars, vars_scalar=NoInput.blank, vars_labels=NoInput.blank)#
Calculate delta risk of an Instrument against some exogenous user created Variables, via a
Solver.See What are exogenous variables? in the cookbook.
Examples
This example calculates the risk of the fixed rate increasing by 1bp and the notional increasing by 1mm. Mathematically this should be equivalent to the npv and the analytic delta (although the calculation is based on AD and is completely independent of the solver).
In [31]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2002, 1, 1): 0.85, dt(2010, 1, 1): 0.75}) In [32]: solver = Solver( ....: curves=[curve], ....: instruments=[ ....: IRS(dt(2000, 1, 1), "2Y", spec="usd_irs", curves=[curve]), ....: IRS(dt(2000, 1, 1), "5Y", spec="usd_irs", curves=[curve]), ....: ], ....: s=[2.0, 2.25], ....: instrument_labels=["2Y", "5Y"], ....: id="US_RATES" ....: ) ....: SUCCESS: `func_tol` reached after 6 iterations (levenberg_marquardt), `f_val`: 8.499591036903249e-16, `time`: 0.0033s In [33]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=Variable(3.0, ["R"]), notional=Variable(1e6, ["N"]), curves=[curve]) In [34]: irs.exo_delta(solver=solver, vars=["R", "N"], vars_scalar=[1e-2, 1e6]) Out[34]: local_ccy usd display_ccy usd type solver label exogenous US_RATES R -291.752073 N -25123.690181 In [35]: irs.analytic_delta() Out[35]: <Dual: 291.752073, (N, 8b8490, 8b8491, ...), [0.0, 49.2, 239.9, ...]> In [36]: irs.npv() Out[36]: <Dual: -25123.690181, (N, R, 8b8490, ...), [-0.0, -29175.2, 982218.9, ...]>
- Parameters:
curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, required) – A
Solverobject containing Curve, Smile, Surface, or Cube mappings for pricing.fx (FXForwards, optional) – The
FXForwardsobject used for forecasting FX rates, if necessary.vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – 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.vars (list[str], required) – The variable tags which to determine sensitivities for.
vars_scalar (list[float], optional) – Scaling factors for each variable, for example converting rates to basis point etc. Defaults to ones.
vars_labels (list[str], optional) – Alternative names to relabel variables in DataFrames.
- Return type:
DataFrame
- gamma(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#
Calculate cross-gamma risk of an Instrument against the calibrating instruments of a
Solver.Examples
In [37]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2002, 1, 1): 0.85, dt(2010, 1, 1): 0.75}) In [38]: solver = Solver( ....: curves=[curve], ....: instruments=[ ....: IRS(dt(2000, 1, 1), "2Y", spec="usd_irs", curves=[curve]), ....: IRS(dt(2000, 1, 1), "5Y", spec="usd_irs", curves=[curve]), ....: ], ....: s=[2.0, 2.25], ....: instrument_labels=["2Y", "5Y"], ....: id="US_RATES" ....: ) ....: SUCCESS: `func_tol` reached after 6 iterations (levenberg_marquardt), `f_val`: 8.499591036903249e-16, `time`: 0.0030s In [39]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", curves=[curve]) In [40]: irs.gamma(solver=solver) Out[40]: type instruments solver US_RATES label 2Y 5Y local_ccy display_ccy type solver label usd usd instruments US_RATES 2Y -0.029442 -0.038104 5Y -0.038104 -0.010190
- Parameters:
curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, required) – A
Solverobject containing Curve, Smile, Surface, or Cube mappings for pricing.fx (FXForwards, optional) – The
FXForwardsobject used for forecasting FX rates, if necessary.vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – 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:
DataFrame
Notes
Gamma measures the second order cross-sensitivity of the PV to a change in any of the calibrating instruments of the given
Solver. Values are returned according to therate_scalarquantity at an Instrument level and according to themetricused to derive therate()method of each Instrument.
- local_analytic_rate_fixings(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#
Calculate the sensitivity to rate fixings of the Instrument, expressed in local settlement currency per basis point.
Examples
In [41]: curve1 = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75}, id="Eur1mCurve") In [42]: curve3 = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.70}, id="Eur3mCurve") In [43]: irs = IRS(dt(2000, 1, 1), "20m", spec="eur_irs3", curves=[{"1m": curve1, "3m": curve3}, curve1]) In [44]: irs.local_analytic_rate_fixings() Out[44]: identifier Eur1mCurve Eur3mCurve local_ccy eur eur display_ccy eur eur frequency 1M 3M obs_dates 1999-12-30 8.81934 7.215824 2000-02-28 NaN 25.251470 2000-05-30 NaN 25.069179 2000-08-30 NaN 24.619619 2000-11-29 NaN 24.177105 2001-02-27 NaN 24.535960 2001-05-30 NaN 24.884455
- Parameters:
curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A
Solverobject containing Curve, Smile, Surface, or Cube mappings for pricing.fx (FXForwards, optional) – The
FXForwardsobject used for forecasting FX rates, if necessary.vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
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
Notes
This analytic method will index the sensitivities with series identifier according to the Curve id which has forecast the fixing.
- local_fixings(identifiers, scalars=NoInput.blank, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#
Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.
- Parameters:
identifiers (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.curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A
Solverobject containing Curve, Smile, Surface, or Cube mappings for pricing.fx (FXForwards, optional) – The
FXForwardsobject used for forecasting FX rates, if necessary.vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
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
- npv(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, local=False, settlement=NoInput.blank, forward=NoInput.blank)#
Calculate the NPV of the Instrument converted to any other base accounting currency.
Examples
In [45]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75}) In [46]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=1.0, curves=[curve]) In [47]: irs.npv() Out[47]: 53875.24237805192 In [48]: irs.npv(local=True) Out[48]: {'usd': 53875.24237805192}
- Parameters:
curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A
Solverobject containing Curve, Smile, Surface, or Cube mappings for pricing.fx (FXForwards, optional) – The
FXForwardsobject used for forecasting FX rates, if necessary.vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.
local (bool, optional (set as False)) – An override flag to return a dict of NPV values indexed by string currency.
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:
float, Dual, Dual2, Variable or dict of such indexed by string currency.
Notes
If
baseis not given then this function will return the value obtained from determining the PV in local settlement currency.If
baseis provided this then anFXForwardsobject may be required to perform conversions. AnFXRatesobject is also allowed for this conversion although best practice does not recommend it due to possible settlement date conflicts.
- plot_payoff(range=NoInput.blank, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, vol=NoInput.blank)#
Return a plot of the payoff at expiry, indexed by the FXFixing value.
- Parameters:
range (list of float, optional) – A range of values for the FXFixing value at expiry to use as the x-axis.
curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A
Solverobject containing Curve, Smile, Surface, or Cube mappings for pricing.fx (FXForwards, optional) – The
FXForwardsobject used for forecasting FX rates, if necessary.vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
- Return type:
(Figure, Axes, list[Lines2D])
- rate(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank, metric=NoInput.blank)#
Calculate some pricing rate metric for the Instrument.
Examples
The default metric for an
IRSis its fixed ‘rate’.In [49]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75}) In [50]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", curves=[curve], fixed_rate=2.0) In [51]: irs.rate() # <- `fixed_rate` on fixed leg to equate value with float leg Out[51]: 2.87622187684324
- Parameters:
curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
solver (Solver, optional) – A
Solverobject containing Curve, Smile, Surface, or Cube mappings for pricing.fx (FXForwards, optional) – The
FXForwardsobject used for forecasting FX rates, if necessary.vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.
base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.
local (bool, optional (set as False)) – An override flag to return a dict of NPV values indexed by string currency.
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.metric (str, optional) – The specific calculation to perform and the value to return. See Pricing on each Instrument for details of allowed inputs.
- Return type:
- reset_fixings(state=NoInput.blank)#
Resets any fixings values of the Instrument derived using the given data state.
- 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.
- Return type:
None