esbacktestbyde

Create esbacktestbyde object to run suite of Du and Escanciano expected shortfall (ES) backtests

Description

The general workflow is:

Load or generate the data for the ES backtesting analysis.
Create an esbacktestbyde object. For more information, see Create esbacktestbyde and Properties.
Use the summary function to generate a summary report on the failures and severities.
Use the runtests function to run all tests at once.
For additional test details, run the following individual tests:
- unconditionalDE — Unconditional ES backtest by Du-Escanciano
- conditionalDE — Conditional ES backtest by Du-Escanciano
simulate — Simulate critical values for test statistics

For more information, see Overview of Expected Shortfall Backtesting and Workflow for Expected Shortfall (ES) Backtesting by Du and Escanciano.

Creation

Syntax

ebtde = esbacktestbyde(PortfolioData,DistributionName)

ebtde = esbacktestbyde(___,Name,Value)

Description

ebtde = esbacktestbyde(PortfolioData,DistributionName) creates an esbacktestbyde (ebtde) object using portfolio outcomes data and model distribution information. The esbacktestbyde object has the following properties:

PortfolioData — NumRows-by-1 numeric array or NumRows-by-1 table or timetable with a numeric column containing portfolio outcomes data.
VaRData — Computed VaR data using distribution information from PortfolioData, returned as a NumRows-by-NumVaRs numeric array.
ESData — Computed ES data using distribution information from PortfolioData, returned as a NumRows-by-NumVaRs numeric array.
Distribution — Model distribution information, returned as a structure.
PortfolioID — User-defined portfolio ID.
VaRID — VaRIDs for the corresponding column in PortfolioData.
VaRLevel — VaRLevel for the corresponding columns in PortfolioData.

example

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

example

Input Arguments

expand all

`PortfolioData` — Portfolio outcome data
`NumRows`-by-`1` numeric array | `NumRows`-by-`1` table of numeric columns | `NumRows`-by-`1` timetable with one numeric column

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

Unlike other ES backtesting classes, the esbacktestbyde does not require VaR data or ES data inputs. The distribution information from PortfolioData is sufficient to run the tests. esbacktestbyde uses the distribution information to apply the cumulative distribution function to the portfolio data and map it into the (0,1) interval. The ES backtests are applied to the mapped data.

Note

Before applying the tests, the function discards rows with missing values (NaN) in the PortfolioData or Distribution parameters. Therefore, the reported number of observations equals the original number of rows minus the number of missing values.

Data Types: double | table | timetable

`DistributionName` — Model distribution name
character vector with a value of `'normal'` or `'t'` | string with a value of `"normal"` of `"t"`

Model distribution name for ES backtesting analysis, specified as a character vector with a value of 'normal' or 't' or string with a value of "normal" or "t".

Data Types: char | string

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: ebtde = esbacktestbyde(PortfolioData,"t",'DegreesOfFreedom',10,'Location',Mu,'Scale',Sigma,'PortfolioID',"S&P",'VaRID',["t(10) 95%","t(10) 97.5%","t(10) 99%"],'VaRLevel',VaRLevel)

Name-Value Pairs for 'normal' or 't' Distributions

expand all

