risk.validation.trafficLightVaRTest

Value-at-risk (VaR) traffic light test

Since R2025b

collapse all in page

    Syntax

    hTLTest = risk.validation.trafficLightVaRTest(VaRLevel,NumExceptions,NumObservations)
    hTLTest = risk.validation.trafficLightVaRTest(VaRLevel,NumExceptions,NumObservations,Name=Value)
    [hTLTest,Output] = risk.validation.trafficLightVaRTest(___)

    Description

    hTLTest = risk.validation.trafficLightVaRTest(VaRLevel,NumExceptions,NumObservations) returns the traffic light test result, hTLTest, for a given VaR confidence level, number of VaR exceptions, and number of observations. The output is an integer indicating the zone that the test statistic falls into.

    example

    hTLTest = risk.validation.trafficLightVaRTest(VaRLevel,NumExceptions,NumObservations,Name=Value) specifies additional options using one or more name-value arguments. For example, you can specify the bounds for the zones.

    [hTLTest,Output] = risk.validation.trafficLightVaRTest(___) also returns a structure Output that contains summary metrics.

    example

    Examples

    collapse all

    Open Live Script

    Perform a traffic light test for 40 VaR exceptions over 250 trading days, using a 90% VaR confidence level.

    hTLTest = risk.validation.trafficLightVaRTest(0.9,40,250)
    hTLTest = 
2

    The default confidence level intervals for the traffic light test are [0,0.95) for zone 1, [0.95,0.9999) for zone 2, and [0.9999,1] for zone 3. The Basel supervisory framework calls zones 1, 2, and 3 the green, amber, and red zones, respectively. The test result indicates that the test statistic falls into the amber zone. Under the null hypothesis that the VaR model is accurate, the probability of observing 40 or less VaR exceptions in 250 trading days is greater than or equal to 95%, but is less than 99.99%. In other words, the probability of observing more than 40 VaR exceptions is greater than 0.01%, but less than or equal to 5%. Such a result indicates that the VaR model could be underpredicting the number of VaR exceptions.

    Open Live Script

    Perform a traffic light test for 15 VaR exceptions over 250 trading days, using a 95% VaR level. Define the zones for the test statistic and specify the method for calculating the scaling factor increase.

    [hTLTest,Output] = risk.validation.trafficLightVaRTest(0.95,15,250,ConfidenceThresholds=[0.8 0.9],ScalingFactorType="Normal")
    hTLTest = 
2

    Output = struct with fields:
    Results: [1×9 table]

    The traffic light test classifies the test statistic as being in zone 2. Under the null hypothesis that the VaR model is accurate, the probability of observing 15 exceptions or less over 250 trading days is between 80% and 90%.

    Display the summary metrics for the test.

    Output.Results
    ans=1×9 table
    Zone    NumExceptions    ScalingFactorIncrease    CumulativeProbability    ConfidenceThresholds    CriticalValues    Type1ErrorProbability    NumObservations    VaRLevel
    ____    _____________    _____________________    _____________________    ____________________    ______________    _____________________    _______________    ________

     2           15                 0.17381                  0.81128                0.8    0.9            15    17              0.27116                 250            0.95

    The results show that, under the null hypothesis, the cumulative probability for observing 15 exceptions or less is approximately 81% and the probability of observing 15 exceptions or more is approximately 27%. Critical values for zones 2 and 3 are 15 and 17 exceptions.

    Input Arguments

    collapse all

    VaR confidence level, specified as a numeric scalar between 0 and 1, or a vector of values between 0 and 1. VaRLevel represents the expected proportion of time periods in the backtesting window without VaR exceptions.

    When VaRLevel is a vector, risk.validation.trafficLightVaRTest performs a test for each of its elements. If one or both of NumExceptions and NumObservations are also vectors, they must be of the same length as VaRLevel.

    Example: 0.95

    Data Types: single | double

    Number of time periods in the backtesting window with VaR exceptions, specified as a nonnegative integer or array of nonnegative integers. Each element of NumExceptions must be less than or equal to the element at the same index in NumObservations.

    When NumExceptions is a vector, risk.validation.trafficLightVaRTest performs a test for each of its elements. If one or both of VaRLevel and NumObservations are also vectors, they must be of the same length as NumExceptions.

    Example: 30

    Data Types: single | double

    Number of time periods in the backtesting window, specified as a positive integer or vector of positive integers. Each element of NumObservations must be greater than or equal to the element at the same index in NumExceptions.

    When NumObservations is a vector, risk.validation.trafficLightVaRTest performs a test for each of its elements. If one or both of VaRLevel and NumExceptions are also vectors, they must be of the same length as NumObservations.

    Example: 250

    Data Types: single | double

    Name-Value Arguments

    collapse all

    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: hTLTest = risk.validation.trafficLightVaRTest(0.95,5,100,ConfidenceThresholds=[0.9,0.95],ScalingFactorType="Normal") specifies three test statistic zones, and a normal scaling factor type.

    Bounds for the test statistic zones, specified as a vector of values between 0 and 1. The test statistic is classified as being in a zone if it is greater than or equal to the zone's lower bound and smaller than the zone's upper bound. For more information about the test statistic, see More About.

    To define the zones, risk.validation.trafficLightVaRTest divides the interval [0,1] using the unique values in ConfidenceThresholds. Then, the function assigns integer labels starting at 1 to the zones, in ascending order of the upper bounds.

    The default values for ConfidenceThresholds correspond to the zones used by the Basel supervisory framework.

    Example: [0.9 0.95]

    Data Types: single | double

    Method for calculating the scaling factor increase, specified as "Basel" or "Normal". The scaling factor increase is the additional amount added to the scaling factor used to calculate the required reserve capital for a portfolio. A larger value implies a greater penalty resulting from the VaR performance.

    • "Basel" — risk.validation.trafficLightVaRTest calculates the scaling factor from the Basel supervisory framework. To specify ScalingFactorType as "Basel", you must also specify VaRLevel, ConfidenceThresholds, and NumObservations as 0.99, [0.95 0.9999] (default), and 250, respectively. Otherwise, risk.validation.trafficLightVaRTest returns NaN for the ScalingFactorIncrease field in the Output argument.

    • "Normal" — risk.validation.trafficLightVaRTest calculates the scaling factor from the Basel supervisory framework, omitting the rounding step.

    For more information about how the software calculates the scaling factor increase, see Section 3(e) of [1].

    Example: "Normal"

    Data Types: single | double

    Output Arguments

    collapse all

    Test statistic zone or zones, returned as a positive integer scalar or vector of positive integers. A test statistic is classified as being in a zone if it is greater or equal to the zone's lower bound and smaller than the zone's upper bound. For more information about the test statistic, see More About.

    hTLTest is a scalar if VaRLevel, NumExceptions, and NumObservations are all scalars. Otherwise, hTLTest is a vector of the same length as the vector inputs. In this case, each element of hTLTest contains the traffic light test result corresponding to the elements at the same index in the vector input arguments.

    Output metrics, returned as a structure with a single field Results. Results contains a table with the following columns:

    • Zone — Test statistic zone, returned as a numeric scalar. Zone contains the same value as hTLTest.

    • NumExceptions — Number of time periods in the backtesting window with VaR exceptions, returned as a nonnegative integer. This value is specified by the NumExceptions input argument.

    • ScalingFactorIncrease — Additional amount added to the scaling factor used to calculate the required reserve capital for a portfolio, returned as a numeric scalar. A larger value implies a greater penalty resulting from the VaR performance. You can specify the method for calculating ScalingFactorIncrease using the ScalingFactorType name-value argument.

    • CumulativeProbability — Test statistic for the traffic light test, returned as a numeric scalar. CumulativeProbability is the probability of observing a number of VaR exceptions less than or equal to NumExceptions with the assumption that the VaR estimate is accurate.

    • ConfidenceThresholds — Bounds for the test statistic zones, returned as a vector. These values are specified by the ConfidenceThresholds name-value argument.

    • CriticalValues — Number of exceptions associated with each value in ConfidenceThresholds, returned as a numeric vector.

    • Type1ErrorProbability — Probability of observing NumExceptions or more VaR exceptions with the assumption that the VaR estimate is accurate.

    • NumObservations — Number of observations, returned as a positive integer. Each observation is a time period. This value is set by the NumObservations input argument.

    • VaRLevel — Confidence level for the VaR estimate, returned as a numeric scalar. This value is set by the VaRLevel input argument.

    For more information about the traffic light VaR test and its corresponding statistics, see More About.

    More About

    collapse all

    Alternative Functionality

    Function

    You can use the varbacktest object function tl to perform a traffic light test on a timeseries of portfolio outcomes. tl allows you to perform traffic light tests on multiple timeseries with different VaR levels.

    References

    [1] Basel Committee on Banking Supervision, "Supervisory Framework for the Use of "Backtesting in Conjunction with the Internal Models Approach to Market Risk Capital Requirements." January, 1996. https://www.bis.org/publ/bcbs22.pdf.

    [2] Basel Committee on Banking Supervision, "Calculation of RWA for market risk." January, 2022. https://www.bis.org/basel_framework/chapter/MAR/32.htm?inforce=20220101&published=20191215.

    Version History

    Introduced in R2025b

    See Also

    | | |

    Topics