sensitivity (version 1.28.0)

support: Support index functions: Measuring the effect of input variables over their support

Description

Function to estimate the first-order and total support index functions (Fruth et al., 2016).

Usage

support(model, X, Xnew = NULL, fX = NULL, gradfX = NULL, h = 1e-06, ...)

Value

main

a matrix whose columns contain the first-order support index functions, estimated at Xnew.

total

a matrix whose columns contain the total support index functions, estimated at Xnew.

DGSM

a vector containing an estimation of DGSM.

X

...

Xnew

...

fX

...

gradfX

... see 'arguments' section.

Arguments

model

a function, or a model with a predict method, defining the model to analyze.

X

a random sample.

Xnew

an optional set of points where to visualize the support indices. If missing, X is used.

fX

an optional vector containing the evaluations of model at X. If missing, fX is computed by evaluating model at X.

gradfX

an optional vector containing the evaluations of the gradient of model at X. If missing, gradfX is approximated by finite differences of model at X.

h

a small number for computing finite differences (f(X_i + h) - f(X_i))/h. Default is 1e-6.

...

optional arguments to be passed to model.

Author

O. Roustant

Details

The first-order support index of f(X) relative to X_i is the squared conditional expectation of its partial derivative with respect to X_i.

The total support index of f(X) relative to X_i is the conditional expectation of its squared partial derivative with respect to X_i.

These two functions measure the local influence of X_i, in the global space of the other input variables. Up to square transformations, support indices can be viewed as regression curves of partial derivatives df(X)/dX_i with respect to X_i. Estimation is performed by smoothing from the diagonal scatterplots (X_i, df/dX_i) with the function smooth.spline{stats} with the default options.

For the sake of comparison, support index functions may be normalized. The proposed normalization is the sum of the DGSM, equal to the sum of the overall means of total support functions. Normalized support index functions can be plotted with the S3 method plot, as well as the underlying diagonal scatterplots of derivatives (S3 method scatterplot).

References

J. Fruth, O. Roustant, S. Kuhnt, 2019, Support indices: Measuring the effects of input variables over their support, Reliability Engineering and System Safety, 187:17-27.

See Also

S3 methods plot and scatterplot: plot.support

Examples

# \donttest{
# -----------------
# ishigami function
# -----------------
n <- 5000
n.points <- 1000
d <- 3

set.seed(0)
X <- matrix(runif(d*n, min = -pi, max = pi), n, d)
Xnew <- matrix(seq(from = -pi, to = pi, length=n.points), n.points, d)

b <- support(model = ishigami.fun, X, Xnew)

# plot method (x-axis in probability scale), of the normalized support index functions
plot(b, col = c("lightskyblue4", "lightskyblue1", "black"), 
     xprob = TRUE, p = 'punif', p.arg = list(min = -pi, max = pi), ylim = c(0, 2))

# below : diagonal scatterplots of the gradient, 
# on which are based the estimation by smoothing
scatterplot(b, xprob = TRUE) 

# now with normal margins
# -----------------------
X <- matrix(rnorm(d*n), n, d)
Xnew <- matrix(rnorm(d*n.points), n.points, d)
b <- support(model = ishigami.fun, X, Xnew)

plot(b, col = c("lightskyblue4", "lightskyblue1", "black"), xprob = FALSE)
scatterplot(b, xprob = FALSE, type = "histogram", bins = 10, cex = 1, cex.lab = 1.5)
# }