Main Content

exceptions

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

Since R2023b

collapse all in page

    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

    example

    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.

    example

    Examples

    collapse all

    Open Live Script

    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
    Open Live Script

    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
    Open Live Script

    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

    collapse all

    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)

    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")

    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

    expand all

    See Also

    | | | | | | | | | | | | |

    Topics