| Title: | At-Risk |
| Version: | 0.2.0 |
| Description: | The at-Risk (aR) approach is based on a two-step parametric estimation procedure that allows to forecast the full conditional distribution of an economic variable at a given horizon, as a function of a set of factors. These density forecasts are then be used to produce coherent forecasts for any downside risk measure, e.g., value-at-risk, expected shortfall, downside entropy. Initially introduced by Adrian et al. (2019) <doi:10.1257/aer.20161923> to reveal the vulnerability of economic growth to financial conditions, the aR approach is currently extensively used by international financial institutions to provide Value-at-Risk (VaR) type forecasts for GDP growth (Growth-at-Risk) or inflation (Inflation-at-Risk). This package provides methods for estimating these models. Datasets for the US and the Eurozone are available to allow testing of the Adrian et al. (2019) model. This package constitutes a useful toolbox (data and functions) for private practitioners, scholars as well as policymakers. |
| Depends: | R (≥ 3.5.0) |
| License: | GPL-3 |
| Encoding: | UTF-8 |
| LazyData: | true |
| RoxygenNote: | 7.2.3 |
| Date: | 2025-01-07 |
| Imports: | stats, quantreg, sn, dfoptim, ggplot2, ggridges |
| Author: | Quentin Lajaunie [aut, cre], Guillaume Flament [aut, ctb], Christophe Hurlin [aut], Souzan Kazemi [rev] |
| Maintainer: | Quentin Lajaunie <quentin_lajaunie@hotmail.fr> |
| NeedsCompilation: | no |
| Packaged: | 2025-01-14 18:06:08 UTC; quentin.lajaunie_ver |
| Repository: | CRAN |
| Date/Publication: | 2025-01-14 18:50:01 UTC |
Historical data for the US (GDP and Financial Conditions) from 1973:Q1 to 2020:Q1
Description
data_euro contains: - Quarterly annualized GDP, from 1973:Q1 to 2020:Q1 - National Financial Condition Index of the US, from 1973:Q1 to 2020:Q1 Sources : https://www.chicagofed.org/research/data/nfci/current-data https://fred.stlouisfed.org/series/A191RL1Q225SBEA
Usage
data("data_US")Format
A data frame with 189 observations on the following 3 variables.
DATEVector of dates.
GDPVector of annualized PIB.
NFCIHistorical values of the National Financial Condition Index (NFCI).
Historical data for the eurozone (GDP and Financial Conditions) from 2008:Q4 to 2022:Q3
Description
data_euro contains: - Quarterly annualized GDP, from 2008:Q4 to 2022:Q3 - Financial Condition Index of the euro Area, from 2008:Q4 to 2022:Q3 - Composite Indicator of Systemic Stress, from 2008:Q4 to 2022:Q3 Sources : https://sdw.ecb.europa.eu/browseExplanation.do?node=9689686 https://webstat.banque-france.fr/ws_wsen/browseSelection.do?node=DATASETS_FCI https://fred.stlouisfed.org/series/CLVMEURSCAB1GQEA19
Usage
data("data_euro")Format
A data frame with 56 observations on the following 4 variables.
DATEVector of dates.
GDPVector of annualized PIB.
FCIHistorical values of the Financial Condition Index (FCI).
CISSHistorical values of the Composite Indicator of Systemic Stress (CISS).
Historical parameters (skew-t) for the US from 1973:Q1 to 2020:Q1
Description
Data corresponding to historical parameters estimated over the period 1973:Q1 to 2020:Q1, based on the data_US file in the matrisk package, with the skew-t distribution, and calculated with the f_param_histo function. data_param_histo_US has been calculated using c(0.05,0.25,0.75,0.95) for the qt_trgt parameter, PIB_us_forward_1 as the dependent variable, NFCI_us_lag_1 as the explanatory variable, "skew-t" for the type_function parameter and c(0, 1, -0.5, 1.3) for the starting_values.
Usage
data("data_param_histo_US")Format
A matrix with 188 rows and 4 columns for the four parameters of the skew-t distribution).
Expected Shortfall
Description
The function allows to calculate Expected-shortfall for a given distribution. It takes as parameters alpha (risk level), a distribution and the parameters associated with this distribution. For example, for a normal distribution, the user must enter the mean and the standard deviation. Currently, the function can calculate the Expected-shortfall for the normal distribution, the skew-normal distribution and for the skew-t distribution (Azzalini and Capitianio, 2003)
Usage
f_ES(alpha, type_function, params, accuracy = 0.005)
Arguments
alpha |
Numeric argument for Expected-Shortfall, between 0 and 1 |
type_function |
String argument : "gaussian" for normal distribution, "skew-gaussian" for Skew-Normal Distribution or "skew-t" for t-student distribution |
params |
Numeric vector containing parameters of the distribution |
accuracy |
Scalar value which regulates the accuracy of the ES (default value 1e-05) |
Value
Numeric value for the expected-shortfall given the distribution and the alpha risk.
References
Azzalini, Adelchi, and Antonella Capitanio. "Distributions generated by perturbation of symmetry with emphasis on a multivariate skew t‐distribution." Journal of the Royal Statistical Society: Series B (Statistical Methodology) 65.2 (2003): 367-389.
Azzalini, Adelchi, and Maintainer Adelchi Azzalini. "Package ‘sn’." The skew-normal and skew-t distributions (2015): 1-3.
Examples
f_ES(0.95, "gaussian", params=c(0,1))
f_ES(0.95, "gaussian", params=c(0,1), accuracy=1e-05)
f_ES(0.95, "gaussian", params=c(0,1), accuracy=1e-04)
Value-at-Risk
Description
The function allows to calculate Value-at-Risk for a given distribution. It takes as parameters alpha (risk level), a distribution and the parameters associated with this distribution. For example, for a normal distribution, the user must enter the mean and the standard deviation. Currently, the function can calculate the Value-at-Risk for the normal distribution and for the skew-t distribution (Azzalini and Capitianio, 2003)
Usage
f_VaR(alpha, type_function, params)
Arguments
alpha |
Numeric argument for Expected-Shortfall, between 0 and 1 |
type_function |
String argument : "gaussian" for Normal Distribution, "skew-gaussian" for Skew-Normal Distribution or "skew-t" for T-student Distribution |
params |
Numeric vector containing parameters of the distribution |
Value
Numeric value for the Value-at-Risk given the distribution and the alpha risk
References
Azzalini, Adelchi, and Antonella Capitanio. "Distributions generated by perturbation of symmetry with emphasis on a multivariate skew t‐distribution." Journal of the Royal Statistical Society: Series B (Statistical Methodology) 65.2 (2003): 367-389.
Azzalini, Adelchi, and Maintainer Adelchi Azzalini. "Package ‘sn’." The skew-normal and skew-t distributions (2015): 1-3.
Examples
f_VaR(0.95, "gaussian", params=c(0,1))
Estimation of quantiles
Description
Predicted values based on each quantile regression (Koenker and Basset, 1978), at time=t_trgt, for each quantile in qt_trgt.
Usage
f_compile_quantile(qt_trgt, v_dep, v_expl, newdata = NULL)
Arguments
qt_trgt |
Numeric vector, dim k, of k quantiles for different qt-estimations |
v_dep |
Numeric vector of the dependent variable |
v_expl |
Numeric vector or matrix of the (k) explanatory covariate(s) |
newdata |
Numeric optional vector of the (k) out of sample explanatory covariate(s) |
Value
A list with the following elements:
quantile_target |
Numeric vector, dim k, of k quantiles for different qt-estimations. |
results_qt |
Numeric matrix with all the predicted values based on each quantile regression, where each column corresponds to a quantile target. This matrix includes out-of-sample values of the dependent variable if 'newdata' is specified. |
References
Koenker, Roger, and Gilbert Bassett Jr. "Regression quantiles." Econometrica: journal of the Econometric Society (1978): 33-50.
Examples
# Import data
data("data_euro")
# Data process
PIB_euro_forward_4 = data_euro["GDP"][c(5:length(data_euro["GDP"][,1])),]
FCI_euro_lag_4 = data_euro["FCI"][c(1:(length(data_euro["GDP"][,1]) - 4)),]
CISS_euro_lag_4 = data_euro["CISS"][c(1:(length(data_euro["GDP"][,1]) - 4)),]
quantile_target <- as.vector(c(0.10,0.25,0.75,0.90))
results_quantile_reg <- f_compile_quantile(qt_trgt=quantile_target,
v_dep=PIB_euro_forward_4,
v_expl=as.matrix(cbind(FCI_euro_lag_4, CISS_euro_lag_4)))
Distribution
Description
This function is used to estimate the parameters of the distribution for each period (mean and standard deviation for Gaussian Distribution, xi, omega and alpha for Skew-Normal Distribution, and xi, omega, alpha, and nu for t-student Distribution) based on the quantile regression results (Koenker and Basset, 1978). See Adrian et al. (2019) and Adrian et al. (2022) for more details on the estimation steps.
Usage
f_distrib(type_function, compile_qt, starting_values, tolerance = 1e-06)
Arguments
type_function |
String argument : "gaussian" for Normal Distribution, "skew-gaussian" for Skew-Normal Distribution or "skew-t" for t-student Distribution |
compile_qt |
List containing the results of f_compile_quantile function |
starting_values |
Numeric vector with initial values for optimization |
tolerance |
Numeric optional for the convergence tolerance. Iteration is terminated when the absolute difference in function value between successive iteration is below tol (default value = 1.e-06). |
Value
Dataframe with the parameters of the distribution for each period. This dataframe includes out of sample values of the paramateres if newdata has been specified in f_compile_quantile.
References
Adrian, Tobias, Nina Boyarchenko, and Domenico Giannone. "Vulnerable growth." American Economic Review 109.4 (2019): 1263-89.
Adrian, Tobias, et al. "The term structure of growth-at-risk." American Economic Journal: Macroeconomics 14.3 (2022): 283-323.
Koenker, Roger, and Gilbert Bassett Jr. "Regression quantiles." Econometrica: journal of the Econometric Society (1978): 33-50.
Azzalini, Adelchi. "The skew-normal and related families." Vol. 3. Cambridge University Press (2013).
Examples
# Import data
data("data_euro")
# Data process
PIB_euro_forward_4 = data_euro["GDP"][c(5:length(data_euro["GDP"][,1])),]
FCI_euro_lag_4 = data_euro["FCI"][c(1:(length(data_euro["GDP"][,1]) - 4)),]
CISS_euro_lag_4 = data_euro["CISS"][c(1:(length(data_euro["GDP"][,1]) - 4)),]
# for a gaussian
quantile_target <- as.vector(c(0.25,0.75))
results_quantile_reg <- f_compile_quantile(qt_trgt=quantile_target,
v_dep=PIB_euro_forward_4,
v_expl=cbind(FCI_euro_lag_4, CISS_euro_lag_4))
results_g <- f_distrib(type_function="gaussian",
compile_qt=results_quantile_reg,
starting_values=c(0, 1))
# for a skew-t
quantile_target <- as.vector(c(0.10,0.25,0.75,0.90))
results_quantile_reg <- f_compile_quantile(qt_trgt=quantile_target,
v_dep=PIB_euro_forward_4,
v_expl=cbind(FCI_euro_lag_4, CISS_euro_lag_4))
results <- f_distrib(type_function="skew-t",
compile_qt=results_quantile_reg,
starting_values=c(0, 0.5, 0, 2), tolerance=1e-05)
Historical parameters
Description
This function allows to calculate historical historical parameters and the VaR and ES for each historical period.
Usage
f_histo_RM(param_histo, type_function, alpha)
Arguments
param_histo |
Dataframe with the parameters of the distribution for each period. |
type_function |
String argument : "gaussian" for Normal Distribution, "skew-gaussian" for Skew-Normal Distribution or "skew-t" for t-student distribution |
alpha |
Numeric argument for Expected-Shortfall, between 0 and 1 |
Value
A list with historical estimated coefficients, VaR(alpha) and ES(alpha)
Examples
data("data_euro")
# Data process
PIB_euro_forward_4 = data_euro["GDP"][c(5:length(data_euro["GDP"][,1])),]
FCI_euro_lag_4 = data_euro["FCI"][c(1:(length(data_euro["GDP"][,1]) - 4)),]
CISS_euro_lag_4 = data_euro["CISS"][c(1:(length(data_euro["GDP"][,1]) - 4)),]
results_quantile_reg <- f_compile_quantile(qt_trgt=as.vector(c(0.10,0.25,0.75,0.90)),
v_dep=PIB_euro_forward_4,
v_expl=cbind(FCI_euro_lag_4, CISS_euro_lag_4))
histo_param <- f_distrib(type_function="skew-t",
compile_qt=results_quantile_reg,
starting_values=c(0, 1, -0.5, 1.3))
# for a skew-t
results_s <- f_histo_RM(param_histo = histo_param,
type_function="skew-t",
alpha=0.95)
Estimation of quantiles using the Nadaraya-Watson estimator with a product kernel
Description
This function performs quantile regression using the Nadaraya-Watson estimator with a product kernel. It computes the weights using a Gaussian kernel for each dimension of the explanatory variables and then estimates the quantile using a weighted average of the observed responses.
Usage
f_nadaraya_watson_quantile(v_dep, v_expl, qt_trgt, bandwidth)
Arguments
v_dep |
Numeric vector of the dependent variable |
v_expl |
Numeric vector or matrix of the (k) explanatory covariate(s) |
qt_trgt |
Numeric vector, dim k, of k quantiles for different qt-estimations |
bandwidth |
Numeric value specifying the bandwidth for the Gaussian kernel |
Value
Numeric matrix with all the predicted values based on each quantile regression, where each column corresponds to a quantile target.
Examples
# Data process
set.seed(123)
Y <- as.vector(rnorm(100))
X <- matrix(rnorm(200), ncol = 2)
quantile_target <- c(0.1, 0.5, 0.9)
bandwidth_value <- 0.5
results_qt <- f_nadaraya_watson_quantile(v_dep=Y,
v_expl=X,
qt_trgt=quantile_target,
bandwidth=bandwidth_value)
Plot of historical distributions in 2D
Description
This function allows to create a plot in 2D of historical distributions.
Usage
f_plot_distrib_2D(
m_param_histo,
type_function,
v_date = NULL,
v_var_dep,
x_lab,
y_lab,
x_min = NULL,
x_max = NULL,
color_theme = c("#bd8e42", "gray30", "#876b3a", "khaki1")
)
Arguments
m_param_histo |
Numeric matrix containing the parameters of the f_param_histo function |
type_function |
String argument specifying the distribution type (gaussian, skew-gaussian or skew-t) |
v_date |
Vector optional of dates containing the full sample's dates (default value : daily dates starting from "1970-01-01") |
v_var_dep |
Numeric vector containing the realization of the dependent variable |
x_lab |
String optional argument for the x axis title (default value = x) |
y_lab |
String optionalargument for the y axis title (default value = y) |
x_min |
Numeric optional argument (default value = VaR 97.5) |
x_max |
Numeric optional argument (default value = VaR 2.5) |
color_theme |
A character vector specifying the color theme to use (default value c("#bd8e42","gray30","#876b3a","khaki1")) |
Value
A plot of historical distributions with the median, four quantiles (5th, 25th, 75th, 95th) and the realized dependent variable.
Examples
# Import data
data(data_US)
data(data_param_histo_US)
results_plot_2D <- f_plot_distrib_2D(m_param_histo=data_param_histo_US,
type_function="skew-t",
v_date=data_US[,1],
v_var_dep=data_US[,2],
x_lab="US GDP variation",
y_lab="Year")
Plot of historical distributions in 3D
Description
This function allows to create a plot in 3D of historical distributions.
Usage
f_plot_distrib_3D(
m_param_histo,
type_function,
v_date = NULL,
n_samples = 10000,
x_min = NULL,
x_max = NULL,
x_lab,
y_lab,
color_theme = c("#bd8e42", "#bebfbf")
)
Arguments
m_param_histo |
Numeric matrix containing the parameters of the f_param_histo function |
type_function |
String argument specifying the distribution type ("gaussian", "skew-gaussian" or "skew-t") |
v_date |
Vector optional of dates containing the full sample's dates (default value : daily dates starting from "1970-01-01") |
n_samples |
Number optional of samples for the plot (default value = 1000) |
x_min |
Numeric optional argument (default value = VaR 97.5) |
x_max |
Numeric optional argument (default value = VaR 2.5) |
x_lab |
String optional argument for the x axis title (default value = x) |
y_lab |
String optional argument for the y axis title (default value = y) |
color_theme |
A character vector specifying the color theme to use (default value c("#bd8e42", "#bebfbf")) |
Value
A plot in 3D of historical distributions
Examples
# Import data
data(data_US)
data(data_param_histo_US)
results_plot_3D <- f_plot_distrib_3D(m_param_histo=data_param_histo_US,
type_function="skew-t",
v_date=data_US[,1],
x_lab="US GDP variation",
y_lab="Year")