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.

An abstract type that serves as the base type for measures. Objects of type AbstractMeasure need to be callable.

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.

(ce::CounterfactualExplanation)()::FlattenedCE

Calling the ce::CounterfactualExplanation object results in a FlattenedCE instance, which is the flattened version of the original.

EncodedOutputArrayType

Type of encoded output array.

EncodedTargetType

Type of encoded target variable.

FlattenedCE <: AbstractCounterfactualExplanation

A flattened representation of a CounterfactualExplanation, containing only the factual, target, and counterfactual attributes. This can be useful for compact storage or transmission of explanations.

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.

flatten(ce::CounterfactualExplanation)

Alias for (ce::CounterfactualExplanation)(). Converts a CounterfactualExplanation to its flattened form.

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,
    return_flattened::Bool=false,
)

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.
• return_flattened::Bool: If true, the flattened CE is returned instead of a CE object.
• callback::Union{Nothing,Function}: An optional callback function that takes a CounterfactualExplanation as its only positional input.

Examples

Generic generator

julia> using CounterfactualExplanations

julia> using CounterfactualExplanations.Generators

julia> using CounterfactualExplanations.Models

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(Models.predict_label(M, counterfactual_data) .== factual));

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

julia> generator = Generators.GenericGenerator();

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

julia> CounterfactualExplanations.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> using CounterfactualExplanations

julia> using CounterfactualExplanations.Generators

julia> using CounterfactualExplanations.Models

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(Models.predict_label(M, counterfactual_data) .== factual), 5);

julia> xs = CounterfactualExplanations.select_factual(counterfactual_data, chosen);

julia> generator = Generators.GenericGenerator();

julia> ces = generate_counterfactual.(xs, target, counterfactual_data, M, 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_global_ad_backend()

Get the currently set automatic differentiation backend.

Returns

• The global automatic differentiation backend as an instance of DI.AutoZygote.

get_target_index(y_levels, target)

Utility that returns the index of target in y_levels.

num_counterfactuals(flat_ce::FlattenedCE)

Extends the num_counterfactuals method to FlattenedCE.

path(ce::CounterfactualExplanation)

A convenience method that returns the entire counterfactual path.

set_global_ad_backend(backend)

Set the global automatic differentiation backend.

Arguments

• backend: The new backend to set, which must be an instance of DI.AbstractBackend.

target_encoded(ce::CounterfactualExplanation, data::CounterfactualData)

Returns the encoded representation of ce.target.

target_encoded(flat_ce::FlattenedCE, data::CounterfactualData)

Returns the encoded representation of flat_ce.target.

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::AbstractCounterfactualExplanation)

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::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(
    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::InvalidationRateConvergence,
    ce::AbstractCounterfactualExplanation,
    x::Union{AbstractArray,Nothing}=nothing,
)

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

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.

invalidation_rate(ce::AbstractCounterfactualExplanation)

Single-argument method for convenience.

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

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

Global serializer state (allows or disallows serialization).

All measures.

The default evaluation measures.

All distance measures.

Available plausibility 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).

Benchmark(evaluation::DataFrames.DataFrame; counterfactuals=nothing)

Constructs a Benchmark from an evaluation DataFrame.

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

Returns a DataFrame containing evaluation measures aggregated by num_counterfactual.

Default output identifier (no specific ID).

The ExplicitCETransformer can be used to specify any arbitrary CE transformation.

And explicit output identifier that takes the string value of id.

Default CE transformer that returns the input as is.

MMD{K<:KernelFunctions.Kernel} <: AbstractDivergenceMetric

Concrete type for the Maximum Mean Discrepancy (MMD) metric.

(m::MMD)(
    x::AbstractArray,
    y::AbstractArray,
    n::Int;
    kwrgs...
)

Computes the MMD between two datasets x and y, along with a p-value based on a null distribution of MMD values (unless m.compute_p=nothing) for a random subset of the data (of sample size n). The p-value is computed using a permutation test.

(m::MMD)(x::AbstractArray, y::AbstractArray)

Computes the maximum mean discrepancy (MMD) between two datasets x and y. The MMD is a measure of the difference between two probability distributions. It is defined as the maximum value of the kernelized dot product between the two datasets. It is computed as the sum of average kernel values between columns (samples) of x and y, minus twice the average kernel value between columns (samples) of x and y. A larger MMD value indicates that the distributions are more different, while a value closer to zero suggests they are more similar. See also kernelsum.

Null serializer (does not allow serialization).

Standard serializer (allows serialization).

benchmark(
    data::CounterfactualData;
    test_data::Union{Nothing,CounterfactualData}=nothing,
    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,
    n_runs::Int=1,
    suppress_training::Bool=false,
    factual::Union{Nothing,RawTargetType}=nothing,
    target::Union{Nothing,RawTargetType}=nothing,
    store_ce::Bool=false,
    parallelizer::Union{Nothing,AbstractParallelizer}=nothing,
    dataname::Union{Nothing,Symbol,String}=nothing,
    verbose::Bool=true,
    vertical_splits::Union{Nothing,Int}=nothing,
    storage_path::String=tempdir(),
    kwrgs...,
)

Benchmark a set of counterfactuals for a given data set and additional inputs.

Arguments

• data::CounterfactualData: The dataset containing the factual and target labels.
• test_data::Union{Nothing,CounterfactualData}: Optional test data for evaluation. Defaults to nothing, in which case data is used for evaluation.
• models::Dict{<:Any,<:Any}: A dictionary of model objects keyed by their names. Defaults to standard_models_catalogue.
• generators::Union{Nothing,Dict{<:Any,<:AbstractGenerator}}: Optional dictionary of generator functions keyed by their names. Defaults to nothing, in which case the whole generator_catalogue is used.
• measure::Union{Function,Vector{<:Function}}: The measure(s) to evaluate the counterfactuals against. Defaults to default_measures.
• n_individuals::Int=5: Number of individuals to generate for each model and generator.
• n_runs::Int=1: Number of runs for each model and generator.
• suppress_training::Bool=false: Whether to suppress training of models during benchmarking. This is useful if models have already been trained.
• factual::Union{Nothing,RawTargetType}: Optional factual label. Defaults to nothing, in which case factual labels are randomly sampled from the dataset.
• target::Union{Nothing,RawTargetType}: Optional target label. Defaults to nothing, in which case target labels are randomly sampled from the dataset.
• store_ce::Bool=false: Whether to store the CounterfactualExplanation objects for each counterfactual.
• parallelizer::Union{Nothing,AbstractParallelizer}=nothing: Parallelization strategy for generating and evaluating counterfactuals.
• dataname::Union{Nothing,Symbol,String}=nothing: Name of the dataset. Defaults to nothing.
• verbose::Bool=true: Whether to print verbose output during benchmarking.
• vertical_splits::Union{Nothing,Int}=nothing: Number of elements per vertical split for generating counterfactuals. Defaults to nothing. This can useful, if it is necessary to reduce peak memory usage, by decreasing the number of counterfactuals generated at once. Lower values lead to smaller batches and hence smaller peak load.
• storage_path::String=tempdir(): Path where interim results will be stored. Defaults to tempdir().
• concatenate_output::Bool=true: Whether to collect output from each run and concatenate them into a single output file.

Returns

• A dictionary containing the benchmark results, including mean and standard deviation of the measures across all runs.

Benchmarking Procedure

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 chunks of vertical_splits each. 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.

concatenate_benchmarks(storage_path::String)

Concatenates all benchmarks stored in storage_path into a single benchmark.

evaluate(
    ce::CounterfactualExplanation,
    meta_data::Union{Nothing,Dict}=nothing;
    measure::Union{Function,Vector{<:Function}}=default_measures,
    agg::Function=mean,
    report_each::Bool=false,
    output_format::Symbol=:Vector,
    pivot_longer::Bool=true,
    store_ce::Bool=false,
    report_meta::Bool=false,
)

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.

Arguments:

• ce: The counterfactual explanation to evaluate.
• meta_data: A vector of dictionaries containing meta data for each counterfactual explanation. If not provided, the default meta data is inferred from the counterfactual explanations.
• measure: The evaluation measures to compute. By default, all available measures are computed.
• agg: The aggregation function to use for the evaluation measures. By default, the mean is used.
• report_each: If true, each evaluation measure is reported separately. Otherwise, the mean of all measures is reported.
• output_format: The format of the output. By default, a vector is returned.
• pivot_longer: If true, the evaluation measures are pivoted longer. Otherwise, they are stacked.
• store_ce: If true, the counterfactual explanation is stored in the evaluation DataFrame. Note: These objects are potentially large and can consume a lot of memory.
• report_meta: If true, meta data is reported. Otherwise, it is not.

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).

feature_sensitivity(
    ce::AbstractCounterfactualExplanation, d::Union{Int,Vector{Int}}=[1]; kwrgs...
)

Return the sensitivity to feature(s) d in terms of absolute changes associated with the counterfactual. Any keyword arguments accepted by distance can be passed to kwrgs....

Get the global CE transformer.

global_ce_transform(transformer::AbstractCETransformer)

Sets the global CE transformer to transformer.

global_output_identifier(identifier::AbstractOutputIdentifier)

Set the global output identifier to identifier and return its string representation. The global output identifier is used by default for all serialization operations.

global_serializer(serializer::AbstractSerializer)

Set the global serializer to serializer and return its state. The global serializer is used by default for all serialization operations.

mmd_null_dist(
    x::AbstractArray, y::AbstractArray, k::KernelFunctions.Kernel=default_kernel; l=1000
)

Compute the null distribution of MMD for two samples x and y through bootstrapping as follows:

1. For each bootstrap sample, shuffle the columns of x and y.
2. Compute the MMD between the shuffled samples.
3. Repeat this process l times to obtain a null distribution of MMD values.
4. Return the null distribution of MMD values.

Under the null hypothesis x and y are actually from the same distribution.

mmd_significance(mmd::Number, mmd_null_dist::AbstractArray)

Compute the p-value of the MMD test as the proportion of MMD values in the null distribution that are greater than or equal to the observed MMD value.

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 distance between the counterfactual and samples drawn from the target distribution.

plausibility(
    ce::CounterfactualExplanation,
    fun::typeof(Objectives.distance_from_target_cosine);
    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_cosine(ce::CounterfactualExplanation; kwrgs...)

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

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

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

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

Computes the plausibility of a counterfactual explanation based on the energy differential 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 in that the predicted label corresponds to the specified target. 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.

mutability_constraints!(counterfactual_data::CounterfactualData, mutability)

Applies provided mutability constraints in-place to existing data.

mutability_constraints(counterfactual_data::CounterfactualData, mutability::Nothing)

If nothing is supplied, all features are assumed to be mutable in both directions.

mutabilityconstraints(counterfactualdata::CounterfactualData, mutability::Vector{Symbol})

If mutability is already a vector of integers, these are assumed to be indices of immutable features. All other features are assumed to be mutable in both directions. This offers a convenient way to quickly specify immutable features.

mutabilityconstraints(counterfactualdata::CounterfactualData, mutability::Vector{Symbol})

If mutability is already a vector of symbols, it is returned as is.

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.

mutability_constraints(counterfactual_data::CounterfactualData, mutability::Pair{K,V}...) where {K<:Int,V<:Symbol}

If pairs of feature indices (::Int) and constraints (::Symbol) are supplied, the given constraints are applied to the corresponding features. All other features are assumed to be mutable in both directions.

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.

To Do:

Refactor this to be less convoluted and bring in line with current MLJ API.

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::Optimisers.AbstractRule=Optimisers.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::Optimisers.AbstractRule=Optimisers.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.

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

Outer constructor for the JSMADescent rule.

T-CREx counterfactual generator class.

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

For details, see Pawelczyk et al. (2022).

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.

choose_ad_backend(backends::Vararg{<:Any})

Select a single automatic differentiation backend from multiple provided backends.

Arguments

• backends::Vararg{<:Any}: Variable number of AD backend instances (e.g., AutoZygote(), AutoEnzyme()).

Returns

• AutoZygote() if all provided backends are AutoZygote instances.
• The single non-AutoZygote backend if exactly one is provided among AutoZygote instances.

Throws

• AssertionError if more than one non-AutoZygote backend is provided.

Examples

choose_ad_backend(AutoZygote(), AutoZygote())  # Returns AutoZygote()
choose_ad_backend(AutoZygote(), AutoEnzyme())  # Returns AutoEnzyme()
choose_ad_backend(AutoZygote(), AutoEnzyme(), AutoForwardDiff())  # Throws AssertionError

choose_ad_backend(ce::CounterfactualExplanation)

Select a compatible automatic differentiation backend for a counterfactual explanation.

Determines the AD backend by querying the backends of the model and generator within the counterfactual explanation, then reconciling them into a single compatible backend.

Arguments

• ce::CounterfactualExplanation: A counterfactual explanation object containing a model (M) and a generator.

Returns

• A single AD backend compatible with both the model and generator.

Throws

• AssertionError if the model and generator use incompatible non-AutoZygote backends.

See Also

• choose_ad_backend(backends::Vararg)

choose_ad_backend(gen::AbstractGenerator)

Choose an appropriate automatic differentiation backend for a given generator based on its penalty function. Handles both simple cases (no penalty function) and complex cases where multiple penalties might require different AD backends, ensuring that these backends are mutually exclusive.

Chooses the appropriate AD backend for the given model type

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

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

ddp_diversity(ce::AbstractCounterfactualExplanation; kwargs...)

Convenience method that computes cf from ce.

distance(
    cf::AbstractArray,
    from::AbstractArray;
    agg=mean,
    p::Real=1,
    weights::Union{Nothing,AbstractArray}=nothing,
    cosine::Bool=false,
    d::Union{Nothing,Vector{Int}}=nothing,
)

Computes the distance of the counterfactual to the original factual.

distance(ce::AbstractCounterfactualExplanation; kwrgs...)

Overloads method to be applied directly to ce

distance_cosine(ce::AbstractCounterfactualExplanation)

Computes the distance of the counterfactual to the original factual using cosine similarity. See also: cos_dist.

distance_cosine(ce::AbstractCounterfactualExplanation; kwargs...)

Convenience method that computes cf from ce.

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.

distance_from_target(ce::AbstractCounterfactualExplanation; kwargs...)

Convenience method that computes cf from ce.

distance_from_target_cosine(ce::AbstractCounterfactualExplanation;kwrgs...)

Compute the distance from a counterfactual to the target manifold using cosine similarity. See also: cos_dist.

Arguments

• ce::AbstractCounterfactualExplanation: The counterfactual explanation object.
• kwrgs...: Additional keyword arguments for the distance function.

distance_from_target_cosine(ce::AbstractCounterfactualExplanation; kwargs...)

Convenience method that computes cf from ce.

distance_l0(ce::AbstractCounterfactualExplanation)

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

distance_l0(ce::AbstractCounterfactualExplanation; kwargs...)

Convenience method that computes cf from ce.

distance_l1(ce::AbstractCounterfactualExplanation)

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

distance_l1(ce::AbstractCounterfactualExplanation; kwargs...)

Convenience method that computes cf from ce.

distance_l2(ce::AbstractCounterfactualExplanation)

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

distance_l2(ce::AbstractCounterfactualExplanation; kwargs...)

Convenience method that computes cf from ce.

distance_linf(ce::AbstractCounterfactualExplanation)

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

distance_linf(ce::AbstractCounterfactualExplanation; kwargs...)

Convenience method that computes cf from ce.

distance_mad(ce::AbstractCounterfactualExplanation; agg=mean)

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

distance_mad(ce::AbstractCounterfactualExplanation; kwargs...)

Convenience method that computes cf from ce.

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.

hinge_loss(ce::AbstractCounterfactualExplanation)

Convenience method that computes cf from ce.

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.

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.

The LaplaceReduxModel model type requires ForwardDiff

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,
    grad_ce_state::AbstractArray,
)

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

