Counterfactual explanations

class optbinning.scorecard.Counterfactual(scorecard: Scorecard, special_missing: bool = False, n_jobs: int = 1, verbose: bool = False)

Bases: BaseCounterfactual

Optimal counterfactual explanations given a scorecard model.

Parameters:

  • scorecard (object) – A Scorecard instance.

  • special_missing (bool (default=False)) – Whether the special and missing bin are considered as valid counterfactual values.

  • n_jobs (int, optional (default=1)) – Number of cores to run the optimization solver.

  • verbose (bool (default=False)) – Enable verbose output.

display(show_only_changes: bool = False, show_outcome: bool = False) → DataFrame

Display the generatedcounterfactual explanations.

Parameters:

  • show_only_changes (boolean (default=False)) – Whether to show only changes on feature values.

  • show_outcome (boolean (default=False)) – Whether to add a column with the scorecard outcome. If outcome_type is “binary” or “probability”, the estimated probability of the counterfactual is added.

Returns:

counterfactuals – Counterfactual explanations.

Return type:

pandas.DataFrame

fit(X: DataFrame) → Self

Fit counterfactual. Compute problem data to generate counterfactual explanations.

Parameters:

X (pandas.DataFrame (n_samples, n_features)) – Training vector, where n_samples is the number of samples.

Returns:

self – Fitted counterfactual.

Return type:

Counterfactual

generate(query: dict | DataFrame, y: int | float, outcome_type: str, n_cf: int, method: str = 'weighted', objectives: dict | None = None, max_changes: int | None = None, actionable_features: list[str] | None = None, hard_constraints: list[str] | None = None, soft_constraints: dict[str, float] | None = None, priority_tol: float = 0.1, time_limit: int = 10) → Self

Generate counterfactual explanations given objectives and constraints.

Parameters:

  • query (dict or pandas.DataFrame) – Input data points for which a single or multiple counterfactual explanations are to be generated.

  • y (int or float) – Desired outcome.

  • outcome_type (str) – Desired outcome type. Supported outcome types are “binary”, “probability” and “continuous”.

  • n_cf (int) – Number of counterfactuals to be generated.

  • method (str (default="weighted")) – Multi-objective optimization method. Supported methods are “weighted” and “hierarchical”.

  • objectives (dict or None (default=None)) – Objectives with their corresponding weights or priorities, depending on the method.

  • max_changes (int or None (default=None)) – Maximum number of features to be changed. If None, the maximum number of changes is half of the number of features.

  • actionable_features (array-like or None (default=None)) – List of actionable features. If None. all features are suitable to be changed.

  • hard_constraints (array-like or None (default=None)) – Constraint to be enforced when solving the underlying optimization problem.

  • soft_constraints (dict or None (default=None)) – Constraints to be moved to the objective function as a penalization term.

  • priority_tol (float, optional (default=0.1)) – Relative tolerance when solving the multi-objective optimization problem with method="hierarchical".

  • time_limit (int (default=10)) – The maximum time in seconds to run the optimization solver.

Returns:

self – Generated counterfactuals.

Return type:

Counterfactual

get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routing – A MetadataRequest encapsulating routing information.

Return type:

MetadataRequest

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

params – Parameter names mapped to their values.

Return type:

dict

information(print_level: int = 1) → None

Print overview information about the options settings and statistics.

Parameters:

print_level (int (default=1)) – Level of details.

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**params (dict) – Estimator parameters.

Returns:

self – Estimator instance.

Return type:

estimator instance

property status: str

The status of the underlying optimization solver.

Returns:

status

Return type:

str