ir.model package

ir.model.calib_input_helper module

Calibration helper for short rate models

class ir.model.calib_input_helper.CalibrationError

Bases: enum.Enum

Calibration error enum

Prc = <CalibrationError.Prc: 1>

Price error (MarketPrc - ModelPrc)

RelPrc = <CalibrationError.RelPrc: 0>

Relative price error (MarketPrc - ModelPrc) / MarketPrc

Vol = <CalibrationError.Vol: 2>

Implied volatility error (MarketVol - ModelVol)

ir.model.calib_input_helper.cap(term_structure, cap_tenor, cap_vol, weight, pricing_engine, floating_index, daycount=<DayCount.Act360: <QuantLib.QuantLib.Actual360; proxy of <Swig Object of type 'QuantLib::Actual360 *' at 0x000000000696E0F0> >>, fixed_freq=<Freq.Semiannual: 2>, calib_error=<CalibrationError.Prc: 1>)

Calibration helper for cap

Parameters:

• term_structure (ql.YieldTermStructure) – Term Structure handle
• cap_tenor – (list) cap tenor in ql.Period
• cap_vol (list) – Cap volatility
• weight (list) – Calibration weight
• pricing_engine (ql.SwaptionEngine) – Pricing engine (see ir.model.hull_white.calibrate)
• floating_index (ql.IborIndex) – Floating rate index (E.g., ql.USDLibor(ql.Period(‘3M’), term_structure))
• daycount (ir.date_time.enum.DayCount) – Daycount for fixed and floating (Default: DayCount.Actual360)
• fixed_freq (ir.date_time.enum.Freq) – Fixed rate payment frequency (Default: Freq.Semiannual)
• calib_error (ir.model.calib_input_helper.CalibrationError) – Calibration error (Default: CalibrationError.Prc) This parameter does not change the setting in CapHelper. I suspect bug in QuantLib-Swig

Returns:

tuple contains:

• helper (list): list of ql.CalibrationHelper
• input_data (Pandas.DataFrame): DataFrame by columns: ‘vol’, ‘weight’ and index: ‘name’

Return type:

tuple

Warning

calib_error parameter does not change the CalibrationErrorType in ql.CapHelper

CalibrationError type is always set as RelPrc error type in quantlib-swig 1.8

I complied quantlib-swig 1.8.1 to set the default as Prc

ir.model.calib_input_helper.extract_json(json_file, term_structure, swaption_prc_engine=None, cap_prc_engine=None, calib_error=<CalibrationError.Prc: 1>, is_print=False)

The json file is for the most widely used inputs for US market. Input types are swaption, caps (todo) on Libor 3M

Parameters:

• json_file (str) – json file name
• term_structure (ql.YieldTermStructure) – Term Structure handle
• swaption_prc_engine (e.g., ql.JamshidianSwaptionEngine) – Pricing engine (see ir.model.hull_white.calibrate, Default: None)
• cap_prc_engine (e.g., ql.AnalyticCapFloorEngine) – Cap pricing engine (Default: None)
• calib_error (ir.model.calib_input_helper.CalibrationError) – Calibration error (Default: Prc)
• is_print (bool) – print in console (Default: False)

Returns:

tuple contains:

• helper (list): list of ql.CalibrationHelper
• input_data (Pandas.DataFrmae): DataFrame by columns: ‘vol’, ‘weight’ and index: ‘name’

Return type:

tuple

ir.model.calib_input_helper.swaption(term_structure, swaption_exercise, swap_tenor, swaption_vol, weight, pricing_engine, floating_index, daycount=<DayCount.Act360: <QuantLib.QuantLib.Actual360; proxy of <Swig Object of type 'QuantLib::Actual360 *' at 0x000000000696E0F0> >>, fixed_freq=<Freq.Semiannual: 2>, calib_error=<CalibrationError.Prc: 1>)

Calibration helper for swaption

Parameters:

• term_structure (ql.YieldTermStructure) – Term Structure handle
• swaption_exercise (list) – Swaption exercise in ql.Period
• swap_tenor – (list) Underlying swap tenor in ql.Period
• swaption_vol (list) – Swaption volatility
• weight (list) – Calibration weight
• pricing_engine (ql.JamshidianSwaptionEngine) – Pricing engine (see ir.model.hull_white.calibrate)
• floating_index (ql.IborIndex) – Floating rate index (E.g., ql.USDLibor(ql.Period(‘3M’), term_structure))
• daycount (ir.date_time.enum.DayCount) – Daycount for fixed and floating (Default: DayCount.Actual360)
• fixed_freq (ir.date_time.enum.Freq) – Fixed rate payment frequency (Default: Freq.Semiannual)
• calib_error (ir.model.calib_input_helper.CalibrationError) – Calibration error (Default: CalibrationError.Prc)

Returns:

tuple contains:

• helper (list): list of ql.CalibrationHelper
• input_data (Pandas.DataFrmae): DataFrame by columns: ‘vol’, ‘weight’ and index: ‘name’

Return type:

tuple

ir.model.hull_white module

Hull-While one factor module

class ir.model.hull_white.HullWhite1F(curve, **kwargs)

Bases: ir.model.short_rate.ShortRate

Hull-White one factor model class

Examples

• Curve Construction

>>> curve = FlatForward(ql.Date(19, 2, 2002), 0.04875825, daycount=DayCount.Act365, val_date=ql.Date(15, 2, 2002))
2016-05-26 14:14:38 WARNING Valuation date is changed to [February 15th, 2002]

• Calibration

calib_hw1f_euribor.json is located in ir/model/test

