Main Content


Format exceptions in value-at-risk (VaR) backtest object

Since R2023b



    excTable = exceptions(vbt) returns a formatted table or timetable of exceptions for a varbacktest object, vbt. 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 time, loss, VaR, and severity ratio.


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


    collapse all

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

    load VaRBacktestData
    vbt = varbacktest(EquityIndex,Normal95);
    excTable = exceptions(vbt);
        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    

    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
    vbt = varbacktest(EquityIndex,Normal95,Time=Date);
    lossTable = exceptions(vbt,VaRID="VaR",SeverityThreshold=0);
    sortedLosses = sortrows(lossTable,'SeverityRatio','descend');
    worstThree = sortedLosses(1:3,:);
           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    

    Input Arguments

    collapse all

    VaR backtest object, specified as a varbacktest object. vbt contains a copy of the given data (the PortfolioData and VarData properties) and all combinations of portfolio ID, VaR ID, and VaR levels to be tested.

    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(vbt,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 object.

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

    Exceptions threshold for specifying which VaR exceptions to include in the output table, specified as a numeric scalar. A 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(vbt,SeverityThreshold=0)

    Data Types: double

    Version History

    Introduced in R2023b