Reference

Base type of training objectives.

(obj::AdversarialObjective)(
    yhat,
    y,
    energy_differential::Vector{<:AbstractFloat}=[0.0f0],
    regularization::Vector{<:AbstractFloat}=[0.0f0],
    adversarial_loss::Union{AbstractFloat,Vector{<:AbstractFloat}}=0.0f0;
    agg=mean,
    kwrgs...,
)

If the adversarial_loss has been computed already, obj::AdversarialObjective can be called directly on predictions yhat and labels y. The different loss components are then added together with a weighting vector lambda.

AdversarialObjective <: AbstractObjective

The AdversarialObjective is a concrete implementation of the AbstractObjective abstract type that optimizes for:

1. Standard classification objective (the discriminative task).
2. Adversarial classification objective on the counterfactuals (the explainability task).

AdversarialObjective(;
    class_loss::Function=Flux.Losses.logitcrossentropy,
    lambda::Vector{<:AbstractFloat}=[1.0, 0.25]
)

Outer constructor for the AdversarialObjective type.

(obj::EnergyDifferentialObjective)(
    yhat,
    y,
    energy_differential::Vector{<:AbstractFloat}=[0.0f0],
    regularization::Vector{<:AbstractFloat}=[0.0f0],
    adversarial_loss::Union{AbstractFloat,Vector{<:AbstractFloat}}=0.0f0;
    agg=mean,
    kwrgs...,
)

If the energy_differential and regularization have been computed already, obj::EnergyDifferentialObjective can be called directly on predictions yhat and labels y. The different loss components are then added together with a weighting vector lambda.

EnergyDifferentialObjective <: AbstractObjective

The EnergyDifferentialObjective is a concrete implementation of the AbstractObjective abstract type that optimizes for:

1. Standard classification objective (the discriminative task)
2. Energy differential between counterfactuals and observed data (the explainability task).

EnergyDifferentialObjective(;
    class_loss::Function=Flux.Losses.logitcrossentropy, 
    lambda::Vector{<:AbstractFloat}=[1.0, 0.5, 0.1]
)

Outer constructor for the EnergyDifferentialObjective type.

(obj::FullObjective)(
    yhat,
    y,
    energy_differential::Vector{<:AbstractFloat}=[0.0f0],
    regularization::Vector{<:AbstractFloat}=[0.0f0],
    adversarial_loss::Union{AbstractFloat,Vector{<:AbstractFloat}}=[0.0f0];
    agg=mean,
    kwrgs...,
)

If the adversarial_loss has been computed already, obj::FullObjective can be called directly on predictions yhat and labels y. The different loss components are then added together with a weighting vector lambda.

FullObjective <: AbstractObjective

The FullObjective is a concrete implementation of the AbstractObjective abstract type that optimizes for all three tasks:

1. Standard classification objective (the discriminative task)
2. Energy differential between counterfactuals and observed data (the explainability task).
3. Adversarial classification objective on the counterfactuals (the explainability task).

FullObjective(;
    class_loss::Function=Flux.Losses.logitcrossentropy,
    energy_differential::PenaltyOrFun=EnergyDifferential(),
    lambda::Vector{<:AbstractFloat}=[1.0, 0.5, 0.1, 0.25]
)

Outer constructor for the FullObjective type.

(obj::VanillaObjective)(
    yhat,
    y,
    energy_differential::Vector{<:AbstractFloat}=[0.0f0],
    regularization::Vector{<:AbstractFloat}=[0.0f0],
    adversarial_loss::Union{AbstractFloat,Vector{<:AbstractFloat}}=0.0f0;
    agg=mean,
    kwrgs...,
)

obj::VanillaObjective can be called directly on predictions yhat and labels y.

VanillaObjective <: AbstractObjective

The VanillaObjective is a concrete implementation of the AbstractObjective abstract type that optimizes for:

1. Standard classification objective (the discriminative task).

VanillaObjective(class_loss, lambda; needs_ce=false)

Outer constructor to allow passing just class_loss and lambda as positional arguments.

VanillaObjective(;
    class_loss::Function=Flux.Losses.logitcrossentropy,
    lambda::Vector{<:AbstractFloat}=[1.0],
    needs_ce::Bool=false,
)

Outer constructor for the VanillaObjective type.

accuracy(model, train_set)

Compute classification accuracy over a DataLoader. Uses Flux.onecold on whole matrices — GPU-compatible and faster than per-column argmax.

adv_loss(
    model, counterfactual, perturbations, targets; epsilon=2.0, p::Real=Inf, validities=nothing
)

Adversarial loss function.

generate!(
    model,
    data,
    generator::AbstractGenerator;
    nsamples::Union{Int,Nothing}=nothing,
    convergence=Convergence.MaxIterConvergence(),
    parallelizer=nothing,
    input_encoder=nothing,
    verbose=1,
    domain=nothing,
)

This function generates counterfactual explanations for the whole dataset data or a subset thereof (nsamples). It is supposed to be used outside of the mini-batch training loop.

get_global_ae_criterium()

Get the global AE criterium.

get_last_valid_ae(ce::CounterfactualExplanation)

A callback function used to store the last counterfactual that is also a valid adversarial example based on the global AE criterium (see get_global_ae_criterium).

implausibility(model, counterfactual, samples, targets)

Compute the implausibility (contrastive divergence) of the counterfactuals (counterfactual) with respect to samples in the target class. This is computed as the difference between negative logits indexed at the target class for the samples and the counterfactual.

infer_domain_constraints(X::AbstractArray; nstd=3)

Automatically infers reasonable domain constraints for the counterfactuals.

isvalid(ce, model, data)

Checks if the label has been flipped.

protect_immutable!(
    samples::AbstractArray,
    counterfactuals::AbstractArray,
    mutability::Union{Nothing,AbstractArray},
)

Protects immutable features from the contrastive divergence penalty.

reg_loss(model, counterfactual, samples, targets)

Compute the regularization loss for the contrastice divergence.

setup_counterfactual_search(
    data,
    model,
    domain,
    input_encoder,
    mutability,
    nneighbours::Int64,
    nsamples::Union{Nothing,Int64},
)

Sets up the counterfactual search.

unwrap(train_set; labels=nothing)

Unwraps the data from a Flux.DataLoader or zip iterator. The output variables is assumed to be categorical. If no labels are provided, then 1 to n is used where n is the number of classes.

NativeGenerator

Lightweight generator for batched counterfactual search. Holds only the fields needed by generate_counterfactuals!: penalty weights λ and a Flux optimiser opt.

This avoids the Flux 0.16 incompatibility in CE.jl's GradientBasedGenerator (whose opt field is typed against the old Flux.Optimise.AbstractOptimiser).

Keyword fields

• λ::Vector{Float32} — penalty weights [λ₁, λ₂] for the L1 distance penalty and the energy constraint (default [0.1f0, 1.0f0]).
• opt — a Flux optimiser (default Flux.Descent(0.1f0)).

batched_apply_domain_constraints!(X′::AbstractMatrix, data::CounterfactualData)

Clamps each feature row of X′ to the domain bounds stored in data.domain.

batched_apply_mutability!(ΔX::AbstractMatrix, mutability)

Zeros out gradient components along immutable feature directions in-place. mutability is a vector of Symbols (:both, :none, :increase, :decrease), one per feature row.

batched_energy(model, X′::AbstractMatrix, target_idx::AbstractVector)

Returns a length-N vector of negative logits at the target class for each sample in X′. Uses CartesianIndex for GPU compatibility.

check_batched_convergence(probs, target_idx, iter, maxiter, threshold)

Returns a BitVector of length N indicating which samples have converged. Convergence is reached when the target-class probability ≥ threshold or iter ≥ maxiter.

find_neighbours(X, y, targets, y_levels; rng=Random.default_rng())

For each counterfactual with target targets[i], samples a random training point that has label targets[i]. Returns a D×N matrix (one neighbour per counterfactual column).

generate_counterfactuals!(
    model,
    X::AbstractMatrix,
    targets::Vector{Int},
    data::CounterfactualData,
    generator::NativeGenerator;
    maxiter = 30,
    decision_threshold = 0.75f0,
    decay = 0.9f0,
    reg_strength = 1.0f-3,
    epsilon = 0.3f0,
    p = Inf,
)

Generates counterfactual explanations for a batch of N factuals in a fully batched (GPU-compatible) fashion.

Arguments

• model: A Flux model (or any callable that accepts a D×N matrix and returns a C×N matrix of logits).
• X: D×N matrix of factuals.
• targets: Length-N vector of target class indices (1-based integers).
• data: A CounterfactualData object providing domain bounds and mutability.
• generator: A NativeGenerator.

Keyword arguments

• maxiter: Maximum number of search iterations.
• decision_threshold: Target probability threshold for convergence.
• decay: Decay rate for the polynomial decay schedule.
• reg_strength: Regularization strength for the energy penalty.
• epsilon: Norm bound for tracking valid adversarial examples.
• p: Norm order for the adversarial example bound (default Inf).

Returns

• counterfactuals::AbstractMatrix: The final counterfactuals (D×N).
• last_valid_ae::AbstractMatrix: Last valid adversarial examples (D×N).
• converged_mask::BitVector: Per-sample convergence flag.
• maxiter::Int: The maximum number of iterations used.

generate_native!(
    model, train_set, generator::NativeGenerator;
    nsamples=nothing, nneighbours=1, domain=nothing, mutability=nothing,
    maxiter=30, decision_threshold=0.75f0, decay=0.9f0,
    reg_strength=1.0f-3, epsilon=0.3f0, p=Inf, verbose=1,
)

Top-level counterfactual generation for the native branch. Generates counterfactuals for a subset of the training data, finds neighbours, applies mutability protection, and partitions results into a data loader aligned with train_set batches.

Returns (dl, percent_valid, nothing) — same interface as the old generate!().

generator_loss(gen, model, X′, X, targets_onehot, target_idx, iter,
               reg_strength, decay, maxiter)

Batched version of the ECCo objective. Operates on D×N matrices.

protect_immutable!(neighbours, counterfactuals, mutability)

Protects immutable features by setting neighbour values according to mutability directions. For each feature row:

• :both → keep neighbour value
• :none → use counterfactual value (no change)
• :increase → max(counterfactual, neighbour)
• :decrease → min(counterfactual, neighbour)

split_obs(indices, n)

Split indices into n roughly equal groups. Returns a vector of vectors.

track_adversarial_examples!(last_valid_ae, X, X′, epsilon, p)

Updates last_valid_ae in-place: for samples whose perturbation norm (in p-norm) is ≤ epsilon, the current counterfactual is stored.

counterfactual_training(
    loss::AbstractObjective,
    model,
    generator::NativeGenerator,
    train_set,
    opt_state;
    device = identity,
    val_set = nothing,
    nepochs = 100,
    burnin = 0.0f0,
    nce = nothing,
    nneighbours = 100,
    domain = nothing,
    mutability = nothing,
    maxiter = 30,
    decision_threshold = 0.75f0,
    decay = 0.9f0,
    reg_strength = 1.0f-3,
    epsilon = 0.3f0,
    p = Inf,
    verbose = 1,
    checkpoint_dir = nothing,
    callback = nothing,
)

Native GPU-compatible counterfactual training. Dispatches here when the generator is a NativeGenerator.

The device keyword is a function: identity (CPU), Flux.gpu (CUDA), or AMDGPU.gpu (AMDGPU). The model is moved to the device; training data should already be on the device (user moves it before constructing the DataLoader).