ICEbox (version 1.1.5)

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)

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.

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.

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.

See Also

plot.dice, print.dice, summary.dice

Examples

 if (FALSE) {
# 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)
}