4.18 Retail.help

Octarisk Class: object = Retail(id)

Octarisk Class: object = Retail()

Class for setting up various Retail objects like saving plans with bonus or defined contribution pension plans and retirement expenses. Cash flows are generated specific for each Retail sub type and subsequently discounted to calculate the Retail value.

• DCP: Defined contribution savings plan with guaranteed value at maturity and surrender value.
• SAVPLAN: Savings plan with optional bonus at maturity.
• RETEXP: Modelling retirement expenses depending on survival rates and inflation expectation rates.
• GOVPEN: Modelling government pensions depending on survival rates and inflation expectation rates.

In the following, all methods and attributes are explained and a code example is given.

Methods for Retail object obj:

• Retail(id) or Retail(): Constructor of a Bond object. id is optional and specifies id and name of new object.
• obj.set(attribute,value): Setter method. Provide pairs of attributes and values. Values are checked for format and constraints.
• obj.get(attribute): Getter method. Query the value of specified attribute.
• obj.calc_value(valuation_date,scenario, discount_curve) Calculate the net present value of cash flows of Bonds (including pricing of embedded options)
• obj.rollout(scenario, valuation_date): used for SAVPLAN and DCP without redemption
• obj.rollout(scenario, valuation_date, discount_curve): used for DCP with redemption
• obj.rollout(scenario, valuation_date, inflation_exp_curve, longevity_table): used for retirement expenses and government pensions
• obj.calc_sensitivities(valuation_date,discount_curve) Calculate numerical sensitivities for the given Retail instrument.
• obj.calc_key_rates(valuation_date,discount_curve) Calculate key rate sensitivities for the given Retail instrument.
• obj.getValue(scenario): Return Retail value for given scenario. Method inherited from Superclass Instrument
• Retail.help(format,returnflag): show this message. Format can be [plain text, html or texinfo]. If empty, defaults to plain text. Returnflag is boolean: True returns documentation string, false (default) returns empty string. [static method]

Attributes of Retail objects:

• id: Instrument id. Has to be unique identifier. (Default: empty string)
• name: Instrument name. (Default: empty string)
• description: Instrument description. (Default: empty string)
• value_base: Base value of instrument of type real numeric. (Default: 0.0)
• currency: Currency of instrument of type string. (Default: ’EUR’) During instrument valuation and aggregation, FX conversion takes place if corresponding FX rate is available.
• asset_class: Asset class of instrument. (Default: ’derivative’)
• type: Type of instrument, specific for class. Set to ’Bond’.
• value_stress: Line vector with instrument stress scenario values.
• value_mc: Line vector with instrument scenario values. MC values for several timestep_mc are stored in columns.
• timestep_mc: String Cell array with MC timesteps. If new timesteps are set, values are automatically appended.

For illustration see the following example: A monthly savings plan with extra payments and bonus at maturity is valuated. The resulting base value (52803.383344) and effective duration (4.9362)is retrieved:

disp('Pricing Savings Plan');
rates_base = [0.0056,0.02456];
rates_stress = rates_base + [-0.05;-0.03;0.0;0.03;0.05];
valuation_date = '31-May-2019';
r = Retail();
r = r.set('Name','Test_SAVPLAN','sub_type','SAVPLAN', ...
'coupon_rate',0.0155,'coupon_generation_method', ...
'backward','term',1,'term_unit','months');
r = r.set('maturity_date','05-May-2024','compounding_type', ...
'simple','savings_rate',500);
r = r.set('savings_startdate','05-May-2014', ...
'savings_enddate','05-May-2021');
r = r.set('extra_payment_values',[17500], ...
'extra_payment_dates',cellstr('17-May-2019'), ...
'bonus_value_current',0.5,'bonus_value_redemption',0.15);
r = r.set('notice_period',3,'notice_period_unit','months');
r = r.rollout('base',valuation_date);
r = r.rollout('stress',valuation_date);
c = Curve();
c = c.set('id','IR_EUR','nodes',[365,7300]);
c = c.set('rates_base',rates_base,'rates_stress',rates_stress);
c = c.set('method_interpolation','linear');
r = r.calc_value(valuation_date,'base',c);
r = r.calc_value(valuation_date,'stress',c);
r = r.calc_sensitivities(valuation_date,c);
r = r.calc_key_rates(valuation_date,c);
r

Dependencies of class: