exceptions

Format exceptions in value-at-risk (VaR) or expected shortfall (ES) backtest objects

Since R2023b

Syntax

excTable = exceptions(btobj)

excTable = exceptions(btobj,Name=Value)

Description

excTable = exceptions(btobj) returns a formatted table or timetable of exceptions for a backtest object, where btobj is either an esbacktest object (since R2024a) or a varbacktest object. An exception is a data point where -portfolioValue > threshold*varValue. For example, if threshold=0, the table of exceptions includes all dates where portfolioValue < 0, indicating when losses occurred. A loss is defined as -portfolioValue for a given point in time. The ratio Loss/VaR defines the severity ratio.

The output table includes columns corresponding to the following:

• Time, Loss, VaR, and Severity Ratio for varbacktest objects

• Time, Loss, VaR, Severity Ratio, Expected Shortfall, and Expected Severity Ratio for esbacktest objects

excTable = exceptions(btobj,Name=Value) specifies additional output options using one or more name-value arguments. For example, excTable = exceptions(btobj,SeverityThreshold=0) applies an exceptions threshold to list only the dates where the portfolio shows a loss.

Examples

Create VaR Exceptions Table

Create a varbacktest object and use the exceptions function to create an exceptions table.

load VaRBacktestData
btobj = varbacktest(EquityIndex,Normal95);
excTable = exceptions(btobj);
head(excTable)

    Time      Loss        VaR       SeverityRatio
    ____    ________    ________    _____________

     58     0.022232    0.020108       1.1057    
    143     0.023592     0.01998       1.1808    
    145     0.022426    0.019963       1.1234    
    173      0.02561    0.017744       1.4433    
    204     0.025715    0.015562       1.6525    
    206     0.019577    0.015711       1.2461    
    263     0.016179    0.014776       1.0949    
    296     0.018806    0.014471       1.2996    

Customize VaR Exceptions Table

Use the exceptions function with the VaRID and SeverityThreshold name-value arguments to customize the exceptions table, returned in lossTable. Use this output table to determine the three largest trading losses each quarter.

load VaRBacktestData
btobj = varbacktest(EquityIndex,Normal95,Time=Date);
lossTable = exceptions(btobj,VaRID="VaR",SeverityThreshold=0);
sortedLosses = sortrows(lossTable,'SeverityRatio','descend');
worstThree = sortedLosses(1:3,:);
disp(worstThree)

       Time          Loss        VaR       SeverityRatio
    ___________    ________    ________    _____________

    12-Mar-2001    0.046719    0.016616       2.8116    
    14-Apr-2000    0.037507    0.013673       2.7431    
    12-Sep-2001    0.042186     0.01886       2.2367    

Customize ES Exceptions Table

Find the three worst losses in an ES backtesting window as measured by the SeverityRatio.

load ESBacktestData
btobj = esbacktest(Returns,VaRModel1,ESModel1,Time=Dates);
lossTable = exceptions(btobj,VaRID="VaR",SeverityThreshold=0);
sortedLosses = sortrows(lossTable,'SeverityRatio','descend');
worstThree = sortedLosses(1:3,:);
disp(worstThree)

       Time          Loss        VaR       SeverityRatio    ExpectedShortfall    ExpectedSeverityRatio
    ___________    ________    ________    _____________    _________________    _____________________

    27-Oct-1997    0.068657    0.018187       3.7751            0.021693                1.1928        
    31-Aug-1998    0.068014    0.021978       3.0947            0.026214                1.1928        
    08-Mar-1996    0.030827    0.010917       2.8237            0.013022                1.1928        

Input Arguments

btobj — Backtest object

varbacktest object | esbacktest object

Backtest object, specified as either a varbacktest or an esbacktest object.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: excTable = exceptions(btobj,SeverityThreshold=0)

VaRID — VaR ID

scalar string

VaR ID, specified as a scalar string containing the ID of the VaR vector to apply exceptions to. If you do not specify VarID, the exceptions function defaults to the first VaR ID in the varbacktest or esbacktest object.

Example: excTable = exceptions(btobj,VaRID="VaR")

SeverityThreshold — Exceptions threshold

1 (default) | numeric scalar

Exceptions threshold for specifying which VaR exceptions to include in the output table, specified as a numeric scalar. An exception is included in the table if -portfolioValue > threshold*varValue. Setting SevertiyThreshold to 0 lists all the dates where the portfolio shows a loss.

Example: excTable = exceptions(btobj,SeverityThreshold=0)

Data Types: double

Version History

Introduced in R2023b

R2024a: Format exceptions in ES backtest objects

Return formatted table or timetable of exceptions for ES backtest objects.