>>> hw1f = HullWhite1F(curve, alpha=0.1, sigma=0.01)
>>> hw1f.calibrate('calib_hw1f_euribor.json',  is_plot=True, calib_error=CalibrationError.RelPrc)
>>> print(hw1f.param)
{'alpha': 0.04641648494793499, 'sigma': 0.005799411064368165}

You can also calibrate by fixing alpha to 0.06

>>> hw1f.self.hw1f.set_param(alpha=0.06)
>>> hw1f.calibrate('calib_hw1f_euribor.json',  is_fix_alpha=True, is_plot=True, calib_error=CalibrationError.RelPrc)
>>> print(hw1f.param)
{'alpha': 0.06, 'sigma': 0.00602605472101786}

You will see that the error has increased slightly

The figure below shows the objective function while changing alpha and sigma. The objective function does not change much around alpha: 0.0464, sigma: 0.0057.

>>> hw1f.plot_objective_fun('calib_hw1f_euribor.json', calib_error=CalibrationError.RelPrc)

The 2-D plot (alpha vs. relative price error) is presented below by fixing sigma = 0.0060

>>> self.hw1f.plot_objective_fun('calib_hw1f_euribor.json', calib_error=CalibrationError.RelPrc, alpha=numpy.arange(0.001, 1, 0.01), sigma=[0.0060])

• Simulation

>>> hw1f.simulate(ql.Period('10Y'), Freq.Monthly, 100, random_seed=1000, is_plot=True)

calibrate(calib_json_file, is_fix_alpha=False, is_fix_sigma=False, calib_error=<CalibrationError.Prc: 1>, is_plot=True)

Calibration implementation for Hull-White one factor model

Parameters:

• calib_json_file (str) – calibration json file name
• is_fix_alpha (bool) – Fix alpha (Default: False)
• is_fix_sigma (bool) – Fix sigma (Default: False)

:param calib_error:: Calibration error (Default: Prc) :type calib_error:: ir.model.calib_input_helper.CalibrationError :param is_plot: Plot calibration result (Default: True)

Returns: tuple: tuple includes:

• pandas.DataFrame: Calibration results
• list: calib_helper

See also

• http://gouthamanbalaraman.com/blog/short-interest-rate-model-calibration-quantlib.html
• http://wwwf.imperial.ac.uk/~mdavis/course_material/SDEIRM/HW_SWAPTION_FORMULA08.PDF

plot_objective_fun(calib_json_file, calib_error=<CalibrationError.Prc: 1>, **kwargs)

Calibration implementation for Hull-White one factor model

Parameters:

• calib_json_file (str) – calibration json file name
• kwargs – parameter ranges which is iterable

See also

• http://gouthamanbalaraman.com/blog/short-interest-rate-model-calibration-quantlib.html
• http://wwwf.imperial.ac.uk/~mdavis/course_material/SDEIRM/HW_SWAPTION_FORMULA08.PDF

simulate(sim_period, sim_freq, sim_path, random_seed=None, is_brownian_bridge=True, is_plot=False)

Simulation implementation for Hull-White one factor model

Parameters:

• sim_period (ql.Period) – Simulation period
• sim_freq (date_time.enum.Freq) – Simulation period
• sim_path (int) – Simulation number of path
• random_seed (int) – Random seed (Default: None, create based on system time or so)
• is_brownian_bridge (bool) – Brownian bridge (Default: True)
• is_plot (bool) – Plot short rate (Default: False)

Returns:

tuple contains:

• sim_time (list): Simulation time in year
• sim_short_rate (numpy.array): Short rate; sim_path x sim_time_step+1 array
• sim_discount_factor (numpy.array): Discount factor; sim_path x sim_time_step+1 array

Return type:

tuple

See also

• http://gouthamanbalaraman.com/blog/hull-white-simulation-quantlib-python.html
• http://gouthamanbalaraman.com/blog/hull-white-simulation-monte-carlo-convergence.html

ir.model.short_rate module

Short rate module

class ir.model.short_rate.ShortRate(curve, **kwargs)

Bases: object

Base class for short rate models

calibrate(calib_json, is_plot=True)

Calibrate short rate model

Parameters:

• calib_json (str) – json file name
• is_plot (bool) – Plot calibration results by plot_calibration method

returns: tuple: tuple contains:

• Pandas.DataFrame: calib_result,
• list: calib_helper

plot_calibration(calib_result, title=None)

Plot calibration results

Parameters:

• calib_result – Calibration results by self.calibrate method
• title – title string (Default: None)

plot_objective_fun(calib_json, **kwargs)

Plot the objective function

Parameters:

• calib_helper –
• kwargs – parameter ranges in numpy.arange

set_param(**kwargs)

Set parameters after instantiation

Parameters:**kwargs – param_name=param_val format (it will initialized the parameter) (e.g., set_param(alpha=0.01, sigma=0.01) for ir.model.hull_white.HullWhile1F) Raises:ValueError – if curve is not instance of ir.term_structure.curves.Curve

simulate(sim_period, sim_freq, sim_path, random_seed=None, is_brownian_bridge=True, is_plot=False)

Simulate short rate model

Parameters:

• sim_period – Simulation period in year (e.g. ql.Period(10, ql.Years) for 10-year)
• sim_freq – Simulation frequency in year (e.g. Freq.Quarterly for 3-month interval)
• sim_path – Number of simulation path (e.g. 100 for 100 simulation paths)
• random_seed – Random seed for simulation (Default: None, not to have the seed)
• is_brownian_bridge – Brownian Bridge implementation (Default: True)
• is_plot – Plot the simulation path for short rate