trustyai.explainers.CounterfactualExplainer

class trustyai.explainers.CounterfactualExplainer(steps=10000)

“How do I get the result I want?”

The CounterfactualExplainer class seeks to answer this question by exploring “what-if” scenarios. Given some initial input and desired outcome, the counterfactual explainer tries to find a set of nearby inputs that produces the desired outcome. Mathematically, if we have a model \(f\), some input \(x\) and a desired model output \(y'\), the counterfactual explainer finds some nearby input \(x'\) such that \(f(x') = y'\).

__init__(steps=10000)

Build a new counterfactual explainer.

Parameters:
steps: int

The number of search steps to perform during the counterfactual search.

Methods

__init__([steps])

Build a new counterfactual explainer.

explain(inputs, model[, goal, ...])

Request for a counterfactual explanation given a list of features, goals and a PredictionProvider
explain(inputs: int | float | integer | inexact | ndarray | DataFrame | Series | List[Feature] | PredictionInput, model: PredictionProvider | Model, goal: int | float | integer | inexact | ndarray | DataFrame | Series | List[Output] | PredictionOutput | None = None, feature_domains: List[FeatureDomain] | None = None, data_distribution: DataDistribution | None = None, uuid: UUID | None = None, timeout: float | None = None, criteria: GoalCriteria | None = None) → CounterfactualResult

Request for a counterfactual explanation given a list of features, goals and a PredictionProvider

Parameters:
inputsint, float, numpy.number, List[Union[int, float, numpy.number]], numpy.ndarray, pandas.DataFrame, pandas.Series, List[Feature], or PredictionInput

List of input features, as a:

  • If there’s only a single input feature, an int, float, or any of the Numpy equivalents can be used.

  • A list of int, float, or any of the Numpy equivalents.

  • Numpy array of shape [1, n_features] or [n_features]

  • Pandas DataFrame with 1 row and n_features columns

  • Pandas Series with n_features rows

  • A List of TrustyAI Feature, as created by the feature() function

  • A TrustyAI PredictionInput

goalint, float, numpy.number, List[Union[int, float, numpy.number]], numpy.ndarray, pandas.DataFrame, pandas.Series, List[Output], or PredictionOutput

The desired model outputs to be searched for in the counterfactual explanation. These can take the form of a:

  • If there’s only a single output, an int, float, or any of the Numpy equivalents can be used.

  • A list of int, float, or any of the Numpy equivalents.

  • Numpy array of shape [1, n_outputs] or [n_outputs]

  • Pandas DataFrame with 1 row and n_outputs columns

  • Pandas Series with n_outputs rows

  • A List of TrustyAI Output, as created by the output() function

  • A TrustyAI PredictionOutput

modelPredictionProvider

The TrustyAI model as generated by Model or a Java PredictionProvider

feature_domainsList[FeatureDomain]

A list of feature domains (each created by feature_domain()) that define the valid domain of the input features. The ith element of the list defines the domain of the ith input feature. If the ith element of this list is None, the no domain information will be added to the ith feature. If the ith feature had no previously-supplied domain information, it will be taken to be constrained and non-variable. If feature_domains=None, no domain information will be added to any of the features, thus preserving existing domains if they’ve been manually added previously or holding undomained features constrained.

data_distributionOptional[DataDistribution]

The DataDistribution to use when sampling the inputs.

uuidOptional[_uuid.UUID]

The UUID to use during search.

timeoutOptional[float]

The timeout time in seconds of the counterfactual explanation.

criteriaOptional[GoalCriteria]

An optional custom scoring function, wrapped as a GoalCriteria.

Returns:
CounterfactualResult

Object containing the results of the counterfactual explanation.