CONFETTI Explainer

class confetti.explainer.explainer.CONFETTI(model_path: Path | str)

Bases: object

CONFETTI explainer.

CONFETTI generates counterfactual explanations for multivariate time series by combining a nearest-unlike-neighbour search, a naive subsequence replacement stage, and a multi-objective optimization stage. It supports confidence-based constraints, sparsity control, and optional proximity minimization.

generate_counterfactuals(instances_to_explain: ndarray, reference_data: ndarray, reference_weights: ndarray | None = None, alpha: float = 0.5, theta: float = 0.51, n_partitions: int = 3, population_size: int = 100, maximum_number_of_generations: int = 100, crossover_probability: float = 1.0, mutation_probability: float = 0.9, optimize_confidence: bool = True, optimize_sparsity: bool = True, optimize_proximity: bool = True, proximity_distance: str = 'euclidean', dtw_window: int | None = None, processes: int | None = None, save_counterfactuals: bool = False, output_path: str | Path | None = None, verbose: bool = False) → None | CounterfactualResults

Generate counterfactual explanations for multiple instances.

Each instance is processed independently using the CONFETTI pipeline. When processes > 1, parallelization is used; otherwise the generation proceeds sequentially.

Parameters:

  • instances_to_explain (ndarray of shape (n_instances, timesteps, channels)) – Instances for which counterfactuals will be generated.

  • reference_data (ndarray of shape (n_reference, timesteps, channels)) – Reference dataset used to identify nearest unlike neighbours (NUNs).

  • reference_weights (ndarray or None, default=None) – Feature-importance weights used in the naive stage. If None, the naive stage is skipped.

  • alpha (float, default=0.5) – Trade-off parameter between confidence and sparsity when selecting the best counterfactual.

  • theta (float, default=0.51) – Minimum predicted probability required for a counterfactual to be considered valid.

  • n_partitions (int, default=3) – Number of partitions used to construct the reference directions for the NSGA-III algorithm. Larger values create a denser set of directions and may increase search resolution at the cost of runtime.

  • population_size (int, default=100) – Number of individuals in the evolutionary population. Higher values improve the search space exploration but increase computation time.

  • maximum_number_of_generations (int, default=100) – Maximum number of evolutionary generations. Increasing this allows the genetic algorithm to converge more thoroughly at the expense of longer runtimes.

  • crossover_probability (float, default=1.0) – Probability of applying crossover during reproduction. A value of 1.0 means crossover is always applied.

  • mutation_probability (float, default=0.9) – Probability of flipping each bit in the binary mask used to select perturbed time steps.

  • optimize_confidence (bool, default=True) – Whether to include confidence maximization as an optimization objective.

  • optimize_sparsity (bool, default=True) – Whether to include sparsity minimization as an optimization objective.

  • optimize_proximity (bool, default=True) – Whether to include proximity minimization as an optimization objective.

  • proximity_distance (str, default="euclidean") – Distance metric for proximity. Supported metrics include Euclidean and several tslearn-based time-series distances.

  • dtw_window (int or None, default=None) – Sakoe–Chiba radius for DTW proximity. If None, no warping constraint is applied.

  • processes (int or None, default=None) – Number of worker processes for parallel execution. If None, counterfactuals are generated sequentially.

  • save_counterfactuals (bool, default=False) – Whether to save all generated counterfactuals to CSV files.

  • output_path (str or Path or None, default=None) – Directory where CSV outputs should be written. If None, results are saved to the current working directory.

  • verbose (bool, default=False) – If True, print detailed progress messages during generation.

Returns:

counterfactual_results – All counterfactual sets produced for the batch.

Return type:

CounterfactualResults or None

Note

Distance metrics for proximity optimization are handled through the tslearn.metrics module when optimize_proximity=True.

CONFETTI supports several time-series distances beyond Euclidean, including Dynamic Time Warping (DTW), Soft-DTW, CTW, and GAK. These metrics are accessed internally via tslearn.metrics through functions such as cdist_dtw, cdist_ctw, cdist_soft_dtw and cdist_gak.

  • If a tslearn-based distance is selected (e.g., proximity_distance="dtw"), the proximity objective computes pairwise distances between each generated counterfactual and the original instance using the corresponding tslearn cost matrix.

  • DTW can optionally use a Sakoe–Chiba band via dtw_window for faster and more constrained alignment.

  • tslearn is only required when a non-Euclidean proximity metric is requested. If tslearn is not installed and such a metric is selected, CONFETTI raises a CONFETTIConfigurationError describing the missing dependency.

Euclidean proximity does not require tslearn and is always available.

property instances_to_explain: ndarray

Instances for which counterfactuals will be generated.

property model

Return the loaded classification model.

property model_path: str

Return the path to the trained model.

property original_labels: ndarray

Original labels of the instances to be explained.

property reference_data: ndarray

Reference dataset used for finding nearest unlike neighbours.

property reference_labels: ndarray

Reference labels corresponding to the reference dataset.

property weights: None | ndarray

Feature importance weights for the reference dataset.