Reference

RawOutputArrayType

A type union for the allowed type for the output array y.

RawTargetType

A type union for the allowed types for the target variable.

flux_training_params

The default training parameter for FluxModels etc.

An abstract type that serves as the base type for convergence objects.

Base type for counterfactual explanations.

An abstract type that serves as the base type for counterfactual generators.

Base type for models.

An abstract type for penalty functions.

A struct that collects all information relevant to a specific counterfactual explanation for a single individual.

function CounterfactualExplanation(;
	x::AbstractArray,
	target::RawTargetType,
	data::CounterfactualData,
	M::Models.AbstractModel,
	generator::Generators.AbstractGenerator,
	num_counterfactuals::Int = 1,
	initialization::Symbol = :add_perturbation,
    convergence::Union{AbstractConvergence,Symbol}=:decision_threshold,
)

Outer method to construct a CounterfactualExplanation structure.

EncodedOutputArrayType

Type of encoded output array.

EncodedTargetType

Type of encoded target variable.

OutputEncoder

The OutputEncoder takes a raw output array (y) and encodes it.

(encoder::OutputEncoder)(ynew::RawTargetType)

When called on a new value ynew, the OutputEncoder encodes it based on the initial encoding.

(encoder::OutputEncoder)()

On call, the OutputEncoder returns the encoded output array.

generate_counterfactual(
    x::Base.Iterators.Zip,
    target::RawTargetType,
    data::CounterfactualData,
    M::Models.AbstractModel,
    generator::AbstractGenerator;
    kwargs...,
)

Overloads the generate_counterfactual method to accept a zip of factuals x and return a vector of counterfactuals.

generate_counterfactual(
    x::Matrix,
    target::RawTargetType,
    data::CounterfactualData,
    M::Models.AbstractModel,
    generator::AbstractGenerator;
    num_counterfactuals::Int=1,
    initialization::Symbol=:add_perturbation,
    convergence::Union{AbstractConvergence,Symbol}=:decision_threshold,
    timeout::Union{Nothing,Real}=nothing,
)

The core function that is used to run counterfactual search for a given factual x, target, counterfactual data, model and generator. Keywords can be used to specify the desired threshold for the predicted target class probability and the maximum number of iterations.

Arguments

• x::Matrix: Factual data point.
• target::RawTargetType: Target class.
• data::CounterfactualData: Counterfactual data.
• M::Models.AbstractModel: Fitted model.
• generator::AbstractGenerator: Generator.
• num_counterfactuals::Int=1: Number of counterfactuals to generate for factual.
• initialization::Symbol=:add_perturbation: Initialization method. By default, the initialization is done by adding a small random perturbation to the factual to achieve more robustness.
• convergence::Union{AbstractConvergence,Symbol}=:decision_threshold: Convergence criterion. By default, the convergence is based on the decision threshold. Possible values are :decision_threshold, :max_iter, :generator_conditions or a conrete convergence object (e.g. DecisionThresholdConvergence).
• timeout::Union{Nothing,Int}=nothing: Timeout in seconds.

Examples

Generic generator

julia> using CounterfactualExplanations

julia> using TaijaData
       
        # Counteractual data and model:

julia> counterfactual_data = CounterfactualData(load_linearly_separable()...);

julia> M = fit_model(counterfactual_data, :Linear);

julia> target = 2;

julia> factual = 1;

julia> chosen = rand(findall(predict_label(M, counterfactual_data) .== factual));

julia> x = select_factual(counterfactual_data, chosen);
       
       # Search:

julia> generator = Generators.GenericGenerator();

julia> ce = generate_counterfactual(x, target, counterfactual_data, M, generator);

julia> converged(ce.convergence, ce)
true

Broadcasting

The generate_counterfactual method can also be broadcasted over a tuple containing an array. This allows for generating multiple counterfactuals in parallel.

julia> chosen = rand(findall(predict_label(M, counterfactual_data) .== factual), 5);

julia> xs = select_factual(counterfactual_data, chosen);

julia> ces = generate_counterfactual.(xs, target, counterfactual_data, M, generator);

julia> converged(ce.convergence, ce)
true

generate_counterfactual(
    x::Matrix,
    target::RawTargetType,
    data::DataPreprocessing.CounterfactualData,
    M::Models.AbstractModel,
    generator::Generators.GrowingSpheresGenerator;
    num_counterfactuals::Int=1,
    convergence::Union{AbstractConvergence,Symbol}=Convergence.DecisionThresholdConvergence(;
        decision_threshold=(1 / length(data.y_levels)), max_iter=1000
    ),
    kwrgs...,
)

Overloads the generate_counterfactual for the GrowingSpheresGenerator generator.

generate_counterfactual(x::Tuple{<:AbstractArray}, args...; kwargs...)

Overloads the generate_counterfactual method to accept a tuple containing and array. This allows for broadcasting over Zip iterators.

generate_counterfactual(
    x::Vector{<:Matrix},
    target::RawTargetType,
    data::CounterfactualData,
    M::Models.AbstractModel,
    generator::AbstractGenerator;
    kwargs...,
)

Overloads the generate_counterfactual method to accept a vector of factuals x and return a vector of counterfactuals.

get_target_index(y_levels, target)

Utility that returns the index of target in y_levels.

path(ce::CounterfactualExplanation)

A convenience method that returns the entire counterfactual path.

target_probs(
    ce::CounterfactualExplanation,
    x::Union{AbstractArray,Nothing}=nothing,
)

Returns the predicted probability of the target class for x. If x is nothing, the predicted probability corresponding to the counterfactual value is returned.

terminated(ce::CounterfactualExplanation)

A convenience method that checks if the counterfactual search has terminated.

total_steps(ce::CounterfactualExplanation)

A convenience method that returns the total number of steps of the counterfactual search.

convergence_catalogue

A dictionary containing all convergence criteria.

DecisionThresholdConvergence

Convergence criterion based on the target class probability threshold. The search stops when the target class probability exceeds the predefined threshold.

Fields

• decision_threshold::AbstractFloat: The predefined threshold for the target class probability.
• max_iter::Int: The maximum number of iterations.
• min_success_rate::AbstractFloat: The minimum success rate for the target class probability.

GeneratorConditionsConvergence

Convergence criterion for counterfactual explanations based on the generator conditions. The search stops when the gradients of the search objective are below a certain threshold and the generator conditions are satisfied.

Fields

• decision_threshold::AbstractFloat: The threshold for the decision probability.
• gradient_tol::AbstractFloat: The tolerance for the gradients of the search objective.
• max_iter::Int: The maximum number of iterations.
• min_success_rate::AbstractFloat: The minimum success rate for the generator conditions (across counterfactuals).

GeneratorConditionsConvergence(; decision_threshold=0.5, gradient_tol=1e-2, max_iter=100, min_success_rate=0.75, y_levels=nothing)

Outer constructor for GeneratorConditionsConvergence.

MaxIterConvergence

Convergence criterion based on the maximum number of iterations.

Fields

• max_iter::Int: The maximum number of iterations.

conditions_satisfied(gen::AbstractGenerator, ce::AbstractCounterfactualExplanation)

This function is overloaded in the Generators module to check whether the counterfactual search has converged with respect to generator conditions.

converged(
    convergence::InvalidationRateConvergence,
    ce::AbstractCounterfactualExplanation,
    x::Union{AbstractArray,Nothing}=nothing,
)

Checks if the counterfactual search has converged when the convergence criterion is invalidation rate.

converged(
    convergence::DecisionThresholdConvergence,
    ce::AbstractCounterfactualExplanation,
    x::Union{AbstractArray,Nothing}=nothing,
)

Checks if the counterfactual search has converged when the convergence criterion is the decision threshold.

converged(
    convergence::MaxIterConvergence,
    ce::AbstractCounterfactualExplanation,
    x::Union{AbstractArray,Nothing}=nothing,
)

Checks if the counterfactual search has converged when the convergence criterion is maximum iterations. This means the counterfactual search will not terminate until the maximum number of iterations has been reached independently of the other convergence criteria.

converged(
    convergence::GeneratorConditionsConvergence,
    ce::AbstractCounterfactualExplanation,
    x::Union{AbstractArray,Nothing}=nothing,
)

Checks if the counterfactual search has converged when the convergence criterion is generator_conditions.

converged(ce::AbstractCounterfactualExplanation)

Returns true if the counterfactual explanation has converged.

get_convergence_type(convergence::AbstractConvergence)

Returns the convergence object.

get_convergence_type(convergence::Symbol)

Returns the convergence object from the dictionary of default convergence types.

invalidation_rate(ce::AbstractCounterfactualExplanation)

Calculates the invalidation rate of a counterfactual explanation.

Arguments

• ce::AbstractCounterfactualExplanation: The counterfactual explanation to calculate the invalidation rate for.
• kwargs: Additional keyword arguments to pass to the function.

Returns

The invalidation rate of the counterfactual explanation.

threshold_reached(ce::AbstractCounterfactualExplanation, x::Union{AbstractArray,Nothing}=nothing)

Determines if the predefined threshold for the target class probability has been reached.

The default evaluation measures.

