Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

explain

Calculate CIU for specific instance


Description

Calculate Contextual Importance (CI) and Contextual Utility (CU) for an instance (Context) using the given "black-box" model. First get a CIU object by calling ciu.new as e.g. ciu <- ciu.new(...), then call as ciu.res <- ciu$explain(...). "Usage" section is in "Details" section because Roxygen etc. don't support documentation of functions within functions.

Arguments

instance

Input values for the instance to explain. Should be a data.frame even though a vector or matrix might work too if input names and other needed metadata can be deduced from the dataset or other parameters given to ciu.new.

ind.inputs.to.explain

vector of indices for the inputs to be explained, i.e. for which CIU should be calculated. If NULL, then all inputs will be included.

in.min.max.limits

data.frame or matrix with one row per output and two columns, where the first column indicates the minimal value and the second column the maximal value for that output. ONLY NEEDED HERE IF not given as parameter to ciu.new or if the limits are different for this specific instance than the default ones.

n.samples

How many instances to generate for estimating CI and CU. For inputs of type factor, all possible combinations of input values is generated, so this parameter only influences how many instances are (at least) generated for continuous-valued inputs.

target.concept

If provided, then calculate CIU of inputs ind.inputs.to.explain relative to the given concept rather than relative to the actual output(s). ind.inputs.to.explain should normally be a subset (or all) of the inputs that target.concept consists of, even though that not required by the CIU calculation. If a "target.ciu" is provided, then the "target.concept" doesn't have to be included in the vocabulary gives as parameter to ciu.new (at least for the moment).

target.ciu

ciu.result object previously calculated for target.concept. If a target.concept is provided but target.ciu=NULL, then target.ciu is estimated by a call to explain with the n.samples value given as a parameter to this call. It may be useful to provide target.ciu if it should be estimated using some other (typically greater) value for n.samples than the default one, or if it has already been calculated for some reason.

Details

Usage

explain(
  instance,
  ind.inputs.to.explain,
  in.min.max.limits=NULL,
  n.samples=100,
  target.concept=NULL,
  target.ciu=NULL
)

Value

A ciu.result object as returned by ciu.result.new

Author(s)

Kary Främling

See Also


ciu

Contextual Importance and Utility

v0.1.0
MIT + file LICENSE
Authors
Kary Främling
Initial release

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.