ICEbox: dice – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

dice

Creates an object of class dice.

Description

Estimates the partial derivative function for each curve in an ice object. See Goldstein et al (2013) for further details.

Usage

dice(ice_obj, DerivEstimator)

Arguments

`ice_obj`	Object of class `ice`. This function generates partial derivative estimates for each row in `ice_obj$ice_curves`.
`DerivEstimator`	Optional function with a single argument `y`. Returns the estimated partial derivative of a function sampled at the points (`ice_obj$gridpts`,`y`). If omitted, the default (a) smooths (`ice_obj$gridpts`,`y`) using `supsmu` and then (b) uses the `D1tr` function ("discrete first derivative using simple difference ratios") found in the `sfsmisc` package to estimate the derivative.

Value

A list of class dice with the following elements. Most are passed directly through from ice_object and exist to enable various plotting facilities.

`d_ice_curves`	Matrix of dimension `nrow(Xice)` by `length(gridpts)`. Each row corresponds to an observation's d-ICE curve, estimated at the values of `predictor` in `gridpts`.
`xj`	The actual values of `predictor` observed in the data in the order of `Xice`.
`actual_deriv`	Vector of length `nrow(Xice)` containing the estimated partial derivatives at the value of the `predictor` actually found in `Xice`.
`sd_deriv`	Vector of length `length(gridpts)` with the cross-observation sd of partial derivative estimates. For instance `sd_deriv[1]` equals `sd(d_ice_curves[,1])`.
`logodds`	Passed from `ice_object`. If `TRUE`, `d_ice_curves` are estimated derivatives of the centered log-odds.
`gridpts`	Passed from `ice_object`.
`predictor`	Passed from `ice_object`.
`xlab`	Passed from `ice_object`.
`nominal_axis`	Passed from `ice_object`.
`range_y`	Passed from `ice_object`.
`Xice`	Passed from `ice_object`.
`dpdp`	The estimated partial derivative of the PDP.

References

Goldstein, A., Kapelner, A., Bleich, J., and Pitkin, E., Peeking Inside the Black Box: Visualizing Statistical Learning With Plots of Individual Conditional Expectation. (2014) Journal of Computational and Graphical Statistics, in press

Martin Maechler et al. sfsmisc: Utilities from Seminar fuer Statistik ETH Zurich. R package version 1.0-24.

Examples

## Not run: 
# same examples as for 'ice', but now create a derivative estimate as well.
require(ICEbox)
require(randomForest)
require(MASS) #has Boston Housing data, Pima

########  regression example
data(Boston) #Boston Housing data
X = Boston
y = X$medv
X$medv = NULL

## build a RF:
bhd_rf_mod = randomForest(X, y)

## Create an 'ice' object for the predictor "age":
bhd.ice = ice(object = bhd_rf_mod, X = X, y = y, predictor = "age", frac_to_build = .1)

# make a dice object:
bhd.dice = dice(bhd.ice)

#### classification example
data(Pima.te)  #Pima Indians diabetes classification
y = Pima.te$type
X = Pima.te
X$type = NULL

## build a RF:
pima_rf = randomForest(x = X, y = y)

## Create an 'ice' object for the predictor "skin":
# For classification we plot the centered log-odds. If we pass a predict
# function that returns fitted probabilities, setting logodds = TRUE instructs
# the function to set each ice curve to the centered log-odds of the fitted 
# probability. 
pima.ice = ice(object = pima_rf, X = X, predictor = "skin", logodds = TRUE,
                    predictfcn = function(object, newdata){ 
                         predict(object, newdata, type = "prob")[, 2]
                    }
              )

# make a dice object:
pima.dice = dice(pima.ice)

## End(Not run)

ICEbox

Individual Conditional Expectation Plot Toolbox

v1.1.2

GPL-2 | GPL-3

Authors

Alex Goldstein, Adam Kapelner, Justin Bleich

Initial release

2017-07-12