A container for benchmarks of counterfactual explanations. Instead of subtyping DataFrame, it contains a DataFrame of evaluation measures (see this discussion for why we don't subtype DataFrame directly).

(bmk::Benchmark)(; agg=mean)

Returns a DataFrame containing evaluation measures aggregated by num_counterfactual.

benchmark(
    data::CounterfactualData;
    models::Dict{<:Any,<:Any}=standard_models_catalogue,
    generators::Union{Nothing,Dict{<:Any,<:AbstractGenerator}}=nothing,
    measure::Union{Function,Vector{Function}}=default_measures,
    n_individuals::Int=5,
    suppress_training::Bool=false,
    factual::Union{Nothing,RawTargetType}=nothing,
    target::Union{Nothing,RawTargetType}=nothing,
    store_ce::Bool=false,
    parallelizer::Union{Nothing,AbstractParallelizer}=nothing,
    kwrgs...,
)

Runs the benchmarking exercise as follows:

1. Randomly choose a factual and target label unless specified.
2. If no pretrained models are provided, it is assumed that a dictionary of callable model objects is provided (by default using the standard_models_catalogue).
3. Each of these models is then trained on the data.
4. For each model separately choose n_individuals randomly from the non-target (factual) class. For each generator create a benchmark as in benchmark(xs::Union{AbstractArray,Base.Iterators.Zip}).
5. Finally, concatenate the results.

If vertical_splits is specified to an integer, the computations are split vertically into vertical_splits chunks. In this case, the results are stored in a temporary directory and concatenated afterwards.

benchmark(
    x::Union{AbstractArray,Base.Iterators.Zip},
    target::RawTargetType,
    data::CounterfactualData;
    models::Dict{<:Any,<:AbstractModel},
    generators::Dict{<:Any,<:AbstractGenerator},
    measure::Union{Function,Vector{Function}}=default_measures,
    xids::Union{Nothing,AbstractArray}=nothing,
    dataname::Union{Nothing,Symbol,String}=nothing,
    verbose::Bool=true,
    store_ce::Bool=false,
    parallelizer::Union{Nothing,AbstractParallelizer}=nothing,
    kwrgs...,
)

First generates counterfactual explanations for factual x, the target and data using each of the provided models and generators. Then generates a Benchmark for the vector of counterfactual explanations as in benchmark(counterfactual_explanations::Vector{CounterfactualExplanation}).

benchmark(
    counterfactual_explanations::Vector{CounterfactualExplanation};
    meta_data::Union{Nothing,<:Vector{<:Dict}}=nothing,
    measure::Union{Function,Vector{Function}}=default_measures,
    store_ce::Bool=false,
)

Generates a Benchmark for a vector of counterfactual explanations. Optionally meta_data describing each individual counterfactual explanation can be supplied. This should be a vector of dictionaries of the same length as the vector of counterfactuals. If no meta_data is supplied, it will be automatically inferred. All measure functions are applied to each counterfactual explanation. If store_ce=true, the counterfactual explanations are stored in the benchmark.

evaluate(
    ce::CounterfactualExplanation;
    measure::Union{Function,Vector{Function}}=default_measures,
    agg::Function=mean,
    report_each::Bool=false,
    output_format::Symbol=:Vector,
    pivot_longer::Bool=true
)

Just computes evaluation measures for the counterfactual explanation. By default, no meta data is reported. For report_meta=true, meta data is automatically inferred, unless this overwritten by meta_data. The optional meta_data argument should be a vector of dictionaries of the same length as the vector of counterfactual explanations.

faithfulness(
    ce::CounterfactualExplanation,
    fun::typeof(Objectives.distance_from_target);
    λ::AbstractFloat=1.0,
    kwrgs...,
)

Computes the faithfulness of a counterfactual explanation based on the cosine similarity between the counterfactual and samples drawn from the model posterior through SGLD (see distance_from_posterior).

plausibility(
    ce::CounterfactualExplanation,
    fun::typeof(Objectives.distance_from_target);
    K=nothing,
    kwrgs...,
)

Computes the plausibility of a counterfactual explanation based on the cosine similarity between the counterfactual and samples drawn from the target distribution.

plausibility(
    ce::CounterfactualExplanation,
    fun::typeof(Objectives.distance_from_target);
    K=nothing,
    kwrgs...,
)

Computes the plausibility of a counterfactual explanation based on the cosine similarity between the counterfactual and samples drawn from the target distribution.

redundancy(ce::CounterfactualExplanation)

Computes the feature redundancy: that is, the number of features that remain unchanged from their original, factual values.

validity(ce::CounterfactualExplanation; γ=0.5)

Checks of the counterfactual search has been successful with respect to the probability threshold γ. In case multiple counterfactuals were generated, the function returns the proportion of successful counterfactuals.

CounterfactualData(
    X::AbstractMatrix,
    y::RawOutputArrayType;
    mutability::Union{Vector{Symbol},Nothing}=nothing,
    domain::Union{Any,Nothing}=nothing,
    features_categorical::Union{Vector{Vector{Int}},Nothing}=nothing,
    features_continuous::Union{Vector{Int},Nothing}=nothing,
    input_encoder::Union{Nothing,InputTransformer,TypedInputTransformer}=nothing,
)

This outer constructor method prepares features X and labels y to be used with the package. Mutability and domain constraints can be added for the features. The function also accepts arguments that specify which features are categorical and which are continues. These arguments are currently not used.

Examples

using CounterfactualExplanations.Data
x, y = toy_data_linear()
X = hcat(x...)
counterfactual_data = CounterfactualData(X,y')

function CounterfactualData(
    X::Tables.MatrixTable,
    y::RawOutputArrayType;
    kwrgs...
)

Outer constructor method that accepts a Tables.MatrixTable. By default, the indices of categorical and continuous features are automatically inferred the features' scitype.

apply_domain_constraints(counterfactual_data::CounterfactualData, x::AbstractArray)

A subroutine that is used to apply the predetermined domain constraints.

fit_transformer!(
    data::CounterfactualData,
    input_encoder::Union{Nothing,InputTransformer,TypedInputTransformer};
    kwargs...,
)

Fit a transformer to the data in place.

fit_transformer(data::CounterfactualData, input_encoder::Nothing; kwargs...)

Fit a transformer to the data. This is a no-op if input_encoder is Nothing.

fit_transformer(
    data::CounterfactualData,
    input_encoder::Type{<:CausalInference.SCM};
    kwargs...,
)

Fit a transformer to the data for a SCM object.

fit_transformer(
    data::CounterfactualData,
    input_encoder::Type{GenerativeModels.AbstractGenerativeModel};
    kwargs...,
)

Fit a transformer to the data for a GenerativeModels.AbstractGenerativeModel object.

fit_transformer(
    data::CounterfactualData,
    input_encoder::Type{MultivariateStats.AbstractDimensionalityReduction};
    kwargs...,
)

Fit a transformer to the data for a MultivariateStats.AbstractDimensionalityReduction object.

fit_transformer(
    data::CounterfactualData,
    input_encoder::Type{StatsBase.AbstractDataTransform};
    kwargs...,
)

Fit a transformer to the data for a StatsBase.AbstractDataTransform object.

fit_transformer(data::CounterfactualData, input_encoder::InputTransformer; kwargs...)

Fit a transformer to the data for an InputTransformer object. This is a no-op.

select_factual(counterfactual_data::CounterfactualData, index::Int)

A convenience method that can be used to access the feature matrix.

select_factual(counterfactual_data::CounterfactualData, index::Union{Vector{Int},UnitRange{Int}})

A convenience method that can be used to access the feature matrix.

transformable_features(counterfactual_data::CounterfactualData, input_encoder::Any)

By default, all continuous features are transformable. This function returns the indices of all continuous features.

transformable_features(
    counterfactual_data::CounterfactualData, input_encoder::Type{CausalInference.SCM}
)

Returns the indices of all features that have causal parents.

transformable_features(
    counterfactual_data::CounterfactualData, input_encoder::Type{ZScoreTransform}
)

Returns the indices of all continuous features that can be transformed. For constant features ZScoreTransform returns NaN.

transformable_features(counterfactual_data::CounterfactualData)

Dispatches the transformable_features function to the appropriate method based on the type of the dt field.

all_models_catalogue

A dictionary containing both differentiable and non-differentiable machine learning models.

standard_models_catalogue

A dictionary containing all differentiable machine learning models.

(model::AbstractModel)(X::AbstractArray)

When called on data x, logits are returned.

DeepEnsemble(model; likelihood::Symbol=:classification_binary)

An outer constructor for a deep ensemble model.

Linear(model; likelihood::Symbol=:classification_binary)

An outer constructor for a linear model.

MLP(model; likelihood::Symbol=:classification_binary)

An outer constructor for a multi-layer perceptron (MLP) model.

Model <: AbstractModel

Constructor for all models.

Model(model, type::AbstractFluxNN; likelihood::Symbol=:classification_binary)

Overloaded constructor for Flux models.

Model(model, type::AbstractModelType; likelihood::Symbol=:classification_binary)

Outer constructor for Model where the atomic model is defined and assumed to be pre-trained.

(M::Model)(data::CounterfactualData, type::DeepEnsemble; kwargs...)

Constructs a deep ensemble for the given data.

(M::Model)(data::CounterfactualData, type::Linear; kwargs...)

Constructs a model with one linear layer for the given data. If the output is binary, this corresponds to logistic regression, since model outputs are passed through the sigmoid function. If the output is multi-class, this corresponds to multinomial logistic regression, since model outputs are passed through the softmax function.

(M::Model)(data::CounterfactualData, type::MLP; kwargs...)

Constructs a multi-layer perceptron (MLP) for the given data.

(M::Model)(data::CounterfactualData; kwargs...)

Wrap model M around the data in data.

Model(type::AbstractModelType; likelihood::Symbol=:classification_binary)

Outer constructor for Model where the atomic model is not yet defined.

fit_model(
    counterfactual_data::CounterfactualData, model::Symbol=:MLP;
    kwrgs...
)

Fits one of the available default models to the counterfactual_data. The model argument can be used to specify the desired model. The available values correspond to the keys of the all_models_catalogue dictionary.

fit_model(
    counterfactual_data::CounterfactualData, type::AbstractModelType; kwrgs...
)

A wrapper function to fit a model to the counterfactual_data for a given type of model.

Arguments

• counterfactual_data::CounterfactualData: The data to be used for training the model.
• type::AbstractModelType: The type of model to be trained, e.g., MLP, DecisionTreeModel, etc.

Examples

julia> using CounterfactualExplanations

julia> using CounterfactualExplanations.Models

julia> using TaijaData

julia> data = CounterfactualData(load_linearly_separable()...);

julia> M = fit_model(data, Linear())
CounterfactualExplanations.Models.Model(Chain(Dense(2 => 2)), :classification_multi, CounterfactualExplanations.Models.Fitresult(Chain(Dense(2 => 2)), Dict{Any, Any}()), Linear())

logits(M::Model, X::AbstractArray)

Returns the logits of the model.

logits(M::Model, type::AbstractFluxNN, X::AbstractArray)

Overloads the logits function for Flux models.

logits(M::Model, type::MLJModelType, X::AbstractArray)

Overloads the logits method for MLJ models.

logits(M::Model, type::DeepEnsemble, X::AbstractArray)

Overloads the logits function for deep ensembles.

model_evaluation(M::AbstractModel, test_data::CounterfactualData)

Helper function to compute F-Score for AbstractModel on a (test) data set. By default, it computes the accuracy. Any other measure, e.g. from the StatisticalMeasures package, can be passed as an argument. Currently, only measures applicable to classification tasks are supported.

predict_label(M::AbstractModel, counterfactual_data::CounterfactualData, X::AbstractArray)

Returns the predicted output label for a given model M, data set counterfactual_data and input data X.

predict_label(M::AbstractModel, counterfactual_data::CounterfactualData)

Returns the predicted output labels for all data points of data set counterfactual_data for a given model M.

predict_proba(M::AbstractModel, counterfactual_data::CounterfactualData, X::Union{Nothing,AbstractArray})

Returns the predicted output probabilities for a given model M, data set counterfactual_data and input data X.

probs(M::Model, X::AbstractArray)

Returns the probabilities of the model.

probs(M::Model, type::AbstractFluxNN, X::AbstractArray)

Overloads the probs function for Flux models.

probs(
    M::Model,
    type::MLJModelType,
    X::AbstractArray,
)

Overloads the probs method for MLJ models.

Note for developers

Note that currently the underlying MLJ methods (reformat, predict) are incompatible with Zygote's autodiff. For differentiable MLJ models, the probs` and logits methods need to be overloaded.

probs(M::Model, type::DeepEnsemble, X::AbstractArray)

Overloads the probs function for deep ensembles.

A dictionary containing the constructors of all available counterfactual generators.

AbstractGradientBasedGenerator

An abstract type that serves as the base type for gradient-based counterfactual generators.

AbstractNonGradientBasedGenerator

An abstract type that serves as the base type for non gradient-based counterfactual generators.

Feature Tweak counterfactual generator class.

FeatureTweakGenerator(; penalty::Union{Nothing,Function,Vector{Function}}=Objectives.distance_l2, ϵ::AbstractFloat=0.1)

Constructs a new Feature Tweak Generator object.

Uses the L2-norm as the penalty to measure the distance between the counterfactual and the factual. According to the paper by Tolomei et al., another recommended choice for the penalty in addition to the L2-norm is the L0-norm. The L0-norm simply minimizes the number of features that are changed through the tweak.

Arguments

• penalty::Penalty: The penalty function to use for the generator. Defaults to distance_l2.
• ϵ::AbstractFloat: The tolerance value for the feature tweaks. Described at length in Tolomei et al. (https://arxiv.org/pdf/1706.06691.pdf). Defaults to 0.1.

Returns

• generator::FeatureTweakGenerator: A non-gradient-based generator that can be used to generate counterfactuals using the feature tweak method.

Base class for gradient-based counterfactual generators.

GradientBasedGenerator(;
	loss::Union{Nothing,Function}=nothing,
	penalty::Penalty=nothing,
	λ::Union{Nothing,AbstractFloat,Vector{AbstractFloat}}=nothing,
	latent_space::Bool::false,
	opt::Flux.Optimise.AbstractOptimiser=Flux.Descent(),
    generative_model_params::NamedTuple=(;),
)

Default outer constructor for GradientBasedGenerator.

Arguments

• loss::Union{Nothing,Function}=nothing: The loss function used by the model.
• penalty::Penalty=nothing: A penalty function for the generator to penalize counterfactuals too far from the original point.
• λ::Union{Nothing,AbstractFloat,Vector{AbstractFloat}}=nothing: The weight of the penalty function.
• latent_space::Bool=false: Whether to use the latent space of a generative model to generate counterfactuals.
• opt::Flux.Optimise.AbstractOptimiser=Flux.Descent(): The optimizer to use for the generator.
• generative_model_params::NamedTuple: The parameters of the generative model associated with the generator.

Returns

• generator::GradientBasedGenerator: A gradient-based counterfactual generator.

Growing Spheres counterfactual generator class.

GrowingSpheresGenerator(; n::Int=100, η::Float64=0.1, kwargs...)

Constructs a new Growing Spheres Generator object.

An optimisation rule that can be used to implement a Jacobian-based Saliency Map Attack.

Outer constructor for the JSMADescent rule.

Constructor for CLUEGenerator. For details, see Antoran et al. (2021).

Constructor for ClaPGenerator. For details, see Altmeyer et al. (2023).

Constructor for DiCEGenerator. For details, see Mothilal et al. (2020).

Constructor for ECCoGenerator. This corresponds to the generator proposed in https://arxiv.org/abs/2312.10648, without the conformal set size penalty. For details, see Altmeyer et al. (2024).

Constructor for GenericGenerator.

Constructor for GravitationalGenerator. For details, see Altmeyer et al. (2023).

Constructor for GreedyGenerator. For details, see Schut et al. (2021).

Constructor for ProbeGenerator. For details, see Pawelczyk et al. (2022).

Warning

The ProbeGenerator is currenlty not working adequately. In particular, gradients are not computed with respect to the Hinge loss term proposed in the paper. It is still possible, however, to use this generator to achieve a desired invalidation rate. See issue #376 for details.

Constructor for REVISEGenerator. For details, see Joshi et al. (2019).

Constructor for WachterGenerator. For details, see Wachter et al. (2018).

generate_perturbations(
    generator::AbstractGenerator, ce::AbstractCounterfactualExplanation
)

The default method to generate feature perturbations for any generator.

generate_perturbations(generator::AbstractGradientBasedGenerator, ce::AbstractCounterfactualExplanation)

The default method to generate feature perturbations for gradient-based generators through simple gradient descent.

objective(generator, ex)

A macro that can be used to define the counterfactual search objective.

search_feature_space(generator)

A simple macro that can be used to specify feature space search.

search_latent_space(generator)

A simple macro that can be used to specify latent space search.

with_optimiser(generator, optimiser)

A simple macro that can be used to specify the optimiser to be used.

ddp_diversity(
    ce::AbstractCounterfactualExplanation;
    perturbation_size=1e-5
)

Evaluates how diverse the counterfactuals are using a Determinantal Point Process (DDP).

distance(
    ce::AbstractCounterfactualExplanation;
    from::Union{Nothing,AbstractArray}=nothing,
    agg=mean,
    p::Real=1,
    weights::Union{Nothing,AbstractArray}=nothing,
)

Computes the distance of the counterfactual to the original factual.

distance_l0(ce::AbstractCounterfactualExplanation)

Computes the L0 distance of the counterfactual to the original factual.

distance_l1(ce::AbstractCounterfactualExplanation)

Computes the L1 distance of the counterfactual to the original factual.

distance_l2(ce::AbstractCounterfactualExplanation)

Computes the L2 (Euclidean) distance of the counterfactual to the original factual.

distance_linf(ce::AbstractCounterfactualExplanation)

Computes the L-inf distance of the counterfactual to the original factual.

distance_mad(ce::AbstractCounterfactualExplanation; agg=mean)

This is the distance measure proposed by Wachter et al. (2017).

hinge_loss(ce::AbstractCounterfactualExplanation)

Calculates the hinge loss of a counterfactual explanation with InvalidationRateConvergence.

Arguments

• ce::AbstractCounterfactualExplanation: The counterfactual explanation to calculate the hinge loss for.

Returns

The hinge loss of the counterfactual explanation.

predictive_entropy(ce::AbstractCounterfactualExplanation; agg=Statistics.mean)

Computes the predictive entropy of the counterfactuals. Explained in https://arxiv.org/abs/1406.2541.

Flux.Losses.logitbinarycrossentropy(ce::AbstractCounterfactualExplanation)

Simply extends the logitbinarycrossentropy method to work with objects of type AbstractCounterfactualExplanation.

Flux.Losses.logitcrossentropy(ce::AbstractCounterfactualExplanation)

Simply extends the logitcrossentropy method to work with objects of type AbstractCounterfactualExplanation.

Flux.Losses.mse(ce::AbstractCounterfactualExplanation)

Simply extends the mse method to work with objects of type AbstractCounterfactualExplanation.

CRE <: AbstractCounterfactualExplanation

A Counterfactual Rule Explanation (CRE) is a global explanation for a given target, model M, data and generator.

(cre::CRE)(x::AbstractArray)

Generates a local counterfactual point explanation for x using the generator.

DecisionTreeModel

Concrete type for tree-based models from DecisionTree.jl. Since DecisionTree.jl has an MLJ interface, we subtype the MLJModelType model type.

FluxModelParams

Default MLP training parameters.

JEM

Concrete type for joint-energy models from JointEnergyModels. Since JointEnergyModels has an MLJ interface, we subtype the MLJModelType model type.

LaplaceReduxModel

Concrete type for neural networks with Laplace Approximation from the LaplaceRedux package. Currently subtyping the AbstractFluxNN model type, although this may be changed to MLJ in the future.

NeuroTreeModel

Concrete type for differentiable tree-based models from NeuroTreeModels. Since NeuroTreeModels has an MLJ interface, we subtype the MLJModelType model type.

RandomForestModel

Concrete type for random forest model from DecisionTree.jl. Since the DecisionTree package has an MLJ interface, we subtype the MLJModelType model type.

Rule

A Rule is just a list of bounds for the different features. See also CRE.

Treat AbstractGenerator as scalar when broadcasting.

Treat AbstractModel as scalar when broadcasting.

Treat AbstractPenalty as scalar when broadcasting.

adjust_shape!(ce::CounterfactualExplanation)

A convenience method that adjusts the dimensions of the counterfactual state and related fields.

adjust_shape(
    ce::CounterfactualExplanation, 
    x::AbstractArray
)

A convenience method that adjusts the dimensions of x.

already_in_target_class(ce::CounterfactualExplanation)

Check if the factual is already in the target class.

apply_domain_constraints!(ce::CounterfactualExplanation)

Wrapper function that applies underlying domain constraints.

apply_mutability(
    ce::CounterfactualExplanation,
    Δcounterfactual_state::AbstractArray,
)

A subroutine that applies mutability constraints to the proposed vector of feature perturbations.

counterfactual(ce::CounterfactualExplanation)

A convenience method that returns the counterfactual.

counterfactual_label(ce::CounterfactualExplanation)

A convenience method that returns the predicted label of the counterfactual.

counterfactual_label_path(ce::CounterfactualExplanation)

Returns the counterfactual labels for each step of the search.

counterfactual_probability(ce::CounterfactualExplanation)

A convenience method that computes the class probabilities of the counterfactual.

counterfactual_probability_path(ce::CounterfactualExplanation)

Returns the counterfactual probabilities for each step of the search.

decode_array(
    data::CounterfactualData,
    dt::CausalInference.SCM,
    x::AbstractArray,
)

Helper function to decode an array x using a data transform dt::GenerativeModels.AbstractGenerativeModel.

decode_array(dt::GenerativeModels.AbstractGenerativeModel, x::AbstractArray)

Helper function to decode an array x using a data transform dt::GenerativeModels.AbstractGenerativeModel.

decode_array(dt::MultivariateStats.AbstractDimensionalityReduction, x::AbstractArray)

Helper function to decode an array x using a data transform dt::MultivariateStats.AbstractDimensionalityReduction.

decode_array(dt::Nothing, x::AbstractArray)

Helper function to decode an array x using a data transform dt::Nothing. This is a no-op.

decode_array(dt::StatsBase.AbstractDataTransform, x::AbstractArray)

Helper function to decode an array x using a data transform dt::StatsBase.AbstractDataTransform.

function decode_state( ce::CounterfactualExplanation, x::Union{AbstractArray,Nothing}=nothing, )

Applies all the applicable decoding functions:

1. If applicable, map the state variable back from the latent space to the feature space.
2. If and where applicable, inverse-transform features.
3. Reconstruct all categorical encodings.

Finally, the decoded counterfactual is returned.

decode_state!(ce::CounterfactualExplanation, x::Union{AbstractArray,Nothing}=nothing)

In-place version of decode_state.

encode_array(data::CounterfactualData, dt::CausalInference.SCM, x::AbstractArray)

Helper function to encode an array x using a data transform dt::CausalInference.SCM. This is a no-op.

encode_array(dt::GenerativeModels.AbstractGenerativeModel, x::AbstractArray)

Helper function to encode an array x using a data transform dt::GenerativeModels.AbstractGenerativeModel.

encode_array(dt::MultivariateStats.AbstractDimensionalityReduction, x::AbstractArray)

Helper function to encode an array x using a data transform dt::MultivariateStats.AbstractDimensionalityReduction.

encode_array(dt::Nothing, x::AbstractArray)

Helper function to encode an array x using a data transform dt::Nothing. This is a no-op.

encode_array(dt::StatsBase.AbstractDataTransform, x::AbstractArray)

Helper function to encode an array x using a data transform dt::StatsBase.AbstractDataTransform.

function encode_state( ce::CounterfactualExplanation, x::Union{AbstractArray,Nothing} = nothing, )

Applies all required encodings to x:

1. If applicable, it maps x to the latent space learned by the generative model.
2. If and where applicable, it rescales features.

Finally, it returns the encoded state variable.

encode_state!(ce::CounterfactualExplanation, x::Union{AbstractArray,Nothing}=nothing)

In-place version of encode_state.

factual(ce::CounterfactualExplanation)

A convenience method to retrieve the factual x.

factual_label(ce::CounterfactualExplanation)

A convenience method to get the predicted label associated with the factual.

factual_probability(ce::CounterfactualExplanation)

A convenience method to compute the class probabilities of the factual.

find_potential_neighbors(ce::AbstractCounterfactualExplanation)

Finds potential neighbors for the selected factual data point.

get_meta(ce::CounterfactualExplanation)

Returns meta data for a counterfactual explanation.

guess_likelihood(y::RawOutputArrayType)

Guess the likelihood based on the scientific type of the output array. Returns a symbol indicating the guessed likelihood and the scientific type of the output array.

guess_loss(ce::CounterfactualExplanation)

Guesses the loss function to be used for the counterfactual search in case likelihood field is specified for the AbstractModel instance and no loss function was explicitly declared for AbstractGenerator instance.

initialize!(ce::CounterfactualExplanation)

Initializes the counterfactual explanation. This method is called by the constructor. It does the following:

1. Creates a dictionary to store information about the search.
2. Initializes the counterfactual state.
3. Initializes the search path.
4. Initializes the loss.

initialize_state!(ce::CounterfactualExplanation)

Initializes the starting point for the factual(s) in-place.

initialize_state(ce::CounterfactualExplanation)

Initializes the starting point for the factual(s):

1. If ce.initialization is set to :identity or counterfactuals are searched in a latent space, then nothing is done.
2. If ce.initialization is set to :add_perturbation, then a random perturbation is added to the factual following following Slack (2021): https://arxiv.org/abs/2106.02666. The authors show that this improves adversarial robustness.

outdim(ce::CounterfactualExplanation)

A convenience method that returns the output dimension of the predictive model.

polynomial_decay(a::Real, b::Real, decay::Real, t::Int)

Computes the polynomial decay function as in Welling et al. (2011): https://www.stats.ox.ac.uk/~teh/research/compstats/WelTeh2011a.pdf.

reset!(flux_training_params::FluxModelParams)

Restores the default parameter values.

steps_exhausted(ce::CounterfactualExplanation)

A convenience method that checks if the number of maximum iterations has been exhausted.

target_probs_path(ce::CounterfactualExplanation)

Returns the target probabilities for each step of the search.

update!(ce::CounterfactualExplanation)

An important subroutine that updates the counterfactual explanation. It takes a snapshot of the current counterfactual search state and passes it to the generator. Based on the current state the generator generates perturbations. Various constraints are then applied to the proposed vector of feature perturbations. Finally, the counterfactual search state is updated.

max_iter(conv::AbstractConvergence)

Returns the maximum number of iterations specified.

All distance measures.

Base type that stores information relevant to energy-based posterior sampling from AbstractModel.

EnergySampler(
    model::AbstractModel,
    𝒟x::Distribution,
    𝒟y::Distribution,
    input_size::Dims,
    yidx::Int;
    opt::Union{Nothing,AbstractSamplingRule}=nothing,
    nsamples::Int=100,
    niter_final::Int=1000,
    ntransitions::Int=0,
    opt_warmup::Union{Nothing,AbstractSamplingRule}=nothing,
    niter::Int=20,
    batch_size::Int=50,
    prob_buffer::AbstractFloat=0.95,
    kwargs...,
)

Constructor for EnergySampler, which is used to sample from the posterior distribution of the model conditioned on y.

Arguments

• model::AbstractModel: The model to be used for sampling.
• data::CounterfactualData: The data to be used for sampling.
• y::Any: The conditioning value.
• opt::AbstractSamplingRule=ImproperSGLD(): The sampling rule to be used. By default, SGLD is used with a = (2 / std(Uniform()) * std(𝒟x) and b = 1 and γ=0.9.
• nsamples::Int=100: The number of samples to include in the final empirical posterior distribution.
• niter_final::Int=1000: The number of iterations for generating samples from the posterior distribution. Typically, this number will be larger than the number of iterations during PMC training.
• ntransitions::Int=0: The number of transitions for (optionally) warming up the sampler. By default, this is set to 0 and the sampler is not warmed up. For valies larger than 0, the sampler is trained through PMC for niter iterations and ntransitions transitions to build a buffer of samples. The buffer is used for posterior sampling.
• opt_warmup::Union{Nothing,AbstractSamplingRule}=nothing: The sampling rule to be used for warm-up. By default, ImproperSGLD is used with α = (2 / std(Uniform()) * std(𝒟x) and γ = 0.005α.
• niter::Int=100: The number of iterations for training the sampler through PMC.
• batch_size::Int=50: The batch size for training the sampler.
• prob_buffer::AbstractFloat=0.5: The probability of drawing samples from the replay buffer. Smaller values will result in more samples being drawn from the prior and typically lead to better mixing and diversity in the samples.
• kwargs...: Additional keyword arguments to be passed on to the sampler and PMC.

Returns

• EnergySampler: An instance of EnergySampler.

EnergySampler(ce::CounterfactualExplanation; kwrgs...)

Overloads the EnergySampler constructor to accept a CounterfactualExplanation object.

Base.rand(sampler::EnergySampler, n::Int=100; retrain=false)

Overloads the rand method to randomly draw n samples from EnergySampler. If from_posterior is true, the samples are drawn from the posterior distribution. Otherwise, the samples are generated from the model conditioned on the target value using a single chain (see generate_posterior_samples).

Arguments

• sampler::EnergySampler: The EnergySampler object to be used for sampling.
• n::Int=100: The number of samples to draw.
• from_posterior::Bool=true: Whether to draw samples from the posterior distribution.
• niter::Int=500: The number of iterations for generating samples through Monte Carlo sampling (single chain).

Returns

• AbstractArray: The samples.

Base.vcat(bmk1::Benchmark, bmk2::Benchmark)

Vertically concatenates two Benchmark objects.

compute_measure(ce::CounterfactualExplanation, measure::Function, agg::Function)

Computes a single measure for a counterfactual explanation. The measure is applied to the counterfactual explanation ce and aggregated using the aggregation function agg.

define_prior(
    data::CounterfactualData;
    𝒟x::Union{Nothing,Distribution}=nothing,
    𝒟y::Union{Nothing,Distribution}=nothing,
    n_std::Int=3,
)

Defines the prior for the data. The space is defined as a uniform distribution with bounds defined by the mean and standard deviation of the data. The bounds are extended by n_std standard deviations.

Arguments

• data::CounterfactualData: The data to be used for defining the prior sampling space.
• n_std::Int=3: The number of standard deviations to extend the bounds.

Returns

• Uniform: The uniform distribution defining the prior sampling space.

distance_from_posterior(ce::AbstractCounterfactualExplanation)

Computes the distance from the counterfactual to generated conditional samples. The distance is computed as the mean distance from the counterfactual to the samples drawn from the posterior distribution of the model. By default, the cosine distance is used.

Arguments

• ce::AbstractCounterfactualExplanation: The counterfactual explanation object.
• nsamples::Int=1000: The number of samples to draw.
• from_posterior::Bool=true: Whether to draw samples from the posterior distribution.
• agg: The aggregation function to use for computing the distance.
• choose_lowest_energy::Bool=true: Whether to choose the samples with the lowest energy.
• choose_random::Bool=false: Whether to choose random samples.
• nmin::Int=25: The minimum number of samples to choose.
• p::Int=1: The norm to use for computing the distance.
• cosine::Bool=true: Whether to use the cosine distance.
• kwargs...: Additional keyword arguments to be passed on to the EnergySampler.

Returns

• AbstractFloat: The distance from the counterfactual to the samples.

generate_posterior_samples(
    e::EnergySampler, n::Int=1000; niter::Int=1000, kwargs...
)

Generates n samples from the posterior distribution of the model conditioned on the target value y. The samples are generated through (Persistent) Monte Carlo sampling using the EnergySampler object. If the replay buffer is not empty, the initial samples are drawn from the buffer.

Note that by default the batch size of the sampler is set to round(Int, n / 100) by default for sampling. This is to ensure that the samples are drawn independently from the posterior distribution. It also helps to avoid vanishing gradients.

The chain is run persistently until n samples are generated. The number of transitions is set to ceil(Int, n / batch_size). Once the chain is run, the last n samples are form the replay buffer are returned.

Arguments

• e::EnergySampler: The EnergySampler object to be used for sampling.
• n::Int=100: The number of samples to generate.
• batch_size::Int=round(Int, n / 100): The batch size for sampling.
• niter::Int=1000: The number of iterations for generating samples from the posterior distribution.
• kwargs...: Additional keyword arguments to be passed on to the sampler.

Returns

• AbstractArray: The generated samples.

get_lowest_energy_sample(sampler::EnergySampler; n::Int=5)

Chooses the samples with the lowest energy (i.e. highest probability) from EnergySampler.

Arguments

• sampler::EnergySampler: The EnergySampler object to be used for sampling.
• n::Int=5: The number of samples to choose.

Returns

• AbstractArray: The samples with the lowest energy.

get_sampler!(ce::AbstractCounterfactualExplanation; kwargs...)

Gets the EnergySampler object from the counterfactual explanation. If the sampler is not found, it is constructed and stored in the counterfactual explanation object.

evaluate_dataframe(
    ce::CounterfactualExplanation,
    measure::Vector{Function},
    agg::Function,
    report_each::Bool,
    pivot_longer::Bool,
    store_ce::Bool,
)

Evaluates a counterfactual explanation and returns a dataframe of evaluation measures.

validity_strict(ce::CounterfactualExplanation)

Checks if the counterfactual search has been strictly valid in the sense that it has converged with respect to the pre-specified target probability γ.

warmup!(
    e::EnergySampler,
    y::Int;
    niter::Int=20,
    ntransitions::Int=100,
    kwargs...,
)

Warms up the EnergySampler to the underlying model for conditioning value y. Specifically, this entails running PMC for niter iterations and ntransitions transitions to build a buffer of samples. The buffer is used for posterior sampling.

Arguments

• e::EnergySampler: The EnergySampler object to be trained.
• y::Int: The conditioning value.
• opt::Union{Nothing,AbstractSamplingRule}: The sampling rule to be used. By default, ImproperSGLD is used with α = 2 * std(Uniform(𝒟x)) and γ = 0.005α.
• niter::Int=20: The number of iterations for training the sampler through PMC.
• ntransitions::Int=100: The number of transitions for training the sampler. In each transition, the sampler is updated with a mini-batch of data. Data is either drawn from the replay buffer or reinitialized from the prior.
• kwargs...: Additional keyword arguments to be passed on to the sampler and PMC.

Returns

• EnergySampler: The trained EnergySampler.

InputTransformer

Abstract type for data transformers. This can be any of the following:

• StatsBase.AbstractDataTransform: A data transformation object from the StatsBase package.
• MultivariateStats.AbstractDimensionalityReduction: A dimensionality reduction object from the MultivariateStats package.
• GenerativeModels.AbstractGenerativeModel: A generative model object from the GenerativeModels module.

TypedInputTransformer

Abstract type for data transformers.

Treat CounterfactualData as scalar when broadcasting.

_subset(data::CounterfactualData, idx::Vector{Int})

Creates a subset of the data.

convert_to_1d(y::Matrix, y_levels::AbstractArray)

Helper function to convert a one-hot encoded matrix to a vector of labels. This is necessary because MLJ models require the labels to be represented as a vector, but the synthetic datasets in this package hold the labels in one-hot encoded form.

Arguments

• y::Matrix: The one-hot encoded matrix.
• y_levels::AbstractArray: The levels of the categorical variable.

Returns

• labels: A vector of labels.

input_dim(counterfactual_data::CounterfactualData)

Helper function that returns the input dimension (number of features) of the data.

mutability_constraints(counterfactual_data::CounterfactualData)

A convenience function that returns the mutability constraints. If none were specified, it is assumed that all features are mutable in :both directions.

outdim(data::CounterfactualData)

Returns the number of output classes.

preprocess_data_for_mlj(data::CounterfactualData)

Helper function to preprocess data::CounterfactualData for MLJ models.

Arguments

• data::CounterfactualData: The data to be preprocessed.

Returns

• (df_x, y): A tuple containing the preprocessed data, with df_x being a DataFrame object and y being a categorical vector.

Example

X, y = preprocessdatafor_mlj(data)

reconstruct_cat_encoding(counterfactual_data::CounterfactualData, x::Vector)

Reconstruct the categorical encoding for a single instance.

subsample(data::CounterfactualData, n::Int)

Helper function to randomly subsample data::CounterfactualData.

train_test_split(data::CounterfactualData;test_size=0.2,keep_class_ratio=false)

Splits data into train and test split.

Arguments

• data::CounterfactualData: The data to be preprocessed.
• test_size=0.2: Proportion of the data to be used for testing.
• keep_class_ratio=false: Decides whether to sample equally from each class, or keep their relative size.

Returns

• (train_data::CounterfactualData, test_data::CounterfactualData): A tuple containing the train and test splits.

Example

train, test = traintestsplit(data, testsize=0.1, keepclass_ratio=true)

unpack_data(data::CounterfactualData)

Helper function that unpacks data.

Base type for custom differentiable models.

Base type for differentiable models.

Abstract types for differentiable models.

Base type for differentiable models written in Flux.

Abstract type for Flux models.

Base type for differentiable models from the MLJ library.

(type::AbstractModelType)(model; likelihood::Symbol=:classification_binary)

Wrap model type around the pre-trained model model.

(type::AbstractModelType)(data::CounterfactualData; kwargs...)

Wrap model type around the data in data. This is a convenience function to avoid having to construct a Model object.

A base type for model differentiability.

Dispatches on the type of model for the differentiability trait.

Fitresult

A struct to hold the results of fitting a model.

Fields

• fitresult: The result of fitting the model to the data. This object should be callable on new data.
• other::Dict: A dictionary to hold any other relevant information.

(fitresult::Fitresult)(newdata::AbstractArray)

When called on new data, the Fitresult object returns the result of calling the fitresult on new data.

(fitresult::Fitresult)()

Concrete type for Flux models.

Struct for models that are differentiable.

Abstract type for MLJ models.

By default, models are assumed not to be differentiable.

binary_to_onehot(p)

Helper function to turn dummy-encoded variable into onehot-encoded variable.

build_ensemble(K::Int;kw=(input_dim=2,n_hidden=32,output_dim=1))

Helper function that builds an ensemble of K models.

build_mlp()

Helper function to build simple MLP.

Examples

nn = build_mlp()

data_loader(data::CounterfactualData)

Prepares counterfactual data for training in Flux.

forward!(model::Flux.Chain, data; loss::Symbol, opt::Symbol, n_epochs::Int=10, model_name="MLP")

Forward pass for training a Flux.Chain model.

load_mnist_model(type::AbstractModelType)

Empty function to be overloaded for loading a pre-trained model for the AbstractModelType model type.

load_mnist_model(type::DeepEnsemble)

Load a pre-trained deep ensemble model for the MNIST dataset.

load_mnist_model(type::MLP)

Load a pre-trained MLP model for the MNIST dataset.

load_mnist_vae(; strong=true)

Load a pre-trained VAE model for the MNIST dataset.

train(M::Model, data::CounterfactualData)

Trains the model M on the data in data.

train(M::FluxModel, data::CounterfactualData; kwargs...)

Wrapper function to train Flux models.

train(
    M::Model,
    type::MLJModelType,
    data::CounterfactualData,
)

Overloads the train function for MLJ models.

train(M::Model, type::DeepEnsemble, data::CounterfactualData; kwargs...)

Overloads the train function for deep ensembles.

Base type of generative model hyperparameter container.

Base type for generative model.

Encoder

Constructs encoder part of VAE: a simple Flux neural network with one hidden layer and two linear output layers for the first two moments of the latent distribution.

VAE <: AbstractGenerativeModel

Constructs the Variational Autoencoder. The VAE is a subtype of AbstractGenerativeModel. Any (sub-)type of AbstractGenerativeModel is accepted by latent space generators.

VAE(input_dim;kws...)

Outer method for instantiating a VAE.

VAEParams <: AbstractGMParams

The default VAE parameters describing both the encoder/decoder architecture and the training process.

Random.rand(encoder::Encoder, x, device=cpu)

Draws random samples from the latent distribution.

Decoder(input_dim::Int, latent_dim::Int, hidden_dim::Int; activation=relu)

The default decoder architecture is just a Flux Chain with one hidden layer and a linear output layer.

decode(generative_model::VAE, x::AbstractArray)

Decodes an array x using the VAE decoder.

encode(generative_model::VAE, x::AbstractArray)

Encodes an array x using the VAE encoder. Specifically, it samples from the latent distribution. It does so by first passing x through the encoder to obtain the mean and log-variance of the latent distribution. Then, it samples from the latent distribution using the reparameterization trick. See Random.rand(encoder::Encoder, x, device=cpu) for more details.

get_data(X::AbstractArray, y::AbstractArray, batch_size)

Preparing data for mini-batch training .

get_data(X::AbstractArray, batch_size)

Preparing data for mini-batch training .

reconstruct(generative_model::VAE, x, device=cpu)

Implements a full pass of some input x through the VAE: x ↦ x̂.

reparameterization_trick(μ,logσ,device=cpu)

Helper function that implements the reparameterization trick: z ∼ 𝒩(μ,σ²) ⇔ z=μ + σ ⊙ ε, ε ∼ 𝒩(0,I).

Type union for acceptable argument types for the penalty field of GradientBasedGenerator.

T-CREx counterfactual generator class.

Convergence.conditions_satisfied(generator::AbstractGradientBasedGenerator, ce::AbstractCounterfactualExplanation)

The default method to check if the all conditions for convergence of the counterfactual search have been satisified for gradient-based generators. By default, gradient-based search is considered to have converged as soon as the proposed feature changes for all features are smaller than one percent of its standard deviation.

_replace_nans(Δcounterfactual_state::AbstractArray, old_new::Pair=(NaN => 0))

Helper function to deal with exploding gradients. This is only a temporary fix and will be improved.

feature_selection!(ce::AbstractCounterfactualExplanation)

Perform feature selection to find the dimension with the closest (but not equal) values between the ce.factual (factual) and ce.counterfactual_state (counterfactual) arrays.

Arguments

• ce::AbstractCounterfactualExplanation: An instance of the AbstractCounterfactualExplanation type representing the counterfactual explanation.

Returns

• nothing

The function iteratively modifies the ce.counterfactual_state counterfactual array by updating its elements to match the corresponding elements in the ce.factual factual array, one dimension at a time, until the predicted label of the modified ce.counterfactual_state matches the predicted label of the ce.factual array.

find_closest_dimension(factual, counterfactual)

Find the dimension with the closest (but not equal) values between the factual and counterfactual arrays.

Arguments

• factual: The factual array.
• counterfactual: The counterfactual array.

Returns

• closest_dimension: The index of the dimension with the closest values.

The function iterates over the indices of the factual array and calculates the absolute difference between the corresponding elements in the factual and counterfactual arrays. It returns the index of the dimension with the smallest difference, excluding dimensions where the values in factual and counterfactual are equal.

find_counterfactual(model, factual_class, counterfactual_data, counterfactual_candidates)

Find the first counterfactual index by predicting labels.

Arguments

• model: The fitted model used for prediction.
• target_class: Expected target class.
• counterfactual_data: Data required for counterfactual generation.
• counterfactual_candidates: The array of counterfactual candidates.

Returns

• counterfactual: The index of the first counterfactual found.

growing_spheres_generation(ce::AbstractCounterfactualExplanation)

Generate counterfactual candidates using the growing spheres generation algorithm.

Arguments

• ce::AbstractCounterfactualExplanation: An instance of the AbstractCounterfactualExplanation type representing the counterfactual explanation.

Returns

• nothing

This function applies the growing spheres generation algorithm to generate counterfactual candidates. It starts by generating random points uniformly on a sphere, gradually reducing the search space until no counterfactuals are found. Then it expands the search space until at least one counterfactual is found or the maximum number of iterations is reached.

The algorithm iteratively generates counterfactual candidates and predicts their labels using the model stored in ce.M. It checks if any of the predicted labels are different from the factual class. The process of reducing the search space involves halving the search radius, while the process of expanding the search space involves increasing the search radius.

h(generator::AbstractGenerator, ce::AbstractCounterfactualExplanation)

Dispatches to the appropriate complexity function for any generator.

h(generator::AbstractGenerator, penalty::Function, ce::AbstractCounterfactualExplanation)

Overloads the h function for the case where a single penalty function is provided.

h(generator::AbstractGenerator, penalty::Nothing, ce::AbstractCounterfactualExplanation)

Overloads the h function for the case where no penalty is provided.

h(generator::AbstractGenerator, penalty::Tuple, ce::AbstractCounterfactualExplanation)

Overloads the h function for the case where a single penalty function is provided with additional keyword arguments.

h(generator::AbstractGenerator, penalty::Tuple, ce::AbstractCounterfactualExplanation)

Overloads the h function for the case where a single penalty function is provided with additional keyword arguments.

hyper_sphere_coordinates(n_search_samples::Int, instance::Vector{Float64}, low::Int, high::Int; p_norm::Int=2)

Generates candidate counterfactuals using the growing spheres method based on hyper-sphere coordinates.

The implementation follows the Random Point Picking over a sphere algorithm described in the paper: "Learning Counterfactual Explanations for Tabular Data" by Pawelczyk, Broelemann & Kascneci (2020), presented at The Web Conference 2020 (WWW). It ensures that points are sampled uniformly at random using insights from: http://mathworld.wolfram.com/HyperspherePointPicking.html

The growing spheres method is originally proposed in the paper: "Comparison-based Inverse Classification for Interpretability in Machine Learning" by Thibaut Laugel et al (2018), presented at the International Conference on Information Processing and Management of Uncertainty in Knowledge-Based Systems (2018).

Arguments

• n_search_samples::Int: The number of search samples (int > 0).
• instance::AbstractArray: The input point array.
• low::AbstractFloat: The lower bound (float >= 0, l < h).
• high::AbstractFloat: The upper bound (float >= 0, h > l).
• p_norm::Integer: The norm parameter (int >= 1).

Returns

• candidate_counterfactuals::Array: An array of candidate counterfactuals.

incompatible(AbstractGenerator, AbstractCounterfactualExplanation)

Checks if the generator is incompatible with any of the additional specifications for the counterfactual explanations. By default, generators are assumed to be compatible.

propose_state(
    ::Models.IsDifferentiable,
    generator::AbstractGradientBasedGenerator,
    ce::AbstractCounterfactualExplanation,
)

Proposes new state based on backpropagation for gradient-based generators and differentiable models.

total_loss(ce::AbstractCounterfactualExplanation)

Computes the total loss of a counterfactual explanation with respect to the search objective.

ℓ(generator::AbstractGenerator, ce::AbstractCounterfactualExplanation)

Dispatches to the appropriate loss function for any generator.

ℓ(generator::AbstractGenerator, loss::Function, ce::AbstractCounterfactualExplanation)

Overloads the ℓ function for the case where a single loss function is provided.

ℓ(generator::AbstractGenerator, loss::Nothing, ce::AbstractCounterfactualExplanation)

Overloads the ℓ function for the case where no loss function is provided.

∂h(generator::AbstractGradientBasedGenerator, ce::AbstractCounterfactualExplanation)

The default method to compute the gradient of the complexity penalty at the current counterfactual state for gradient-based generators. It assumes that Zygote.jl has gradient access.

If the penalty is not provided, it returns 0.0. By default, Zygote never works out the gradient for constants and instead returns 'nothing', so we need to add a manual step to override this behaviour. See here: https://discourse.julialang.org/t/zygote-gradient/26715.

∂ℓ(
    generator::AbstractGradientBasedGenerator,
    ce::AbstractCounterfactualExplanation,
)

The default method to compute the gradient of the loss function at the current counterfactual state for gradient-based generators. It assumes that Zygote.jl has gradient access.

∇(
    generator::AbstractGradientBasedGenerator,
    ce::AbstractCounterfactualExplanation,
)

The default method to compute the gradient of the counterfactual search objective for gradient-based generators. It simply computes the weighted sum over partial derivates. It assumes that Zygote.jl has gradient access. If the counterfactual is being generated using Probe, the hinge loss is added to the gradient.

Penalties that need access to neighbors in the target class.

By default, penalties have no extra requirements.

A base type for a style of process.

The distance_from_target method needs neighbors in the target class.

cos_dist(x,y)

Computes the cosine distance between two vectors.

distance_from_target(
    ce::AbstractCounterfactualExplanation;
    K::Int=50
)

Computes the distance of the counterfactual from samples in the target main. If choose_randomly is true, the function will randomly sample K neighbours from the target manifold. Otherwise, it will compute the pairwise distances and select the K closest neighbours.

Arguments

• ce::AbstractCounterfactualExplanation: The counterfactual explanation.
• K::Int=50: The number of neighbours to sample.
• choose_randomly::Bool=true: Whether to sample neighbours randomly.
• kwrgs...: Additional keyword arguments for the distance function.

Returns

• Δ::AbstractFloat: The distance from the counterfactual to the target manifold.

energy(M::AbstractModel, x::AbstractArray, t::Int)

Computes the energy of the model at a given state as in Altmeyer et al. (2024): https://scholar.google.com/scholar?cluster=3697701546144846732&hl=en&as_sdt=0,5.

energy_constraint(
    ce::AbstractCounterfactualExplanation;
    agg=mean,
    reg_strength::AbstractFloat=0.0,
    decay::AbstractFloat=0.9,
    kwargs...,
)

Computes the energy constraint for the counterfactual explanation as in Altmeyer et al. (2024): https://scholar.google.com/scholar?cluster=3697701546144846732&hl=en&as_sdt=0,5. The energy constraint is a regularization term that penalizes the energy of the counterfactuals. The energy is computed as the negative logit of the target class.

Arguments

• ce::AbstractCounterfactualExplanation: The counterfactual explanation.
• agg::Function=mean: The aggregation function (only applicable in case num_counterfactuals > 1). Default is mean.
• reg_strength::AbstractFloat=0.0: The regularization strength.
• decay::AbstractFloat=0.9: The decay rate for the polynomial decay function (defaults to 0.9). Parameter a is set to 1.0 / ce.generator.opt.eta, such that the initial step size is equal to 1.0, not accounting for b. Parameter b is set to round(Int, max_steps / 20), where max_steps is the maximum number of iterations.
• kwargs...: Additional keyword arguments.

Returns

• ℒ::AbstractFloat: The energy constraint.

function model_loss_penalty(
    ce::AbstractCounterfactualExplanation;
    agg=mean
)

Additional penalty for ClaPROARGenerator.

needs_neighbours(ce::AbstractCounterfactualExplanation)

Check if a counterfactual explanation needs access to neighbors in the target class.

needs_neighbours(gen::AbstractGenerator)

Check if a generator needs access to neighbors in the target class.

Type union for DecisionTree decision tree classifiers and regressors.

Type union for DecisionTree random forest classifiers and regressors.

CounterfactualExplanations.DecisionTreeModel(
    model::AtomicDecisionTree; likelihood::Symbol=:classification_binary
)

Outer constructor for a decision trees.

(generator::Generators.TCRExGenerator)(
    target::RawTargetType,
    data::DataPreprocessing.CounterfactualData,
    M::Models.AbstractModel
)

Applies the Generators.TCRExGenerator to a given target and data using the M model. For details see Bewley et al. (2024) [arXiv, PMLR].

(M::Models.Model)(
    data::CounterfactualData,
    type::CounterfactualExplanations.DecisionTreeModel;
    kwargs...,
)

Constructs a decision tree for the given data. This method is used internally when a decision-tree model is constructed to be trained from scratch (i.e. no pre-trained model is supplied by the user).

(M::Models.Model)(
    data::CounterfactualData, type::CounterfactualExplanations.RandomForestModel; kwargs...
)

Constructs a random forest for the given data.

CounterfactualExplanations.RandomForestModel(
    model::AtomicRandomForest; likelihood::Symbol=:classification_binary
)

Outer constructor for random forests.

Generators.incompatible(gen::FeatureTweakGenerator, ce::CounterfactualExplanation)

Overloads the incompatible function for the FeatureTweakGenerator.

Generators.propose_state(
    generator::Generators.FeatureTweakGenerator, ce::AbstractCounterfactualExplanation
)

Overloads the Generators.propose_state method for the FeatureTweakGenerator.

calculate_delta(ce::AbstractCounterfactualExplanation, penalty::Vector{Function})

Calculates the penalty for the proposed feature tweak.

Arguments

• ce::AbstractCounterfactualExplanation: The counterfactual explanation object.

Returns

• delta::Float64: The calculated penalty for the proposed feature tweak.

classify_prototypes(prototypes, rule_assignments, bounds)

Builds the second tree model using the given prototypes as inputs and their corresponding rule_assignments as labels. Split thresholds are restricted to the bounds, which can be computed using partition_bounds(rules). For details see Bewley et al. (2024) [arXiv, PMLR].

cre(rules, x, X)

Computes the counterfactual rule explanations (CRE) for a given point $x$ and a set of $rules$, where the $rules$ correspond to the set of maximal-valid rules for some given target. For details see Bewley et al. (2024) [arXiv, PMLR].

esatisfactory_instance(generator::FeatureTweakGenerator, x::AbstractArray, paths::Dict{String, Dict{String, Any}})

Returns an epsilon-satisfactory counterfactual for x based on the paths provided.

Arguments

• generator::FeatureTweakGenerator: The feature tweak generator.
• x::AbstractArray: The factual instance.
• paths::Dict{String, Dict{String, Any}}: A list of paths to the leaves of the tree to be used for tweaking the feature.

Returns

• esatisfactory::AbstractArray: The epsilon-satisfactory instance.

Example

esatisfactory = esatisfactory_instance(generator, x, paths) # returns an epsilon-satisfactory counterfactual for x based on the paths provided

extract_leaf_rules(root::DT.Root)

Extracts leaf decision rules (i.e. hyperrectangles) from a decision tree (root). For a decision tree with $L$ leaves this results in $L$ hyperrectangles. The rules are returned as a vector of tuples containing 2-element tuples, where each 2-element tuple stores the lower and upper bound imposed by the given rule for a given feature. For details see Bewley et al. (2024) [arXiv, PMLR].

extract_leaf_rules(node::Union{DT.Leaf,DT.Node}, conditions::AbstractArray, decisions::AbstractArray)

See extract_leaf_rules(root::DT.Root) for details.

extract_rules(root::DT.Root)

Extracts decision rules (i.e. hyperrectangles) from a decision tree (root). For a decision tree with $L$ leaves this results in $2L-1$ hyperrectangles. The rules are returned as a vector of vectors of 2-element tuples, where each tuple stores the lower and upper bound imposed by the given rule for a given feature. For details see Bewley et al. (2024) [arXiv, PMLR].

extract_rules(node::DT.Node, conditions::AbstractArray)

See extract_rules(root::DT.Root).

get_individual_classifiers(M::Model)

Returns the individual classifiers in the forest. If the input is a decision tree, the method returns the decision tree itself inside an array.

Arguments

• M::Model: The model selected by the user.
• model::CounterfactualExplanations.D

Returns

• classifiers::AbstractArray: An array of individual classifiers in the forest.

grow_surrogate(
    generator::Generators.TCRExGenerator, X::AbstractArray, ŷ::AbstractArray
)

Grows the tree-based surrogate model for the Generators.TCRExGenerator. For details see Bewley et al. (2024) [arXiv, PMLR].

grow_surrogate(
    generator::Generators.TCRExGenerator, data::CounterfactualData, M::AbstractModel
)

Overloads the grow_surrogate function to accept a CounterfactualData and a AbstractModel to grow a surrogate model. See grow_surrogate(generator::Generators.TCRExGenerator, X::AbstractArray, ŷ::AbstractArray).

induced_grid(rules)

Computes the induced grid of the given rules. For details see Bewley et al. (2024) [arXiv, PMLR]..

issubrule(rule, otherrule)

Checks if the rule hyperrectangle is a subset of the otherrule hyperrectangle. For details see Bewley et al. (2024) [arXiv, PMLR].

max_valid(rules, X, fx, target, τ)

Returns the maximal-valid rules for a given target and accuracy threshold τ. For details see Bewley et al. (2024) [arXiv, PMLR].

partition_bounds(rules, dim::Int)

Computes the set of (unique) bounds for each rule in rules along the dim-th dimension. For details see Bewley et al. (2024) [arXiv, PMLR].

partition_bounds(rules)

Computes the set of (unique) bounds for each rule in rules and all dimensions. For details see Bewley et al. (2024) [arXiv, PMLR].

prototype(rule, X; pick_arbitrary::Bool=true)

Picks an arbitrary point $x^C \in X$ (i.e. prototype) from the subet of $X$ that is contained by rule $R_i$. If pick_arbitrary is set to false, the prototype is instead computed as the average across all samples. For details see Bewley et al. (2024) [arXiv, PMLR].

rule_accuracy(rule, X, fx, target)

Computes the accuracy of the rule on the data X for predicted outputs fx and the target. Accuracy is defined as the fraction of points contained by the rule, for which predicted values match the target. For details see Bewley et al. (2024) [arXiv, PMLR].

rule_changes(rule, x)

Computes the number of feature changes necessary for x to be contained by rule $R_i$. For details see Bewley et al. (2024) [arXiv, PMLR].

rule_contains(rule, X)

Returns the subet of X that is contained by rule $R_i$. For details see Bewley et al. (2024) [arXiv, PMLR].

rule_cost(rule, x, X)

Computes the cost for $x$ to be contained by rule $R_i$, where cost is defined as rule_changes(rule, x) - rule_feasibility(rule, X). For details see Bewley et al. (2024) [arXiv, PMLR].

rule_feasibility(rule, X)

Computes the feasibility of a rule $R_i$ for a given dataset. Feasibility is defined as fraction of the data points that satisfy the rule. For details see Bewley et al. (2024) [arXiv, PMLR].

search_path(tree::Union{DT.Leaf, DT.Node}, target::RawTargetType, path::AbstractArray)

Return a path index list with the inequality symbols, thresholds and feature indices.

Arguments

• tree::Union{DT.Leaf, DT.Node}: The root node of a decision tree.
• target::RawTargetType: The target class.
• path::AbstractArray: A list containing the paths found thus far.

Returns

• paths::AbstractArray: A list of paths to the leaves of the tree to be used for tweaking the feature.

Example

paths = search_path(tree, target) # returns a list of paths to the leaves of the tree to be used for tweaking the feature

wrap_decision_tree(node::TreeNode, X, y)

Turns a custom decision tree into a DecisionTree.Root object from the DecisionTree.jl package.

wrap_decision_tree(node::TreeNode)

See wrap_decision_tree(node::TreeNode, X, y).

CounterfactualExplanations.JEM(
    model::JointEnergyModels.JointEnergyClassifier; likelihood::Symbol=:classification_multi
)

Outer constructor for a neural network with Laplace Approximation from LaplaceRedux.jl.

Models.Model(model, type::CounterfactualExplanations.JEM; likelihood::Symbol=:classification_multi)

Overloaded constructor for Flux models.

(M::Model)(data::CounterfactualData, type::JEM; kwargs...)

Constructs a differentiable tree-based model for the given data.

Models.load_mnist_model(type::CounterfactualExplanations.JEM)

Overload for loading a pre-trained model for the JEM model type.

Models.logits(M::JEM, X::AbstractArray)

Calculates the logit scores output by the model M for the input data X.

Arguments

• M::JEM: The model selected by the user. Must be a model from the MLJ library.
• X::AbstractArray: The feature vector for which the logit scores are calculated.

Returns

• logits::Matrix: A matrix of logits for each output class for each data point in X.

Example

logits = Models.logits(M, x) # calculates the logit scores for each output class for the data point x

Models.probs(
    M::Models.Model,
    type::CounterfactualExplanations.JEM,
    X::AbstractArray,
)

Overloads the Models.probs method for NeuroTree models.

train(M::JEM, data::CounterfactualData; kwargs...)

Fits the model M to the data in the CounterfactualData object. This method is not called by the user directly.

Arguments

• M::JEM: The wrapper for an JEM model.
• data::CounterfactualData: The CounterfactualData object containing the data to be used for training the model.

Returns

• M::JEM: The fitted JEM model.

CounterfactualExplanations.LaplaceReduxModel(
    model::LaplaceRedux.Laplace; likelihood::Symbol=:classification_binary
)

Outer constructor for a neural network with Laplace Approximation from LaplaceRedux.jl.

(M::Model)(data::CounterfactualData, type::LaplaceReduxModel; kwargs...)

Constructs a differentiable tree-based model for the given data.

logits(M::LaplaceReduxModel, X::AbstractArray)

Predicts the logit scores for the input data X using the model M.

probs(M::LaplaceReduxModel, X::AbstractArray)

Predicts the probabilities of the classes for the input data X using the model M.

train(M::LaplaceReduxModel, data::CounterfactualData; kwargs...)

Fits the model M to the data in the CounterfactualData object. This method is not called by the user directly.

Arguments

• M::LaplaceReduxModel: The wrapper for an LaplaceReduxModel model.
• data::CounterfactualData: The CounterfactualData object containing the data to be used for training the model.

Returns

• M::LaplaceReduxModel: The fitted LaplaceReduxModel model.

Type union for NeuroTree classifiers and regressors.

(M::Model)(data::CounterfactualData, type::NeuroTreeModel; kwargs...)

Constructs a differentiable tree-based model for the given data.

CounterfactualExplanations.NeuroTreeModel(
    model::AtomicNeuroTree; likelihood::Symbol=:classification_binary
)

Outer constructor for a differentiable tree-based model from NeuroTreeModels.jl.

Models.logits(M::NeuroTreeModel, X::AbstractArray)

Calculates the logit scores output by the model M for the input data X.

Arguments

• M::NeuroTreeModel: The model selected by the user. Must be a model from the MLJ library.
• X::AbstractArray: The feature vector for which the logit scores are calculated.

Returns

• logits::Matrix: A matrix of logits for each output class for each data point in X.

Example

logits = Models.logits(M, x) # calculates the logit scores for each output class for the data point x

Models.probs(
    M::Models.Model,
    type::CounterfactualExplanations.NeuroTreeModel,
    X::AbstractArray,
)

Overloads the probs method for NeuroTree models.

train(M::NeuroTreeModel, data::CounterfactualData; kwargs...)

Fits the model M to the data in the CounterfactualData object. This method is not called by the user directly.

Arguments

• M::NeuroTreeModel: The wrapper for an NeuroTree model.
• data::CounterfactualData: The CounterfactualData object containing the data to be used for training the model.

Returns

• M::NeuroTreeModel: The fitted NeuroTree model.