3.6. Distortion Module

class aggregate.spectral.Distortion(name, shape, r0=0.0, df=None, col_x='', col_y='', display_name='')

Creation and management of distortion functions.

0.9.4: renamed roe to ccoc, but kept creator with roe for backwards compatibility. Oct 2022: renamed wtdtvar to bitvar, but kept …

__init__(name, shape, r0=0.0, df=None, col_x='', col_y='', display_name='')

Create a new distortion.

Tester:

ps = np.linspace(0, 1, 201)
for dn in agg.Distortion.available_distortions(True):
    if dn=='clin':
        # shape param must be > 1
        g_dist = agg.Distortion(**{'name': dn, 'shape': 1.25, 'r0': 0.02, 'df': 5.5})
    else:
        g_dist = agg.Distortion(**{'name': dn, 'shape': 0.5, 'r0': 0.02, 'df': 5.5})
    g_dist.plot()
    g = g_dist.g
    g_inv = g_dist.g_inv

    df = pd.DataFrame({'p': ps, 'gg_inv': g(g_inv(ps)), 'g_invg': g_inv(g(ps)),
    'g': g(ps), 'g_inv': g_inv(ps)})
    print(dn)
    print("errors")
    display(df.query(' abs(gg_inv - g_invg) > 1e-5'))

Parameters

• name – name of an available distortion, call Distortion.available_distortions() for a list

• shape – float or [float, float]

• shape – shape parameter

• r0 – risk free or rental rate of interest

• df – for convex envelope, dataframe with col_x and col_y used to parameterize or df for t

• col_x –

• col_y –

• display_name – over-ride name, useful for parameterized convex fix distributions

classmethod available_distortions(pricing=True, strict=True)

List of the available distortions.

Parameters

• pricing – only return list suitable for pricing, excludes tvar and convex

• strict – only include those without mass at zero (pricing only)

Returns

static average_distortion(data, display_name, n=201, el_col='EL', spread_col='Spread')

Create average distortion from (s, g(s)) pairs. Each point defines a wtdTVaR with p=s and p=1 points.

Parameters

• data –

• display_name –

• n – number of s values (between 0 and max(EL), 1 is added

• el_col – column containing EL

• spread_col – column containing Spread

Returns

static bagged_distortion(data, proportion, samples, display_name='')

Make a distortion by bootstrap aggregation (Bagging) resampling, taking the convex envelope, and averaging from data.

Each sample uses proportion of the data.

Data must have two columns: EL and Spread

Parameters

• data –

• proportion – proportion of data for each sample

• samples – number of resamples

• display_name – display_name of created distortion

Returns

static convex_example(source='bond')

Example convex distortion using data from https://www.bis.org/publ/qtrpdf/r_qt0312e.pdf.

Parameters

source – bond gives a bond yield curve example, cat gives cat bond / cat reinsurance pricing based example

Returns

static distortions_from_params(params, index, r0=0.025, df=5.5, pricing=True, strict=True)

Make set of dist funs and inverses from params, output of port.calibrate_distortions. params must just have one row for each method and be in the output format of cal_dist.

Called by Portfolio.

Parameters

• index –

• params – dataframe such that params[index, :] has a [lep, param] etc. pricing=True, strict=True: which distortions to allow df for t distribution

• r0 – min rol parameters

• strict –

• pricing –

Returns

g_dual(x)

The dual of the distortion function g.

plot(xs=None, n=101, both=True, ax=None, plot_points=True, scale='linear', c=None, size='small', **kwargs)

Quick plot of the distortion

Parameters

• xs –

• n – length of vector is no xs

• both – True: plot g and ginv and add decorations, if False just g and no trimmings

• ax –

• plot_points –

• scale – linear as usual or return plots -log(gs) vs -logs and inverts both scales

• size – ‘small’ or ‘large’ for size of plot, FIG_H or FIG_W. The default is ‘small’.

• kwargs – passed to matplotlib.plot

Returns

price(ser, a=inf, kind='ask', S_calculation='forwards')

Compute the bid and ask prices for the distribution determined by ser with an asset limit a. Index of ser need not be equally spaced, so it can be applied to \(\kappa\). To do this for unit A in portfolio port:

ser = port.density_df[['exeqa_A', 'p_total']].\
    set_index('exeqa_A').groupby('exeqa_A').\
    sum()['p_total']
dist.price(ser, port.q(0.99), 'both')

Always use S_calculation='forwards method to compute S = 1 - cumsum(probs). Computes the price as the integral of gS.

Parameters

• ser – pd.Series of is probabilities, indexed by outcomes. Outcomes need not be spaced evenly. ser is usually a probability column from density_df.

• kind – is “ask”, “bid”, or “both”, giving the pricing view.

• a – asset level. ser is truncated at a.

price2(ser, a=None, S_calculation='forwards')

Compute the bid and ask prices for the distribution determined by ser with an asset limits given by values of ser. Index of ser need not be equally spaced, so it can be applied to \(\kappa\). To do this for unit A in portfolio port:

ser = port.density_df[['exeqa_A', 'p_total']].\
    set_index('exeqa_A').groupby('exeqa_A').\
    sum()['p_total']
dist.price(ser, port.q(0.99))

Parameters

ser – pd.Series of is probabilities, indexed by outcomes. Outcomes must be spaced evenly. ser is usually a probability column from density_df.

static s_gs_distortion(s, gs, display_name='')

Make a convex envelope distortion from {s, g(s)} points.

Parameters

• s – iterable (can be converted into numpy.array

• gs –

• display_name –

Returns

classmethod test(r0=0.035, df=[0.0, 0.9])

Tester: make some nice plots of available distortions.

Returns

static wtd_tvar(ps, wts, display_name='', details=False)

A careful version of wtd tvar with knots at ps and wts.

Parameters

• ps –

• wts –

• display_name –

• details –

Returns

aggregate.spectral.approx_ccoc(roe, eps=1e-14, display_name=None)

Create a continuous approximation to the CCoC distortion with return roe. Helpful utility function for creating a distortion.

Parameters

• roe – return on equity

• eps – small number to avoid mass at zero

aggregate.spectral.tvar_weights(d)

Return tvar weight function for a distortion d. Use np.gradient to differentiate g’ but adjust for certain distortions. The returned function expects a numpy array of p values.

Param

d distortion