4.12 Surface.help

Octarisk Class: object = Surface(id)

Octarisk Class: object = Surface()

Class for setting up Surface objects.

Surface class is used for specifying IndexVol, IRVol, Stochastic, Prepayment or Dummy Surfaces. A Surface (or Cube) stores two- or three-dimensional values (e.g. term, tenor and/or moneyness dependent volatility values. Surfaces can be shocked with risk factors (e.g. risk factor types RF_VOLA_EQ or RF_VOLA_IR) at any coordinates of the multi-dimensional space in MC or stress scenarios.

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

• IndexVol two-dimensional surface (term vs. moneyness) for setting up Equity volatility values.
• IRVol two- or three-dimensional surface (term vs. moneyness) / cube (term vs. tenor vs. moneyness) for setting up Interest rate volatility values.
• Stochastic one- or two-dimensional curve / surface to store scenario dependent values (e.g. stochastic cash flow surface with values dependent on date and quantile)
• Prepayment two-dimensional prepayment surface with prepayment factors dependent on e.g. interest rate shock and coupon rates.
• Dummy Dummy curve for various purposes.

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

Methods for Surface object obj:

• Surface(id) or Surface(): Constructor of a Surface 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.getValue(scenario, x, y, z): Return Surface value at given coordinates according to scenario type. Interpolate surface base value and risk factor shock (only possible after call of method apply_rf_shocks )
• Surface.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]
• obj.apply_rf_shocks(riskfactor_struct): Apply risk factor shocks to Surface base values and store the shocks for later use in attribute shock_struct. These shocks are then applied to the surface base value with method getValue. The risk factors are taken from the provided structure according to the surface risk factor IDs given by the attribute riskfactors.
• Surface.interpolate(x, [y, [z]]): Return Surface base value at given coordinates.

Attributes of Surface objects:

• id: Surface id. Has to be unique identifier. Default: empty string.
• name: Surface name. Default: empty string.
• description: Surface description. Default: empty string.
• type: Surface type. Can be [Index, IR, Stochastic, Prepayment, Dummy Surfaces]. Default: Index.
• day_count_convention: Day count convention of curve. See ’help get_basis’ for details (Default: ’act/365’)
• compounding_type: Compounding type. Can be continuous, discrete or simple. (Default: ’cont’)
• method_interpolation: Interpolation method. Can be linear or nearest. Default: linear.
• compounding_freq: Compounding frequency used for discrete compounding. Can be [daily, weekly, monthly, quarterly, semi-annual, annual]. (Default: ’annual’)
• values_base: Base values of Surface.
• moneyness_type: Moneyness type. Can be K/S for relative moneyness or K-S for absolute moneyness. (Default: ’K/S’).
• shock_struct: Structure containing all risk factor shock specifications (e.g. model, risk factor coordinates, shock values and shift type)
• riskfactors: Cell specifying all risk factor IDs
• axis_x: x-axis coordinates
• axis_y: y-axis coordinates
• axis_z: z-axis coordinates
• axis_x_name: x-axis name
• axis_y_name: y-axis name
• axis_z_name: z-axis name

For illustration see the following example:

disp('Setting up an Index Surface and Risk factor, apply shocks and retrieve values:')
r1 = Riskfactor();
r1 = r1.set('id','V1','scenario_stress',[1.0;-0.5], ...
'model','GBM','shift_type',[1;1], ...
'node',730,'node2',1);
riskfactor_struct(1).id = r1.id;
riskfactor_struct(1).object = r1;
v = Surface();
v = v.set('id','V1','axis_x',[365,3650], ...
'axis_x_name','TERM','axis_y',[0.9,1.0,1.1], ...
'axis_y_name','MONEYNESS');
v = v.set('values_base',[0.25,0.36;0.22,0.32;0.26,0.34]);
riskfactor_cell = cell;
riskfactor_cell(1) = 'V1';
v = v.set('type','INDEX','riskfactors',riskfactor_cell);
v = v.apply_rf_shocks(riskfactor_struct);
base_value = v.interpolate(365,0.9)
base_value = v.getValue('base',365,0.9)
stress_value = v.getValue('stress',365,0.9)

Dependencies of class: