ceml.tfkeras¶

ceml.tfkeras.counterfactual¶

class ceml.tfkeras.counterfactual.TfCounterfactual(model, **kwds)

Class for computing a counterfactual of a tensorflow model.

See parent class ceml.model.counterfactual.Counterfactual.

Parameters

model (instance of ceml.model.model.ModelWithLoss) – The tensorflow model that is used for computing counterfactuals. The model has to be wrapped inside a class that is derived from the ceml.model.model.ModelWithLoss class.

Raises
compute_counterfactual(x, y_target, features_whitelist=None, regularization=None, C=1.0, optimizer='nelder-mead', optimizer_args=None, return_as_dict=True, done=None)

Computes a counterfactual of a given input x.

Parameters
• x (numpy.ndarray) – The input x whose prediction has to be explained.

• y_target (int or float or a callable that returns True if a given prediction is accepted.) – The requested prediction of the counterfactual.

• feature_whitelist (list(int), optional) –

List of feature indices (dimensions of the input space) that can be used when computing the counterfactual.

If feature_whitelist is None, all features can be used.

The default is None.

• regularization (str or callable, optional) –

Regularizer of the counterfactual. Penalty for deviating from the original input x.

Supported values:

• l1: Penalizes the absolute deviation.

• l2: Penalizes the squared deviation.

You can use your own custom penalty function by setting regularization to a callable that can be called on a potential counterfactual and returns a scalar.

If regularization is None, no regularization is used.

The default is “l1”.

• C (float or list(float), optional) –

The regularization strength. If C is a list, all values in C are tried and as soon as a counterfactual is found, this counterfactual is returned and no other values of C are tried.

C is ignored if no regularization is used (regularization=None).

The default is 1.0

• optimizer (str or instance of tf.train.Optimizer, optional) –

Name/Identifier of the optimizer that is used for computing the counterfactual. See ceml.optim.optimizer.desc_to_optim() for details.

As an alternative, any optimizer from tensorflow can be used - optimizer must be an an instance of tf.train.Optimizer.

• optimizer_args (dict, optional) –

Dictionary containing additional parameters for the optimization algorithm.

Supported parameters (keys):

• tol: Tolerance for termination

• max_iter: Maximum number of iterations

If optimizer_args is None or if some parameters are missing, default values are used.

The default is None.

• return_as_dict (boolean, optional) –

If True, returns the counterfactual, its prediction and the needed changes to the input as dictionary. If False, the results are returned as a triple.

The default is True.

• done (callable, optional) –

A callable that returns True if a counterfactual with a given output/prediction is accepted and False otherwise.

If done is None, the output/prediction of the counterfactual must match y_target exactly.

The default is None.

Note

In case of a regression it might not always be possible to achieve a given output/prediction exactly.

Returns

A dictionary where the counterfactual is stored in ‘x_cf’, its prediction in ‘y_cf’ and the changes to the original input in ‘delta’.

(x_cf, y_cf, delta) : triple if return_as_dict is False

Return type

dict or triple

Raises

Exception – If no counterfactual was found.

ceml.tfkeras.counterfactual.generate_counterfactual(model, x, y_target, features_whitelist=None, regularization=None, C=1.0, optimizer='nelder-mead', optimizer_args=None, return_as_dict=True, done=None)

Computes a counterfactual of a given input x.

Parameters
• model (instance of ceml.model.model.ModelWithLoss) – The tensorflow model that is used for computing the counterfactual.

• x (numpy.ndarray) – The input x whose prediction has to be explained.

• y_target (int or float or a callable that returns True if a given prediction is accepted.) – The requested prediction of the counterfactual.

• feature_whitelist (list(int), optional) –

List of feature indices (dimensions of the input space) that can be used when computing the counterfactual.

If feature_whitelist is None, all features can be used.

The default is None.

• regularization (str or callable, optional) –

Regularizer of the counterfactual. Penalty for deviating from the original input x.

Supported values:

• l1: Penalizes the absolute deviation.

• l2: Penalizes the squared deviation.

You can use your own custom penalty function by setting regularization to a callable that can be called on a potential counterfactual and returns a scalar.

If regularization is None, no regularization is used.

The default is “l1”.

• C (float or list(float), optional) –

The regularization strength. If C is a list, all values in C are tried and as soon as a counterfactual is found, this counterfactual is returned and no other values of C are tried.

If no regularization is used (regularization=None), C is ignored.

The default is 1.0

• optimizer (str or instance of tf.train.Optimizer, optional) –

Name/Identifier of the optimizer that is used for computing the counterfactual. See ceml.optim.optimizer.desc_to_optim() for details.

As an alternative, any optimizer from tensorflow can be used - optimizer must be an an instance of tf.train.Optimizer.

• optimizer_args (dict, optional) –

Dictionary containing additional parameters for the optimization algorithm.

Supported parameters (keys):

• tol: Tolerance for termination

• max_iter: Maximum number of iterations

If optimizer_args is None or if some parameters are missing, default values are used.

The default is None.

• return_as_dict (boolean, optional) –

If True, returns the counterfactual, its prediction and the needed changes to the input as dictionary. If False, the results are returned as a triple.

The default is True.

• done (callable, optional) –

A callable that returns True if a counterfactual with a given output/prediction is accepted and False otherwise.

If done is None, the output/prediction of the counterfactual must match y_target exactly.

The default is None.

Note

In case of a regression it might not always be possible to achieve a given output/prediction exactly.

Returns

A dictionary where the counterfactual is stored in ‘x_cf’, its prediction in ‘y_cf’ and the changes to the original input in ‘delta’.

(x_cf, y_cf, delta) : triple if return_as_dict is False

Return type

dict or triple