counterfactual(ce::AbstractCounterfactualExplanation)

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::AbstractCounterfactualExplanation)

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_neighbours(ce::CounterfactualExplanation, n::Int=1000)

Overloads the function for CounterfactualExplanation to use the counterfactual data's labels if no data is provided.

find_potential_neighbours(
    ce::AbstractCounterfactualExplanation, data::CounterfactualData, n::Int=1000
)

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::AbstractCounterfactualExplanation)

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.

An abstract type for CE transformers.

Abstract type for output identifiers.

Abstract type for serializers.

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.

Serializer that does not allow serialization.

Serializer that allows serialization.

Transformation function for explicit transformer.

Transformation function for default transformer.

Global CE transformer.

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

For abstract divergence metrics, returns a vector of NaN values.

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_benchmark_files(storage_path::String)

Returns a list of all benchmark files stored in storage_path.

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.

includes_divergence_metric(measure::Union{Function,Vector{<:Function}})

Checks if the provided measure includes a divergence metric.

kernelsum(k::KernelFunctions.Kernel, x::AbstractMatrix, y::AbstractMatrix)

Compute the sum of kernel matrices between two matrices x and y. This function sums all kernel evaluations comparing columns in x to columns in y.

kernelsum(k::KernelFunctions.Kernel, x::AbstractMatrix)

Compute the sum of kernel matrices between x and itself. This function sums all kernel evaluations comparing columns in x to each other and subtracts the trace of the resulting matrix to account for self-evaluations. The result is then divided by (m^2 - m) where m is the number of columns in x. This effectively gives you the mean of all pairwise kernel evaluations excluding self-evaluations.

kernelsum(k::KernelFunctions.Kernel, x::AbstractVector)

Compute the sum of kernel matrices between x and itself where x is a vector. This function returns 0 for vectors since there are no pairs to compute the kernel matrix.

needs_ce(store_ce::Bool,measure::Union{Function,Vector{<:Function}})

A helper function to determine if counterfactual explanations should be stored based on the given store_ce flag and the presence of a divergence metric in the measure.

samplecolumns([rng::AbstractRNG], x::AbstractMatrix, n::Int)

Sample n columns from a matrix. Returns x if the matrix has less than n columns.

to_dataframe(
    computed_measures::Vector,
    measure,
    report_each::Bool,
    pivot_longer::Bool,
    store_ce::Bool,
    ce::CounterfactualExplanation,
)

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

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

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::AbstractMatrix, 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.

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.

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(grad_ce_state::AbstractArray, old_new::Pair=(NaN => 0))

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

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

The default method to compute the gradient of the loss function at the current counterfactual state for gradient-based generators.

grad_pen(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.

grad_search_opt(
    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 derivatives. It assumes that Zygote.jl has gradient access. If the counterfactual is being generated using Probe, the hinge loss is added to the gradient.

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.

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.

A base type for AD backend requirements

The energy_constraint function requires ForwardDiff

The hinge_loss function requires ForwardDiff

This trait implies that ForwardDiff is required.

Penalties that need access to neighbors in the target class.

By default, no special AD backend is required.

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.

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.

energy_constraint(ce::AbstractCounterfactualExplanation; kwargs...)

Convenience method that computes cf from ce.

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

Additional penalty for ClaPROARGenerator.

model_loss_penalty(ce::AbstractCounterfactualExplanation; kwargs...)

Convenience method that computes cf from ce.

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 JointEnergyClassifier from JointEnergyModels.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.