esbacktestbysim

R2026b

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

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)

   • minBiasAbsolute — Minimally biased absolute test of Acerbi-Szekely (2017)

   • minBiasRelative — Minimally biased relative test of Acerbi-Szekely (2017)

   For more information, see Overview of Expected Shortfall Backtesting.

Creation

Syntax

ebts = esbacktestbysim(PortfolioData,VaRData,ESData,DistributionName)

ebts = esbacktestbysim(PortfolioData,VaRData,ESData,pdObj)

ebts = esbacktestbysim(___,Name,Value)

Description

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

• conditional

• unconditional

• quantile

• minBiasAbsolute

• minBiasRelative

The ebts output has these properties:

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

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

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

• Distribution — structure containing the model information. For example, if you specify DistributionName as "normal", then Distribution has a field Name, with value "normal", as well as fields Mean and StandardDeviation, with values set to the corresponding inputs.

• PortfolioID — String containing PortfolioID

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

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

ebts = esbacktestbysim(PortfolioData,VaRData,ESData,pdObj) creates the object and simulates the scenarios for the vector pdObj of probability distribution objects.

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=0.99). You can specify multiple name-value pairs.

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 rows in PortfolioData, VaRData, ESData, or Distribution that contain missing (NaN) values, then the function discards those rows of data before applying the tests. To determine if the function discarded rows, use the Missing column of the summary report.

Input Arguments

PortfolioData — Portfolio outcomes data

NumRows-by-1 numeric array | NumRows-by-1 numeric columns table | NumRows-by-1 numeric columns timetable

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

VaRData — Value-at-risk (VaR) data

NumRows-by-NumVaRs numeric array | NumRows-by-NumVaRs table with numeric columns | NumRows-by-NumVaRs timetable with numeric columns

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

ESData — Expected shortfall data

NumRows-by-NumVaRs positive numeric array | NumRows-by-NumVaRs table with positive numeric columns | NumRows-by-NumVaRs timetable with positive numeric columns

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

DistributionName — Distribution name

"normal" | "t" | "empirical"

Distribution name, specified as "normal", "t", or "empirical".

• "normal" — Normal distribution

• "t" — t distribution

• "empirical" — Empirical distribution

pdObj — Probability distribution

NumRows-by-1 NormalDistribution object vector | NumRows-by-1 tLocationScaleDistribution object vector | NumRows-by-1 EmpiricalDistribution object vector

Probability distribution, specified as a NumRows-by-1 NormalDistribution, tLocationScaleDistribution, or EmpiricalDistribution object vector.

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: ebts = esbacktestbysim(PortfolioData,VaRData,ESData,DistributionName,VaRID="TotalVaR",VaRLevel=0.99)

PortfolioID — User-defined ID

character vector | string

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

VaRID — VaR identifier

character vector | cell array of character vectors | string | string array

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

VaRLevel — VaR confidence level

0.95 (default) | numeric or numeric array with values between 0 and 1

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

Mean — Means for normal distribution

0 (default) | numeric | numeric array

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

StandardDeviation — Standard deviation for normal distribution

1 (default) | positive numeric | positive numeric array

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

DegreesOfFreedom — Degrees of freedom for t distribution

integer ≥ 3

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 — Location parameters for t distribution

0 (default) | numeric | numeric array

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 — Scale parameters for t distribution

1 (default) | positive numeric

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

Simulate — Indicates if simulation for statistical significance is run

true (default) | values are true or false

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

InputData — Empirical distribution data

numeric array

Empirical distribution data, specified as a numeric array. The row dimension of InputData must match the length of PortfolioData.

Note

The InputData name-value argument is set only when the DistributionName input argument is specified as "empirical".

Properties

PortfolioData — Portfolio data for ES backtesting analysis

numeric array

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

Data Types: double

VaRData — VaR data for ES backtesting analysis

numeric array

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

Data Types: double

ESData — Expected shortfall data

numeric array

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

Data Types: double

Distribution — Distribution information

structure

Distribution information returned as a structure.

Data Types: struct

PortfolioID — Portfolio identifier

string

Portfolio identifier, returned as a string.

Data Types: string

VaRID — VaR identifier

string | string array

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

Data Types: string

VaRLevel — VaR level

numeric array with values between 0 and 1

VaR level, returned 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 Property	Set or Modify Property from Command Line Using esbacktestbysim	Modify Property Using Dot Notation
PortfolioData	Yes	No
VaRData	Yes	No
ESData	Yes	No
Distribution	Yes	No
PortfolioID	Yes	Yes
VaRID	Yes	Yes
VaRLevel	Yes	Yes

Object Functions

summary	Report on failures and severity for basic expected shortfall (ES) using simulations
runtests	Run all expected shortfall backtests (ES) for esbacktestbysim object
conditional	Conditional expected shortfall (ES) backtest by Acerbi and Szekely
unconditional	Unconditional expected shortfall backtest by Acerbi and Szekely
quantile	Quantile expected shortfall (ES) backtest by Acerbi and Szekely
minBiasRelative	Minimally biased relative test for Expected Shortfall (ES) backtest by Acerbi-Szekely
minBiasAbsolute	Minimally biased absolute test for Expected Shortfall (ES) backtest by Acerbi-Szekely
simulate	Simulate expected shortfall (ES) test statistics

Examples

Create esbacktestbysim Object and Run ES Backtests

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: [1966×1 double]
          VaRData: [1966×3 double]
           ESData: [1966×3 double]
     Distribution: [1×1 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: [1966×1 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×8 table
    PortfolioID        VaRID        VaRLevel    Conditional    Unconditional    Quantile    MinBiasAbsolute    MinBiasRelative
    ___________    _____________    ________    ___________    _____________    ________    _______________    _______________

       "S&P"       "t(10) 95%"        0.95        reject          accept         reject         accept             reject     
       "S&P"       "t(10) 97.5%"     0.975        reject          reject         reject         reject             reject     
       "S&P"       "t(10) 99%"        0.99        reject          reject         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: [1966×1 double]
          VaRData: [1966×3 double]
           ESData: [1966×3 double]
     Distribution: [1×1 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×8 table
      PortfolioID           VaRID        VaRLevel    Conditional    Unconditional    Quantile    MinBiasAbsolute    MinBiasRelative
    ________________    _____________    ________    ___________    _____________    ________    _______________    _______________

    "S&P, 1996-2003"    "t(10) 95%"        0.95        reject          accept         reject         accept             reject     
    "S&P, 1996-2003"    "t(10) 97.5%"     0.975        reject          reject         reject         reject             reject     
    "S&P, 1996-2003"    "t(10) 99%"        0.99        reject          reject         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).

Version History

Introduced in R2017b

R2026b: Specify distribution as a vector of probability distribution objects

You can specify a vector of probability distribution objects for the pdObj input argument.