`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 or timetable, 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 the VaR model, specified as the comma-separated pair consisting of 'VaRID' and a character vector, cell array of character vectors, string, or string array.

You can specify multiple VaRID values by using a 1-by-NumVaRs (or NumVaRs-by-1) cell array of character vectors or a string vector with user-defined IDs for the different VaR levels 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.

Data Types: char | cell | string

`VaRLevel` — VaR confidence level
`0.95` (default) | numeric between `0` and `1`

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

Data Types: double

`Simulate` — Indicates if simulation for statistical significance of tests runs
`true` (default) | scalar logical with a value of `true` or `false`

Indicates if simulation for statistical significance of tests runs when an esbacktestbyde object is created, specified as the comma-separated pair consisting of 'Simulate' and a scalar logical value.

Data Types: logical

Name-Value Pairs for 'normal' Distributions

expand all

`Mean` — Means for the normal distribution
`0` (default) | vector

Means for the normal distribution, specified as the comma-separated pair consisting of 'Mean' and a NumRows-by-1 vector. This parameter is used only when DistributionName is 'normal'.

Data Types: double

`StandardDeviation` — Standard deviations
`1` (default) | positive vector

Standard deviations, specified as the comma-separated pair consisting of 'StandardDeviation' and a NumRows-by-1 positive vector. This parameter is only used when DistributionName is "normal".

Data Types: double

Name-Value Pairs for 't' Distributions

expand all

`DegreesOfFreedom` — Degrees of freedom for `'t'` distribution
scalar integer ≥ `3`

Degrees of freedom for 't' distribution, specified as the comma-separated pair consisting of 'DegreesOfFreedom' and a scalar integer ≥ 3.

Note

You must set this name-value parameter when DistributionName is 't'.

Data Types: double

`Location` — Location parameters for `'t'` distribution
`0` (default) | vector

Location parameters for 't' distribution, specified as the comma-separated pair consisting of 'Location' and a NumRows-by-1 vector. This parameter is used only when DistributionName is 't'.

Data Types: double

`Scale` — Scale parameters for `'t'` distribution
`1` (default) | positive vector

Scale parameters for 't' distribution, specified as the comma-separated pair consisting of 'Scale' and a NumRows-by-1 positive vector. This parameter is used only when DistributionName is 't'.

Data Types: double

Properties

expand all

`PortfolioData` — Portfolio data for ES backtesting analysis
numeric array

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

Data Types: double

`VaRData` — VaR data computed using distribution information
numeric array

VaR data computed using distribution information, returned as a NumRows-by-NumVaRs numeric array.

Data Types: double

`ESData` — ES data computed using distribution information
numeric array

ES data computed using distribution information, returned as a NumRows-by-NumVaRs numeric array.

Data Types: double

`Distribution` — Model distribution information
struct

Model distribution information, returned as a struct.

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

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

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 ES model, where NumVaRs is the number of VaR levels.

Data Types: string

`VaRLevel` — VaR level
numeric array with values between `0.90` and `0.99`

VaR level, returned as a 1-by-NumVaRs numeric array.

Data Types: double

`esbacktestbyde` Property	Set or Modify Property from Command Line Using `esbacktestbyde`	Modify Property Using Dot Notation
`PortfolioData`	Yes	No
`VaRData`	No	No
`ESData`	No	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 distributions
`runtests`	Run all expected shortfall (ES) backtests for `esbacktestbyde` object
`unconditionalDE`	Unconditional Du-Escanciano (DE) expected shortfall (ES) backtest
`conditionalDE`	Conditional Du-Escanciano (DE) expected shortfall (ES) backtest
`simulate`	Simulate Du-Escanciano (DE) expected shortfall (ES) test statistics

Examples

collapse all

Create an `esbacktestbyde` Object and Run ES Backtests

Open Live Script

Create an esbacktestbyde object for a t model with 10 degrees of freedom at three different VaR levels, and then run Du and Escanciano ES backtests.

load ESBacktestDistributionData.mat
    rng('default'); % For reproducibility
    ebtde = esbacktestbyde(Returns,"t",...
       'DegreesOfFreedom',T10DoF,...
       'Location',T10Location,...
       'Scale',T10Scale,...
       'PortfolioID',"S&P",...
       'VaRID',["t(10) 95%","t(10) 97.5%","t(10) 99%"],...
       'VaRLevel',VaRLevel);
  runtests(ebtde)

ans=3×5 table
    PortfolioID        VaRID        VaRLevel    ConditionalDE    UnconditionalDE
    ___________    _____________    ________    _____________    _______________

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

Create Two `esbacktestbyde` Objects and Run ES Backtests

Open Live Script

Create two esbacktestbyde objects, one with a normal distribution and another with a t distribution with 5 degrees of freedom, at three different VaR levels. Then run Du and Escanciano ES backtests using runtests.

load ESBacktestDistributionData.mat
    rng('default'); % For reproducibility
    ebtde1 = esbacktestbyde(Returns,"normal",...
       'Mean',NormalMean,...
       'StandardDeviation',NormalStd,...
       'PortfolioID',"S&P",...
       'VaRID',["Normal 95%","Normal 97.5%","Normal 99%"],...
       'VaRLevel',VaRLevel);
    ebtde2 = esbacktestbyde(Returns,"t",...
       'DegreesOfFreedom',T5DoF,...
       'Location',T5Location,...
       'Scale',T5Scale,...
       'PortfolioID',"S&P",...
       'VaRID',["t(5) 95%","t(5) 97.5%","t(5) 99%"],...
       'VaRLevel',VaRLevel);

Concatenate results in a single table.

t = [runtests(ebtde1);runtests(ebtde2)];
disp(t)

    PortfolioID        VaRID         VaRLevel    ConditionalDE    UnconditionalDE
    ___________    ______________    ________    _____________    _______________

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

References

[1] Du, Z., and J. C. Escanciano. "Backtesting Expected Shortfall: Accounting for Tail Risk." Management Science. Vol. 63, Issue 4, April 2017.

[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 R2019b

esbacktestbyde

Description

Creation

Syntax

Description

Input Arguments

`PortfolioData` — Portfolio outcome data
`NumRows`-by-`1` numeric array | `NumRows`-by-`1` table of numeric columns | `NumRows`-by-`1` timetable with one numeric column

`DistributionName` — Model distribution name
character vector with a value of `'normal'` or `'t'` | string with a value of `"normal"` of `"t"`

`PortfolioID` — User-defined ID
character vector | string

`VaRID` — VaR identifier
character vector | cell array of character vectors | string | string array

`VaRLevel` — VaR confidence level
`0.95` (default) | numeric between `0` and `1`

`Simulate` — Indicates if simulation for statistical significance of tests runs
`true` (default) | scalar logical with a value of `true` or `false`

`Mean` — Means for the normal distribution
`0` (default) | vector

`StandardDeviation` — Standard deviations
`1` (default) | positive vector

`DegreesOfFreedom` — Degrees of freedom for `'t'` distribution
scalar integer ≥ `3`

`Location` — Location parameters for `'t'` distribution
`0` (default) | vector

`Scale` — Scale parameters for `'t'` distribution
`1` (default) | positive vector

Properties

`PortfolioData` — Portfolio data for ES backtesting analysis
numeric array

`VaRData` — VaR data computed using distribution information
numeric array

`ESData` — ES data computed using distribution information
numeric array

`Distribution` — Model distribution information
struct

`PortfolioID` — Portfolio identifier
string

`VaRID` — VaR identifier
string | string array

`VaRLevel` — VaR level
numeric array with values between `0.90` and `0.99`

Object Functions

Examples

Create an `esbacktestbyde` Object and Run ES Backtests

Create Two `esbacktestbyde` Objects and Run ES Backtests

References

Version History

See Also

Topics

esbacktestbyde

Description

Creation

Syntax

Description

Input Arguments

PortfolioData — Portfolio outcome data NumRows-by-1 numeric array | NumRows-by-1 table of numeric columns | NumRows-by-1 timetable with one numeric column

DistributionName — Model distribution name character vector with a value of 'normal' or 't' | string with a value of "normal" of "t"

PortfolioID — User-defined ID character vector | string

VaRID — VaR identifier character vector | cell array of character vectors | string | string array

VaRLevel — VaR confidence level 0.95 (default) | numeric between 0 and 1

Simulate — Indicates if simulation for statistical significance of tests runs true (default) | scalar logical with a value of true or false

Mean — Means for the normal distribution 0 (default) | vector

StandardDeviation — Standard deviations 1 (default) | positive vector

DegreesOfFreedom — Degrees of freedom for 't' distribution scalar integer ≥ 3

Location — Location parameters for 't' distribution 0 (default) | vector

Scale — Scale parameters for 't' distribution 1 (default) | positive vector

Properties

PortfolioData — Portfolio data for ES backtesting analysis numeric array

VaRData — VaR data computed using distribution information numeric array

ESData — ES data computed using distribution information numeric array

Distribution — Model distribution information struct

PortfolioID — Portfolio identifier string

VaRID — VaR identifier string | string array

VaRLevel — VaR level numeric array with values between 0.90 and 0.99

Object Functions

Examples

Create an esbacktestbyde Object and Run ES Backtests

Create Two esbacktestbyde Objects and Run ES Backtests

References

Version History

See Also

Topics

`PortfolioData` — Portfolio outcome data
`NumRows`-by-`1` numeric array | `NumRows`-by-`1` table of numeric columns | `NumRows`-by-`1` timetable with one numeric column

`DistributionName` — Model distribution name
character vector with a value of `'normal'` or `'t'` | string with a value of `"normal"` of `"t"`

`PortfolioID` — User-defined ID
character vector | string

`VaRID` — VaR identifier
character vector | cell array of character vectors | string | string array

`VaRLevel` — VaR confidence level
`0.95` (default) | numeric between `0` and `1`

`Simulate` — Indicates if simulation for statistical significance of tests runs
`true` (default) | scalar logical with a value of `true` or `false`

`Mean` — Means for the normal distribution
`0` (default) | vector

`StandardDeviation` — Standard deviations
`1` (default) | positive vector

`DegreesOfFreedom` — Degrees of freedom for `'t'` distribution
scalar integer ≥ `3`

`Location` — Location parameters for `'t'` distribution
`0` (default) | vector

`Scale` — Scale parameters for `'t'` distribution
`1` (default) | positive vector

`PortfolioData` — Portfolio data for ES backtesting analysis
numeric array

`VaRData` — VaR data computed using distribution information
numeric array

`ESData` — ES data computed using distribution information
numeric array

`Distribution` — Model distribution information
struct

`PortfolioID` — Portfolio identifier
string

`VaRID` — VaR identifier
string | string array

`VaRLevel` — VaR level
numeric array with values between `0.90` and `0.99`

Create an `esbacktestbyde` Object and Run ES Backtests

Create Two `esbacktestbyde` Objects and Run ES Backtests