esbacktestbysim

Create esbacktestbysim object to run simulation-based suite of expected shortfall (ES) backtests by Acerbi and Szekely

expand all in page

Description

The general workflow is:

  1. Load or generate the data for the ES backtesting analysis.

  2. Create an esbacktestbysim object. For more information, see Create esbacktestbysim.

  3. Use the summary function to generate a summary report for the given data on the number of observations and the number of failures.

  4. Use the runtests function to run all tests at once.

  5. For additional test details, run the following individual tests:

    • conditional — Conditional test of Acerbi-Szekely (2014)

    • unconditional — Unconditional test of Acerbi-Szekely (2014)

    • quantile — Quantile test of Acerbi-Szekely (2014)

    For more information, see Overview of Expected Shortfall Backtesting.

Creation

Syntax

ebts = esbacktestbysim(PortfolioData,VaRData,ESData,DistributionName)
ebts = esbacktestbysim(___,Name,Value)

Description

example

ebts = esbacktestbysim(PortfolioData,VaRData,ESData,DistributionName) creates an esbacktestbysim (ebts) object and simulates portfolio outcome scenarios to compute critical values for three tests:

The ebts object has the following properties:

  • PortfolioData — NumRows-by-1 numeric array containing a copy of the PortfolioData

  • VaRData — NumRows-by-NumVaRs numeric array containing a copy of the VaRData

  • ESData — NumRows-by-NumVaRs numeric array containing a copy of the ESData

  • Distribution — Structure containing the model information, including model distribution name and distribution parameters. For example, for a normal distribution, Distribution has fields 'Name', 'Mean', and 'StandardDeviation', with values set to the corresponding inputs.

  • PortfolioID — String containing the PortfolioID

  • VaRID — 1-by-NumVaRs string vector containing the VaRIDs for the corresponding columns in VaRData

  • VaRLevel — 1-by-NumVaRs numeric array containing the VaRLevels for the corresponding columns in VaRData.

Note

  • The required input arguments for PortfolioData, VaRData, and ESData must all be in the same units. These arguments can be expressed as returns or as profits and losses. There are no validations in the esbacktestbysim object regarding the units of these arguments.

  • If there are missing values (NaNs) in PortfolioData, VaRData, ESData, or Distribution parameters data, the row of data is discarded before applying the tests. Therefore, a different number of observations are reported for models with a different number of missing values. The reported number of observations equals the original number of rows minus the number of missing values. To determine if there are discarded rows, use the 'Missing' column of the summary report.

example

ebts = esbacktestbysim(___,Name,Value) sets Properties using name-value pairs and any of the arguments in the previous syntax. For example, ebts = esbacktestbysim(PortfolioData,VaRData,ESData,DistributionName,'VaRID','TotalVaR','VaRLevel',.99). You can specify multiple name-value pairs.

Input Arguments

expand all

Portfolio outcomes data, specified as a NumRows-by-1 numeric array, NumRows-by-1 table, or a NumRows-by-1 timetable with a numeric column containing portfolio outcomes data. The PortfolioData input argument sets the PortfolioData property.

Note

PortfolioData data must be in the same units as VaRData and ESData. There are no validations in the esbacktestbysim object regarding the units of portfolio, VaR, and ES data. PortfolioData, VaRData, and ESData can be expressed as returns or as profits and losses.

Data Types: double | table | timetable

Value-at-risk (VaR) data, specified as a NumRows-by-NumVaRs numeric array, NumRows-by-NumVaRs table, or a NumRows-by-NumVaRs timetable with numeric columns. The VaRData input argument sets the VaRData property.

Negative VaRData values are allowed. However negative VaR values indicate a highly profitable portfolio that cannot lose money at the given VaR confidence level. The worst-case scenario at the given confidence level is still a profit.

Note

VaRData must be in the same units as PortfolioData and ESData. There are no validations in the esbacktestbysim object regarding the units of portfolio, VaR, and ES data. VaRData, PortfolioData, and ESData can be expressed as returns or as profits and losses.

Data Types: double | table | timetable

Expected shortfall data, specified as a NumRows-by-NumVaRs positive numeric array, NumRows-by-NumVaRs table, or NumRows-by-NumVaRs timetable with positive numeric columns containing ES data. The ESData input argument sets the ESData property.

Note

ESData data must be in the same units as PortfolioData and VaRData. There are no validations in the esbacktestbysim object regarding the units of portfolio, VaR, and ES data. ESData, PortfolioData, and VaRData can be expressed as returns or as profits and losses.

Data Types: double | table | timetable

Distribution name, specified as a string with a value of normal or t. The DistributionName input argument sets the 'Name' field of the Distribution property.

Data Types: string

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: ebts = esbacktestbysim(PortfolioData,VaRData,ESData,DistributionName,'VaRID','TotalVaR','VaRLevel',.99)

User-defined ID for PortfolioData input, specified as the comma-separated pair consisting of 'PortfolioID' and a character vector or string. The PortfolioID name-value pair argument sets the PortfolioID property.

If PortfolioData is a numeric array, the default value for PortfolioID is 'Portfolio'. If PortfolioData is a table, PortfolioID is set to the corresponding variable name in the table, by default.

Data Types: char | string

VaR identifier for VaRData columns, specified as the comma-separated pair consisting of 'VaRID' and a character vector, cell array of character vectors, string, or string array. Multiple VaRIDs are specified using a 1-by-NumVaRs (or NumVaRs-by-1) cell array of character vectors, or a string array with user-defined IDs for the VaRData columns. A single VaRID identifies a VaRData column and the corresponding ESData column. The VaRID name-value pair argument sets the VaRID property.

If NumVaRs = 1, the default value for VaRID is 'VaR'. If NumVaRs > 1, the default value is 'VaR1', 'VaR2', and so on. If VaRData is a table, 'VaRID' is set by default to the corresponding variable names in the table.

Data Types: char | cell | string

VaR confidence level, specified as a scalar with the comma-separated pair consisting of 'VaRLevel' and a numeric value between 0 and 1 or a 1-by-NumVaRs (or NumVaRs-by-1) numeric array with a numeric value between 0 and 1. The VaRLevel name-value pair argument sets the VaRLevel property.

Data Types: double

Means for the normal distribution, specified as a comma-separated pair consisting of 'Mean' and a numeric value or a NumRows-by-1 numeric array. The Mean name-value pair argument sets the 'Mean' field of the Distribution property.

Note

You set the Mean name-value pair argument only when the DistributionName input argument is specified as normal.

Data Types: double

Standard deviation for the normal distribution, specified as a comma-separated pair consisting of 'StandardDeviation' and a positive numeric value or a NumRows-by-1 array. The StandardDeviation name-value pair argument sets the 'StandardDeviation' field of the Distribution property.

Note

You set the StandardDeviation name-value pair argument only when the DistributionName input argument is specified as normal.

Data Types: double

Degrees of freedom for the t distribution, specified as a comma-separated pair consisting of 'DegreesOfFreedom' and an integer value ≥ 3. The DegreesOfFreedom name-value pair argument sets the 'DegreesOfFreedom' field of the Distribution property.

Note

The DegreesOfFreedom name-value pair argument is only set when the DistributionName input argument is specified as t. A value for DegreesOfFreedom is required when the value of DistributionName is t.

Data Types: double

Location parameters for the t distribution, specified as a comma-separated pair consisting of 'Location' and a numeric value or a NumRows-by-1 array. The Location name-value pair argument sets the'Location' field of the Distribution property.

Note

The Location name-value pair argument is only set when the DistributionName input argument is specified as t.

Data Types: double

Scale parameters for the t distribution, specified as a comma-separated pair consisting of 'Scale' and a positive numeric value or a NumRows-by-1 array. The Scale name-value pair argument sets the 'Scale' field of the Distribution property.

Note

The Scale name-value pair argument is only set when the DistributionName input argument is specified as t.

Data Types: double

Indicates if a simulation for statistical significance is run when you create an esbacktestbysim object, specified as a logical scalar with the comma-separated pair consisting of 'Simulate' and a value of true or false.

Data Types: logical

Properties

expand all

Portfolio data for the ES backtesting analysis, specified as a NumRows-by-1 numeric array containing a copy of the portfolio data.

Data Types: double

VaR data for the ES backtesting analysis, specified as a NumRows-by-NumVaRs numeric array containing a copy of the VaR data.

Data Types: double

Expected shortfall data for ES backtesting analysis, specified as a NumRows-by-NumVaRs numeric array containing a copy of the ESData.

Data Types: double

Distribution information, including distribution name and the associated distribution parameters, specified as a structure.

For a normal distribution, the Distribution structure has fields 'Name' (set to normal), 'Mean', and 'StandardDeviation', with values set to the corresponding inputs.

For a t distribution, the Distribution structure has fields 'Name' (set to t), 'DegreesOfFreedom', 'Location', and 'Scale', with values set to the corresponding inputs.

Data Types: struct

Portfolio identifier, specified as a string.

Data Types: string

VaR identifier, specified as a 1-by-NumVaRs string array containing the VaR IDs for the corresponding columns in VaRData.

