stress_moment: Stressing Moments
In spesenti/SWIM: Scenario Weights for Importance Measurement

Description Usage Arguments Details Value References See Also Examples

Provides weights on simulated scenarios from a baseline stochastic model, such that stressed model components (random variables) fulfill the moment constraints. Scenario weights are selected by constrained minimisation of the relative entropy to the baseline model.

stress_moment(
  x,
  f,
  k,
  m,
  normalise = TRUE,
  show = FALSE,
  names = NULL,
  log = FALSE,
  ...
)

`x`	A vector, matrix or data frame containing realisations of random variables. Columns of `x` correspond to random variables; OR A `SWIM` object, where `x` corresponds to the underlying data of the `SWIM` object.
`f`	A function, or list of functions, that, applied to `x`, constitute the moment constraints.
`k`	A vector or list of vectors, same length as `f`, indicating which columns of `x` each function in `f` operates on. When `f` is a list, `k[[i]]` corresponds to the input variables of `f[[i]]`.
`m`	Numeric vector, same length as `f`, containing the stressed moments of `f(x)`. Must be in the range of `f(x)`.
`normalise`	Logical. If true, values of `f(x)` are linearly scaled to the unit interval.
`show`	Logical. If true, print the result of the call to `nleqslv`.
`names`	Character vector, the names of stressed models.
`log`	Boolean, the option to print weights' statistics.
`...`	Additional arguments to be passed to `nleqslv`.

The moment constraints are given by E^Q( f(x) ) = m, where E^Q denotes the expectation under the stressed model. stress_moment solves the subsequent set of equations with respect to theta, using nleqslv from package nleqslv:

E^Q( f(x) ) = E( f(x) * exp(theta * f(x)) ) = m.

There is no guarantee that the set of equations has a solution, or that the solution is unique. SWIM will return a warning if the termination code provided by nleqslv is different from 1 (convergence has been achieved). It is recommended to check the result of the call to nleqslv using the "show" argument. The user is referred to the nleqslv documentation for further details.

Normalising the data may help avoiding numerical issues when the range of values is wide.

A SWIM object containing:

x, a data.frame containing the data;
new_weights, a list, each component corresponds to a different stress and is a vector of scenario weights;
type = "moment";
specs, a list, each component corresponds to a different stress and contains f, k and m.

See SWIM for details.

The function call will print a message containing the termination code returned by the call to nleqslv and a table with the required and achieved moment, and the absolute and relative error.

\insertRef

Pesenti2019reverseSWIM

\insertRef

Pesenti2020SSRNSWIM

\insertRef

Csiszar1975SWIM

See stress_mean for stressing means and stress_mean_sd for stressing mean and standard deviation jointly.

Other stress functions: stress_HARA_RM_w(), stress_RM_mean_sd_w(), stress_RM_w(), stress_VaR_ES(), stress_VaR(), stress_mean_sd_w(), stress_mean_sd(), stress_mean_w(), stress_mean(), stress_prob(), stress_user(), stress_wass(), stress()

set.seed(0)
x <- data.frame(cbind(
  "normal" = rnorm(1000),
  "gamma" = rgamma(1000, shape = 2),
  "beta" = rbeta(1000, shape1 = 2, shape2 = 2)))

## stressing covariance of columns 1, 2 while leaving the means unchanged
res1 <- stress_moment(x = x,
  f = list(function(x)x, function(x)x, function(x)x[1] * x[2]),
  k = list(1, 2, c(1, 2)), m = c(0, 2, 0.5),
  method = "Newton", control = list(maxit = 1000, ftol = 1E-10))
## means under the stressed model
summary(res1)
apply(x, 2, stats::weighted.mean, w = get_weights(res1))
## covariance of columns 1,2 under the stressed model
stats::weighted.mean(x[, 1] * x[, 2], w = get_weights(res1))

## stressing jointly the tail probabilities of columns 1, 3
res2 <- stress_moment(x = x,
  f = list(function(x)(x > 1.5), function(x)(x > 0.9)),
  k = list(1, 3), m = c(0.9, 0.9))
summary(res2)
## probabilities under the stressed model
mean((x[, 1] > 1.5) * get_weights(res2))
mean((x[, 3] > 0.9) * get_weights(res2))