Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

esbacktest

Create esbacktest object to run suite of table-based expected shortfall (ES) backtests

Description

The general workflow is:

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

  2. Create an esbacktest object. For more information, see Create esbacktest and Properties.

  3. Use the summary function to generate a summary report for the number of observations, expected, and observed average severity ratio.

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

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

    • unconditionalNormal — Unconditional ES backtest assuming returns distribution is normal

    • unconditionalT — Unconditional ES backtest assuming returns distribution is t

    For more information, see Overview of Expected Shortfall Backtesting.

Creation

Syntax

ebt = esbacktest(PortfolioData,VaRData,ESData)
ebt = esbacktest(___,Name,Value)

Description

example

ebt = esbacktest(PortfolioData,VaRData,ESData) creates an esbacktest (ebt) object using portfolio outcomes data and corresponding value-at-risk (VaR) and ES data. The ebt object has the following properties:

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

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

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

  • PortfolioID — String containing the PortfolioID

  • VaRID1-by-NumVaRs string vector containing the VaRIDs for the corresponding columns in VaRData

  • VaRLevel1-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 esbacktest object regarding the units of these arguments.

  • If there are missing values (NaNs) in PortfolioData, VaRData, and ESData, the row of data is discarded before applying the tests. Therefore, a different number of observations is 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.

  • Because the critical values are precomputed, only certain numbers of observations, VaR levels, and test levels are supported.

    • The number of observations (number of rows in the data minus the number of missing values) must be from 200 through 5000.

    • The VaRLevel input argument must be between 0.90 and 0.99; the default is 0.95.

    • The TestLevel (test confidence level) input argument for the runtests, unconditionalNormal, and unconditionalT functions must be between 0.5 and 0.9999; the default is 0.95.

example

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

Input Arguments

expand all

Portfolio outcomes data, specified as a NumRows-by-1 numeric array, NumRows-by-1 numeric columns 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 must be in the same units as VaRData and ESData. PortfolioData, VaRData, and ESData can be expressed as returns or as profits and losses. There are no validations in the esbacktest object regarding the units of portfolio, VaR, and ES data.

Data Types: double | table | timetable

Value-at-risk (VaR) data, specified as a NumRows-by-NumVaRs numeric array, NumRows-by-NumVaRs numeric columns table, or 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. VaRData, PortfolioData, and ESData can be expressed as returns or as profits and losses. There are no validations in the esbacktest object regarding the units of portfolio, VaR, and ES data.

Data Types: double | table | timetable

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

Note

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

Data Types: double | table | timetable

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 single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: ebt = esbacktest(PortfolioData,VaRData,ESData,'VaRID','TotalVaR','VaRLevel',.99)

expand all

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 VaRID values are specified using a 1-by-NumVaRs (or NumVaRs-by-1) cell array of character vectors or a string vector 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 VaRData is a numeric array, the default value for VaRID is 'VaR'. If NumVaRs = 1 or NumVaRs > 1, the default value is 'VaR1', 'VaR2', and so on. If VaRData is a table, the value of VaRID is set to the corresponding variable names in the table, by default.

Data Types: char | cell | string

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

Data Types: double

Properties

expand all

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

Data Types: double

VaR data for 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

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.90 and 0.99, containing the VaR levels for the corresponding columns in VaRData.

Data Types: double

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

Object Functions

summaryBasic expected shortfall (ES) report on failures and severity
runtestsRun all expected shortfall (ES) backtests for esbacktest object
unconditionalNormalUnconditional expected shortfall (ES) backtest with critical values for normal distributions
unconditionalTUnconditional expected shortfall (ES) backtest with critical values for t distributions

Examples

expand all

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

Create an esbacktest object.

 load ESBacktestData
 ebt = esbacktest(Returns,VaRModel1,ESModel1,'VaRLevel',VaRLevel)
ebt = 

  esbacktest with properties:

    PortfolioData: [1966×1 double]
          VaRData: [1966×1 double]
           ESData: [1966×1 double]
      PortfolioID: "Portfolio"
            VaRID: "VaR"
         VaRLevel: 0.9750

ebt, the esbacktest object, contains a copy of the given portfolio data (PortfolioData property), the given VaR data (VaRData property), and the given ES data (ESData) property. 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 ebt object.

 runtests(ebt)
ans =

  1×5 table

    PortfolioID    VaRID    VaRLevel    UnconditionalNormal    UnconditionalT
    ___________    _____    ________    ___________________    ______________

    "Portfolio"    "VaR"    0.975       reject                 reject        

Change the PortfolioID and VaRID properties using dot notation. For more information on creating an esbacktest object, see esbacktest.

ebt.PortfolioID = 'S&P';
ebt.VaRID = 'Normal at 97.5%';
disp(ebt)
  esbacktest with properties:

    PortfolioData: [1966×1 double]
          VaRData: [1966×1 double]
           ESData: [1966×1 double]
      PortfolioID: "S&P"
            VaRID: "Normal at 97.5%"
         VaRLevel: 0.9750

Run all tests using the updated esbacktest object.

 runtests(ebt)
ans =

  1×5 table

    PortfolioID          VaRID          VaRLevel    UnconditionalNormal    UnconditionalT
    ___________    _________________    ________    ___________________    ______________

    "S&P"          "Normal at 97.5%"    0.975       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).

Introduced in R2017b

Was this topic helpful?