Data Types: string

VaR level, specified as a 1-by-NumVaRs numeric array with values between 0 and 1 containing the VaR levels for the corresponding columns in VaRData.

Data Types: double

esbacktestbysim PropertySet or Modify Property from Command Line Using esbacktestbysim Modify Property Using Dot Notation
PortfolioDataYesNo
VaRDataYesNo
ESDataYesNo
DistributionYesNo
PortfolioIDYesYes
VaRIDYesYes
VaRLevelYesYes

Object Functions

summaryBasic expected shortfall (ES) report on failures and severity
runtestsRun all expected shortfall backtests (ES) for esbacktestbysim object
conditionalConditional expected shortfall (ES) backtest by Acerbi and Szekely
unconditionalUnconditional expected shortfall backtest by Acerbi and Szekely
quantileQuantile expected shortfall (ES) backtest by Acerbi and Szekely
simulateSimulate expected shortfall (ES) test statistics

Examples

collapse all

Open Live Script

esbacktestbysim takes in portfolio outcomes data, the corresponding value-at-risk (VaR) data, the expected shortfall (ES) data, and the Distribution information and returns an esbacktestbysim object.

Create an esbacktestbysim object and display the Distribution property. 

load ESBacktestBySimData
rng('default'); % for reproducibility
ebts = esbacktestbysim(Returns,VaR,ES,"t",...
       'DegreesOfFreedom',10,...
       'Location',Mu,...
       'Scale',Sigma,...
       'PortfolioID',"S&P",...
       'VaRID',["t(10) 95%","t(10) 97.5%","t(10) 99%"],...
       'VaRLevel',VaRLevel)
ebts = 
  esbacktestbysim with properties:

    PortfolioData: [1966x1 double]
          VaRData: [1966x3 double]
           ESData: [1966x3 double]
     Distribution: [1x1 struct]
      PortfolioID: "S&P"
            VaRID: ["t(10) 95%"    "t(10) 97.5%"    "t(10) 99%"]
         VaRLevel: [0.9500 0.9750 0.9900]


ebts.Distribution
ans = struct with fields:
                Name: "t"
    DegreesOfFreedom: 10
            Location: 0
               Scale: [1966x1 double]

ebts, the esbacktestbysim object, contains a copy of the given portfolio data (PortfolioData property), the given VaR data (VaRData property), the given ES data (ESData) property, and the given Distribution information. The object also contains all combinations of portfolio ID, VaR ID, and VaR level to be tested (PortfolioID, VaRID, and VaRLevel properties).

Run the tests using the ebts object. 

TestResults = runtests(ebts)
TestResults=3×6 table
    PortfolioID        VaRID        VaRLevel    Conditional    Unconditional    Quantile
    ___________    _____________    ________    ___________    _____________    ________

       "S&P"       "t(10) 95%"        0.95        reject          accept         reject 
       "S&P"       "t(10) 97.5%"     0.975        reject          reject         reject 
       "S&P"       "t(10) 99%"        0.99        reject          reject         reject

Change the PortfolioID property using dot notation. For more information on creating an esbacktestbysim object, see esbacktestbysim.

ebts.PortfolioID = 'S&P, 1996-2003'
ebts = 
  esbacktestbysim with properties:

    PortfolioData: [1966x1 double]
          VaRData: [1966x3 double]
           ESData: [1966x3 double]
     Distribution: [1x1 struct]
      PortfolioID: "S&P, 1996-2003"
            VaRID: ["t(10) 95%"    "t(10) 97.5%"    "t(10) 99%"]
         VaRLevel: [0.9500 0.9750 0.9900]

Run all tests using the updated esbacktestbysim object. 

runtests(ebts)
ans=3×6 table
      PortfolioID           VaRID        VaRLevel    Conditional    Unconditional    Quantile
    ________________    _____________    ________    ___________    _____________    ________

    "S&P, 1996-2003"    "t(10) 95%"        0.95        reject          accept         reject 
    "S&P, 1996-2003"    "t(10) 97.5%"     0.975        reject          reject         reject 
    "S&P, 1996-2003"    "t(10) 99%"        0.99        reject          reject         reject

References

[1] Acerbi, C., and B. Szekely. Backtesting Expected Shortfall. MSCI Inc. December, 2014.

[2] Basel Committee on Banking Supervision. Minimum Capital Requirements for Market Risk. January, 2016 (https://www.bis.org/bcbs/publ/d352.pdf).

See Also

| | | | | | | | | |

Topics

Introduced in R2017b

Risk Management Toolbox Documentation
Support