4.8 Sensitivity.help

Octarisk Class: object = Sensitivity(id)

Octarisk Class: object = Sensitivity()

Class for setting up Sensitivity objects. This class contains two different instrument setups. The first idea of this class is to model an instrument whose shocks are derived from underlying risk factor shocks or idiosyncratic risk (for MC only). The shocks from these risk factors are then applied to the instrument base value under the assumption of a Geometric Brownian Motion or Brownian Motion. Basically, all real assets like Equity or Commodity can be modelled with this class. The combined shock is a linear combination of all underlying risk factor shocks:

V_shock = V_base * exp(Sum_i=1...n [dRF_i * w_i]) (Model: GBM)
V_shock = V_base + (Sum_i=1...n [dRF_i * w_i]) (Model: BM)

with the new shock Value V_shock, base V_base, risk factor shock dRF_i and risk factor weight w_i.

The second idea is to use this class to specify a polynomial function or taylor series of underlying instruments, risk factors, curves, surfaces or indizes and derive the sensitivity value with the following formulas. If Taylor expansion shall be used:

V_shock = V_base + a1/b1 * x1^b1 + a2/b2 * x2^b2 + .. + an/bn * xn^bn * am/bm * xm^bm

The base value is used only if appropriate flag is set. Otherwise, a polynomial function can be set up:

V_shock = V_base + a1 * x1^b1 + a2 * x2^b2 + .. + an * xn^bn * am * xm^bm

with the new shock Value V_shock, base V_base, and prefactors a, exponents b and a multiplicative combination of cross terms (term with equal cross terms are multiplied with each other, term with cross terms equal zero are added to the total value) All combined cross terms and all single terms are finally summed up.

This class contains all attributes and methods related to the following Sensitivity types:

• EQU: Equity sensitivity type
• RET: Real Estate sensitivity type
• COM: Commodity sensitivity type
• STK: Stock sensitivity type
• ALT: Alternative investments sensitivity type
• SENSI: Taylor series or polynomial equation of underlying objects

which stands for Equity, Real Estate, Commodity, Stock and Alternative Investments. All sensitivity types assume a geometric brownian motion or brownian motion as underlying stochastic process.

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

Methods for Sensitivity object obj:

• Sensitivity(id) or Sensitivity(): Constructor of a Sensitivity 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, riskfactor_struct, instrument_struct, index_struct, curve_struct, surface_struct, [scen_number]): Method for calculation of sensitivity value. Only structures with used objects need to be set.
• obj.valuate(valuation_date, scenario, instrument_struct, surface_struct, matrix_struct, curve_struct, index_struct, riskfactor_struct, [ para_struct ]) Generic instrument valuation method. All objects required for valuation of the instrument are taken from provided structures (e.g. curves, riskfactors, underlying indizes). Method inherited from Superclass Instrument.
• obj.getValue(scenario): Return Sensitivity value for given scenario. Method inherited from Superclass Instrument
• Sensitivity.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 Sensitivity 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: empty string
• type: Type of instrument, specific for class. Set to ’sensitivity’.
• 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.
• riskfactors: Cell with IDs of all underlying risk factors. Default: empy cell.
• sensitivities: Vector with weights of riskfactors of same length and order as riskfactors cell. Default: empty vector
• idio_vola: Idiosyncratic volatility of sensitivity instrument. Used only if one riskfactor is set to ’IDIO’. Applies a shock given by a normal distributed random variable with standard deviation taken from the value of attribute idio_vola and a mean of zero.
• model: Model specifies the stochastic process. Can be a Geometric Brownian Notion (GBM) or Brownian Notion (BM). (Default: ’GBM’)
• underlyings: cell array of underlying indizes, curves, surfaces, instruments, risk factors
• x_coord: vector with x coordinates of underlying (curves, surfaces, cubes only)
• y_coord: vector y coordinate of underlying (surfaces, cubes only)
• z_coord: vector z coordinate of underlying (cubes only)
• shock_type: cell array of shock types for each underlying [value, relative, absolute]
• sensi_prefactor: vector with prefactors (a in a*x^b)
• sensi_exponent: vector with exponents (b in a*x^b)
• div_yield: forecast dividend yield
• div_month: dividend paymend month
• sensi_cross: vector with cross terms [0 = single; 1,2,3, ... link cross terms]
• use_value_base: boolean flag: use value_base for base valuation. Scenario shocks are added to base value (default: false)
• use_taylor_exp: boolean flag: if true, treat polynomial value as Taylor expansion(default: false)
• cf_dates: Unused: Cash flow dates (Default: [])
• cf_values: Unused: Cash flow values (Default: [])

For illustration see the following example: An All Country World Index (ACWI) fund with base value of 100 USD shall be modelled with both instrument setups (Linear combination of risk factor shocks and a polynomial (linear) function with two single terms. Underlying risk factors are the MSCI Emerging Market and MSCI World Index. The sensitivities to both risk factors are equal to the weights of the subindices in the ACWI index. Both risk factors are shocked during a stress scenario and the total shock values for the fund are calculated:

 fprintf('	doc_instrument:	Pricing Sensitivity Instrument (Polynomial Function)');
 r1 = Riskfactor();
  r1 = r1.set('id','MSCI_WORLD','scenario_stress',[20;-10], ...
        'model','GBM','shift_type',[1;1]);
  r2 = Riskfactor();
  r2 = r2.set('id','MSCI_EM','scenario_stress',[10;-20], ...
        'model','GBM','shift_type',[1;1] );
  riskfactor_struct = struct();
  riskfactor_struct(1).id = r1.id;
  riskfactor_struct(1).object = r1;
  riskfactor_struct(2).id = r2.id;
  riskfactor_struct(2).object = r2;
  s = Sensitivity();
  s = s.set('id','MSCI_ACWI_ETF','sub_type','SENSI', 'currency', 'USD' , ...
        'asset_class','Equity',  'value_base', 100, ...
        'underlyings',cellstr(['MSCI_WORLD';'MSCI_EM']), ...
        'x_coord',[0,0], ...
        'y_coord',[0,0.0], ...
        'z_coord',[0,0], ...
        'shock_type', cellstr(['absolute';'absolute']), ...
        'sensi_prefactor', [0.8,0.2], 'sensi_exponent', [1,1], ...
        'sensi_cross', [0,0], 'use_value_base',true,'use_taylor_exp',false);
  instrument_struct = struct();
  instrument_struct(1).id = s.id;
  instrument_struct(1).object = s;
s = s.calc_value('31-Dec-2016', 'base',riskfactor_struct,instrument_struct,[],[],[],2);
s.getValue('base')
s = s.calc_value('31-Dec-2016', 'stress',riskfactor_struct,instrument_struct,[],[],[],2);
s.getValue('stress')

 fprintf('	doc_instrument:	Pricing Sensitivity Instrument (Riskfactor linear combination)');
 r1 = Riskfactor();
  r1 = r1.set('id','MSCI_WORLD','scenario_stress',[20;-10], ...
        'model','BM','shift_type',[1;1]);
  r2 = Riskfactor();
  r2 = r2.set('id','MSCI_EM','scenario_stress',[10;-20], ...
        'model','BM','shift_type',[1;1] );
  riskfactor_struct = struct();
  riskfactor_struct(1).id = r1.id;
  riskfactor_struct(1).object = r1;
  riskfactor_struct(2).id = r2.id;
  riskfactor_struct(2).object = r2;
  s = Sensitivity();
  s = s.set('id','MSCI_ACWI_ETF','sub_type','EQU', 'currency', 'USD', ...
        'asset_class','Equity', 'model', 'BM', ...
        'riskfactors',cellstr(['MSCI_WORLD';'MSCI_EM']), ...
        'sensitivities',[0.8,0.2],'value_base',100.00);
  instrument_struct = struct();
  instrument_struct(1).id = s.id;
  instrument_struct(1).object = s;
  s = s.valuate('31-Dec-2016', 'stress', ...
        instrument_struct, [], [], ...
        [], [], riskfactor_struct);
  s.getValue('stress')

Stress results are [118;88].

Dependencies of class: