stochContr: Stochastic contribution analysis of the Monte Carlo output

View source: R/stochContr.R

stochContrR Documentation

Stochastic contribution analysis of the Monte Carlo output

Description

Conducts a "stochastic contribution analysis" by calculating the change in the variance of the Monte Carlo output when each of the simulated input variables is kept constant at its mean, i.e. its uncertainty is removed.

Usage

stochContr(prop, plot = TRUE)

Arguments

prop

a propagate object.

plot

logical. If TRUE, boxplots of the original output distribution and of those with each input fixed at its mean are drawn.

Details

This function takes the Monte Carlo simulated input data from a propagate object (...$datSIM), sequentially substitutes each input X_i by its mean \bar{x}_i, and re-evaluates the model. Optional boxplots compare the original output distribution with those obtained by removing the uncertainty of each X_i. The contribution of X_i is the resulting decrease in output variance,

D_i = \mathrm{V}(Y) - \mathrm{V}(Y \mid X_i = \bar{x}_i),

and the relative contributions are C_i = D_i/\sum_j D_j, so that \sum_i C_i = 1.

Interpretation. For a linear model with independent inputs, D_i = c_i^2 \mathrm{Var}(X_i) up to Monte Carlo noise, so that C_i equals the relative variance contribution of the law of propagation of uncertainty if all inputs have Gaussian margins or the same \nu. In general, the expectation of \mathrm{V}(Y \mid X_i) over X_i is \mathrm{V}(Y) - V_i, with V_i the first-order Sobol' variance, so that D_i/\mathrm{V}(Y) is a one-point estimate of the first-order index S_i, evaluated at X_i = \bar{x}_i instead of averaged over X_i. For nonlinear models, D_i can therefore be negative, which is reported in a message. Use sobol for variance-based sensitivity indices.

Dependent inputs. Fixing one input at its mean while keeping the simulated values of the others ignores their conditional distribution. For correlated inputs (|r_{ij}| > 4/\sqrt{M} for any pair of the M simulated input vectors) and for mc.margins = "mvt", a warning is issued, and the contributions are not interpretable.

Value

The relative contributions C_i for all input variables, with the variance differences D_i as attribute "varDiff".

Author(s)

Andrej-Nikolai Spiess

See Also

sobol, summary.propagate (relative contributions from the law of propagation of uncertainty).

Examples

a <- c(15, 1)
b <- c(100, 5)
phi <- c(0.5, 0.02)
DAT <- cbind(a, b, phi)
EXPR <- expression(a * b^sin(phi))
RES <- propagate(EXPR, DAT, nsim = 10000)
SC <- stochContr(RES)
SC
attr(SC, "varDiff")

propagate documentation built on Nov. 10, 2026, 9:07 a.m.