Counterfactual Data Structures¶

class confetti.structs.counterfactual_structs.Counterfactual(counterfactual: ndarray, label: str | int | float)¶

Bases: object

Container for a single counterfactual instance and its predicted label.

Note

This class is a lightweight structure used internally by CounterfactualSet.

counterfactual: ndarray¶: The generated counterfactual time series.

label: str | int | float¶: The predicted label corresponding to the counterfactual.

class confetti.structs.counterfactual_structs.CounterfactualResults(counterfactual_sets: List[CounterfactualSet] | None = None)¶

Bases: object

Container for counterfactual results across multiple instances.

Parameters:: counterfactual_sets (list of CounterfactualSet or None, optional) – A list of CounterfactualSet objects, each corresponding to one explained instance. If None, the container is initialized empty.

Note

This class acts as a higher-level aggregator over multiple CounterfactualSet objects. It provides convenience methods for exporting structured results for all instances at once.

property counterfactual_sets: List[CounterfactualSet]¶

Return the list of stored counterfactual sets.

Returns:: The stored counterfactual sets.
Return type:: list of CounterfactualSet

to_csv(output_path: Path | str = PosixPath('counterfactuals.csv')) → None¶

Export all counterfactuals for all instances to a CSV file.

Parameters:: output_path (str or Path, default="./counterfactuals.csv") – Destination file path for the exported CSV.
Return type:: None

to_dataframe() → DataFrame¶

Return all counterfactuals across all instances as a DataFrame.

Returns:: A DataFrame containing all counterfactuals for all instances.
Return type:: pd.DataFrame

class confetti.structs.counterfactual_structs.CounterfactualSet(original_instance: ndarray, original_label: str | int | float | int64 | float64, nearest_unlike_neighbour: ndarray, best_solution: None | Counterfactual, all_counterfactuals: List[Counterfactual], feature_importance: ndarray | None = None)¶

Bases: object

Container for all counterfactual explanations generated for one instance.

Parameters:

original_instance (np.ndarray) – The original instance for which counterfactuals were generated.
original_label (str | int | float | np.int64 | np.float64) – The predicted label of the original instance.
nearest_unlike_neighbour (np.ndarray) – The nearest unlike neighbour (NUN) of the original instance.
best_solution (Counterfactual or None) – The best counterfactual solution identified by the method.
all_counterfactuals (list of Counterfactual) – All counterfactuals generated for this instance.
feature_importance (np.ndarray or None, optional) – Optional 1D array of feature-importance values (e.g., CAM weights) for the nearest unlike neighbour.

Note

This object stores all counterfactual candidates for a single instance, together with metadata such as the NUN and optional importance weights. It provides convenience methods for exporting structured results.

property all_counterfactuals: List[Counterfactual]¶

Return all generated counterfactuals.

Returns:: All counterfactual candidates generated for this instance.
Return type:: list of Counterfactual

property best: Counterfactual¶

Return the best counterfactual solution.

Returns:: The best counterfactual, selected according to the method’s optimization criteria.
Return type:: Counterfactual

property feature_importance: ndarray | None¶

Return the optional feature-importance vector.

Returns:: A 1D array of feature-importance weights, or None if not provided.
Return type:: np.ndarray or None

property nearest_unlike_neighbour: ndarray¶

Return the nearest unlike neighbour.

Returns:: The nearest unlike neighbour instance.
Return type:: np.ndarray

property original_instance: ndarray¶

Return the original instance.

Returns:: The original instance for which counterfactuals were generated.
Return type:: np.ndarray

property original_label: str | int | float | int64 | float64¶

Return the predicted label of the original instance.

Returns:: The predicted label.
Return type:: str | int | float | np.int64 | np.float64

to_csv(output_path: Path | str = PosixPath('counterfactuals_all_instances.csv')) → None¶

Export all counterfactuals to a CSV file.

Parameters:: output_path (str or Path, default="./counterfactuals_all_instances.csv") – Destination file path for the exported CSV.
Return type:: None

to_dataframe() → DataFrame¶

Return all counterfactuals as a pandas DataFrame.

Returns:: A DataFrame where each row corresponds to one counterfactual.
Return type:: pd.DataFrame