Tutorial: Counterfactual explanations for scorecard with binary target

Counterfactual explanations is one of the post-hoc methods used to provide explainability to machine learning models. In this tutorial, we show how to generate optimal counterfactual explanations for scorecard models.

[1]:

import numpy as np
import pandas as pd

from sklearn.linear_model import LogisticRegression

from optbinning import BinningProcess
from optbinning import Scorecard
from optbinning.scorecard import Counterfactual

We load the adult income dataset from the UCI repository (https://archive.ics.uci.edu/ml/datasets/adult). For this example, we select 8 features. The target “income” is transformed to binary (0: low-income, <=50K) and (1: high-income, >50K).

[2]:

df = pd.read_csv("data/adult.data", sep=",", header=None)

columns = ["age", "workclass", "fnlwgt", "education", "education-num",
           "marital-status", "occupation", "relationship", "race", "sex",
           "capital-gain", "capital-loss", "hours-per-week","native-country",
           "income"]

target = "income"

variable_names = ["age", "workclass", "education", "marital-status",
                  "occupation", "race", "sex", "hours-per-week"]

df.columns = columns
X = df[variable_names]
y = (df[target].values == ' >50K').astype(int)

Scorecard model

First, we require a scorecard model. As shown in previous tutorials, we need a binning process and an estimator.

[3]:

binning_process = BinningProcess(variable_names)

estimator = LogisticRegression(solver="lbfgs", class_weight="balanced")

scorecard = Scorecard(binning_process=binning_process,
                      estimator=estimator, scaling_method="min_max",
                      scaling_method_params={"min": 300, "max": 850})

scorecard.fit(X, y)

[3]:

Scorecard(binning_process=BinningProcess(variable_names=['age', 'workclass',
                                                         'education',
                                                         'marital-status',
                                                         'occupation', 'race',
                                                         'sex',
                                                         'hours-per-week']),
          estimator=LogisticRegression(class_weight='balanced'),
          scaling_method='min_max',
          scaling_method_params={'max': 850, 'min': 300})

In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook.
On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.

Scorecard

iFitted

Parameters

	binning_process	BinningProces...rs-per-week'])
	estimator	LogisticRegre...ht='balanced')
	scaling_method	'min_max'
	scaling_method_params	{'max': 850, 'min': 300}
	intercept_based	False
	reverse_scorecard	False
	rounding	False
	verbose	False

Fitted attributes

Name	Type	Value
binning_process_	BinningProcess	BinningProces...rs-per-week'])
estimator_	LogisticRegression	LogisticRegre...ht='balanced')
intercept_	int	0

binning_process: BinningProcess

BinningProcess(variable_names=['age', 'workclass', 'education',
                               'marital-status', 'occupation', 'race', 'sex',
                               'hours-per-week'])

BinningProcess

Parameters

	variable_names	['age', 'workclass', ...]
	max_n_prebins	20
	min_prebin_size	0.05
	min_n_bins	None
	max_n_bins	None
	min_bin_size	None
	max_bin_size	None
	max_pvalue	None
	max_pvalue_policy	'consecutive'
	selection_criteria	None
	fixed_variables	None
	categorical_variables	None
	special_codes	None
	split_digits	None
	binning_fit_params	None
	binning_transform_params	None
	n_jobs	None
	verbose	False

estimator: LogisticRegression

LogisticRegression(class_weight='balanced')

LogisticRegression

?Documentation for LogisticRegression

Parameters

	class_weight class_weight: dict or 'balanced', default=None Weights associated with classes in the form ``{class_label: weight}``. If not given, all classes are supposed to have weight one. The "balanced" mode uses the values of y to automatically adjust weights inversely proportional to class frequencies in the input data as ``n_samples / (n_classes * np.bincount(y))``. Note that these weights will be multiplied with sample_weight (passed through the fit method) if sample_weight is specified. .. versionadded:: 0.17 class_weight='balanced'	'balanced'
	penalty penalty: {'l1', 'l2', 'elasticnet', None}, default='l2' Specify the norm of the penalty: - `None`: no penalty is added; - `'l2'`: add an L2 penalty term and it is the default choice; - `'l1'`: add an L1 penalty term; - `'elasticnet'`: both L1 and L2 penalty terms are added. .. warning:: Some penalties may not work with some solvers. See the parameter `solver` below, to know the compatibility between the penalty and solver. .. versionadded:: 0.19 l1 penalty with SAGA solver (allowing 'multinomial' + L1) .. deprecated:: 1.8 `penalty` was deprecated in version 1.8 and will be removed in 1.10. Use `l1_ratio` and `C` instead. `l1_ratio=0` for `penalty='l2'`, `l1_ratio=1` for `penalty='l1'`, `l1_ratio` set to any float between 0 and 1 for `penalty='elasticnet'`, and `C=np.inf` for `penalty=None`.	'deprecated'
	C C: float, default=1.0 Inverse of regularization strength; must be a positive float. Like in support vector machines, smaller values specify stronger regularization. `C=np.inf` results in unpenalized logistic regression. For a visual example on the effect of tuning the `C` parameter with an L1 penalty, see: :ref:`sphx_glr_auto_examples_linear_model_plot_logistic_path.py`.	1.0
	l1_ratio l1_ratio: float, default=0.0 The Elastic-Net mixing parameter, with `0 <= l1_ratio <= 1`. Setting `l1_ratio=1` gives a pure L1-penalty, setting `l1_ratio=0` a pure L2-penalty. Any value between 0 and 1 gives an Elastic-Net penalty of the form `l1_ratio * L1 + (1 - l1_ratio) * L2`. .. warning:: Certain values of `l1_ratio`, i.e. some penalties, may not work with some solvers. See the parameter `solver` below, to know the compatibility between the penalty and solver. .. versionchanged:: 1.8 Default value changed from None to 0.0. .. deprecated:: 1.8 `None` is deprecated and will be removed in version 1.10. Always use `l1_ratio` to specify the penalty type.	0.0
	dual dual: bool, default=False Dual (constrained) or primal (regularized, see also :ref:`this equation <regularized-logistic-loss>`) formulation. Dual formulation is only implemented for l2 penalty with liblinear solver. Prefer `dual=False` when n_samples > n_features.	False
	tol tol: float, default=1e-4 Tolerance for stopping criteria.	0.0001
	fit_intercept fit_intercept: bool, default=True Specifies if a constant (a.k.a. bias or intercept) should be added to the decision function.	True
	intercept_scaling intercept_scaling: float, default=1 Useful only when the solver `liblinear` is used and `self.fit_intercept` is set to `True`. In this case, `x` becomes `[x, self.intercept_scaling]`, i.e. a "synthetic" feature with constant value equal to `intercept_scaling` is appended to the instance vector. The intercept becomes ``intercept_scaling * synthetic_feature_weight``. .. note:: The synthetic feature weight is subject to L1 or L2 regularization as all other features. To lessen the effect of regularization on synthetic feature weight (and therefore on the intercept) `intercept_scaling` has to be increased.	1
	random_state random_state: int, RandomState instance, default=None Only used for `solver` == 'sag', 'saga' or 'liblinear' to shuffle the data. It has no effect on the other solvers. See :term:`Glossary <random_state>` for details.	None
	solver solver: {'lbfgs', 'liblinear', 'newton-cg', 'newton-cholesky', 'sag', 'saga'}, default='lbfgs' Algorithm to use in the optimization problem. Default is 'lbfgs'. To choose a solver, you might want to consider the following aspects: - 'lbfgs' is a good default solver because it works reasonably well for a wide class of problems. - For :term:`multiclass` problems (`n_classes >= 3`), all solvers except 'liblinear' minimize the full multinomial loss, 'liblinear' will raise an error. - 'newton-cholesky' is a good choice for `n_samples` >> `n_features * n_classes`, especially with one-hot encoded categorical features with rare categories. Be aware that the memory usage of this solver has a quadratic dependency on `n_features * n_classes` because it explicitly computes the full Hessian matrix. - For small datasets, 'liblinear' is a good choice, whereas 'sag' and 'saga' are faster for large ones; - 'liblinear' can only handle binary classification by default. To apply a one-versus-rest scheme for the multiclass setting one can wrap it with the :class:`~sklearn.multiclass.OneVsRestClassifier`. .. warning:: The choice of the algorithm depends on the penalty chosen (`l1_ratio=0` for L2-penalty, `l1_ratio=1` for L1-penalty and `0 < l1_ratio < 1` for Elastic-Net) and on (multinomial) multiclass support: ================= ======================== ====================== solver l1_ratio multinomial multiclass ================= ======================== ====================== 'lbfgs' l1_ratio=0 yes 'liblinear' l1_ratio=1 or l1_ratio=0 no 'newton-cg' l1_ratio=0 yes 'newton-cholesky' l1_ratio=0 yes 'sag' l1_ratio=0 yes 'saga' 0<=l1_ratio<=1 yes ================= ======================== ====================== .. note:: 'sag' and 'saga' fast convergence is only guaranteed on features with approximately the same scale. You can preprocess the data with a scaler from :mod:`sklearn.preprocessing`. .. seealso:: Refer to the :ref:`User Guide <Logistic_regression>` for more information regarding :class:`LogisticRegression` and more specifically the :ref:`Table <logistic_regression_solvers>` summarizing solver/penalty supports. .. versionadded:: 0.17 Stochastic Average Gradient (SAG) descent solver. Multinomial support in version 0.18. .. versionadded:: 0.19 SAGA solver. .. versionchanged:: 0.22 The default solver changed from 'liblinear' to 'lbfgs' in 0.22. .. versionadded:: 1.2 newton-cholesky solver. Multinomial support in version 1.6.	'lbfgs'
	max_iter max_iter: int, default=100 Maximum number of iterations taken for the solvers to converge.	100
	verbose verbose: int, default=0 For the liblinear and lbfgs solvers set verbose to any positive number for verbosity.	0
	warm_start warm_start: bool, default=False When set to True, reuse the solution of the previous call to fit as initialization, otherwise, just erase the previous solution. Useless for liblinear solver. See :term:`the Glossary <warm_start>`. .. versionadded:: 0.17 warm_start to support lbfgs, newton-cg, sag, saga solvers.	False
	n_jobs n_jobs: int, default=None Does not have any effect. .. deprecated:: 1.8 `n_jobs` is deprecated in version 1.8 and will be removed in 1.10.	None

Generating counterfactual explanations - binary outcome

Having fitted the scorecard model, we can start generating counterfactual explanations.

Single counterfactual

As an input data point or query, we choose the sample with the lowest probability of having a high income.

[4]:

idx_lowest = np.argmin(scorecard.predict_proba(df)[:, 1])
query = X.iloc[idx_lowest, :].to_dict()

[5]:

query

[5]:

{'age': 17,
 'workclass': ' Private',
 'education': ' 11th',
 'marital-status': ' Never-married',
 'occupation': ' Other-service',
 'race': ' Black',
 'sex': ' Female',
 'hours-per-week': 25}

A counterfactual class can simply be instantiated with a scorecard model. The first step is to fit the counterfactual with the data used to develop the scorecard. This allows computing problem data required for the integer programming formulation. This method must be called once before generating counterfactual explanations.

[6]:

cf = Counterfactual(scorecard=scorecard)

[7]:

cf.fit(X)

[7]:

Counterfactual(scorecard=Scorecard(binning_process=BinningProcess(variable_names=['age',
                                                                                  'workclass',
                                                                                  'education',
                                                                                  'marital-status',
                                                                                  'occupation',
                                                                                  'race',
                                                                                  'sex',
                                                                                  'hours-per-week']),
                                   estimator=LogisticRegression(class_weight='balanced'),
                                   scaling_method='min_max',
                                   scaling_method_params={'max': 850,
                                                          'min': 300}))

In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook.
On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.

The minimum parameters required to generate counterfactuals are a query, the desired target outcome y, the outcome type, and the number of counterfactuals n_cf. Other parameters such as the maximum number of changes max_changes can be specified.

[8]:

cf.generate(query=query, y=1, outcome_type="binary", n_cf=1, max_changes=3)

[8]:

Counterfactual(scorecard=Scorecard(binning_process=BinningProcess(variable_names=['age',
                                                                                  'workclass',
                                                                                  'education',
                                                                                  'marital-status',
                                                                                  'occupation',
                                                                                  'race',
                                                                                  'sex',
                                                                                  'hours-per-week']),
                                   estimator=LogisticRegression(class_weight='balanced'),
                                   scaling_method='min_max',
                                   scaling_method_params={'max': 850,
                                                          'min': 300}))

In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook.
On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.

The property status retrieves the status of the optimization solver. Additional information is retrieved by using the information method, showing three sections:

Solver statistics: number of variables and constraints, and objective value.
Objectives: value of the objectives functions, by default proximity and closeness.
Timing: time statistics.

[9]:

cf.status

[9]:

'OPTIMAL'

[10]:

cf.information(print_level=2)

optbinning (Version 1.0.0)
Copyright (c) 2019-2026 Guillermo Navas-Palencia, Apache License 2.0

  Begin options
    scorecard                            yes   * U
    special_missing                    False   * d
    n_jobs                                 1   * d
    verbose                            False   * d
  End options

  Status  : OPTIMAL

  Solver statistics
    Type                                 mip
    Number of variables                   42
    Number of constraints                 95
    Objective value                  16.1504
    Best objective bound             16.1504

  Objectives
    proximity                         3.7572
    closeness                        12.3932

  Timing
    Total time                          0.34 sec
    Fit                                 0.24 sec   ( 70.70%)
    Solver                              0.09 sec   ( 27.17%)
    Post-processing                     0.01 sec   (  7.86%)

The resulting optimal counterfactual explanation can be shown using display method. By default, all feature values are displayed. We might prefer to only observe the changes from the query, then set parameter show_only_changes to True. In addition, to add the counterfactual outcome, set parameter show_outcome to True.

[11]:

cf.display()

[11]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week
0	[33.50, 35.50)	Private	[ Masters, Prof-school, Doctorate]	[ Married-AF-spouse, Married-civ-spouse]	Other-service	Black	Female	25

[12]:

cf.display(show_only_changes=True)

[12]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week
0	[33.50, 35.50)	-	[ Masters, Prof-school, Doctorate]	[ Married-AF-spouse, Married-civ-spouse]	-	-	-	-

[13]:

cf.display(show_only_changes=True, show_outcome=True)

[13]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week	outcome
0	[33.50, 35.50)	-	[ Masters, Prof-school, Doctorate]	[ Married-AF-spouse, Married-civ-spouse]	-	-	-	-	0.505201

Actionable features

Note that, in general, a scorecard includes features that are not mutable or that should not be actionable. For example, we might exclude marital status by choosing only those actionable features using the parameter actionable_features.

[14]:

cf.generate(query=query, y=1, outcome_type="binary", n_cf=1, max_changes=4,
            actionable_features=["age", "workclass", "education", "occupation",
                                 "hours-per-week"]
           ).display(show_only_changes=True, show_outcome=True)

[14]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week	outcome
0	[43.50, 49.50)	-	[ Masters, Prof-school, Doctorate]	-	[ Tech-support, Protective-serv, Prof-specia...	-	-	[39.50, 41.50)	0.502521

Weighted vs hierarchical method

Currently, there are two methods (weighted and hierarchical) supported to handle multiple objectives functions. By default, method is set to “weighted”, due to having an inferior computational cost.

[15]:

cf.generate(query=query, y=1, outcome_type="binary", n_cf=1,
            method="weighted", max_changes=4).display()

[15]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week
0	[37.50, 40.50)	Private	[ Bachelors]	[ Married-AF-spouse, Married-civ-spouse]	[ ?, Armed-Forces, Farming-fishing]	Black	Female	25

[16]:

cf.information()

optbinning (Version 1.0.0)
Copyright (c) 2019-2026 Guillermo Navas-Palencia, Apache License 2.0

  Status  : OPTIMAL

  Solver statistics
    Type                                 mip
    Number of variables                   42
    Number of constraints                 95
    Objective value                  14.0048
    Best objective bound             14.0048

  Objectives
    proximity                         4.1658
    closeness                         9.8391

  Timing
    Total time                          0.77 sec
    Fit                                 0.24 sec   ( 31.31%)
    Solver                              0.51 sec   ( 66.05%)
    Post-processing                     0.02 sec   (  4.00%)

When generating counterfactuals the objectives are passed as a dictionary. If method="weighted", the dictionary values represent the assigned weight to each objective, whereas if method="hierarchical", the dictionary values represent the priority of each objective. In the following example, we assign a higher weight to closeness, reducing the objective value compared to the previous one, where both weights are set to 1.

[17]:

cf.generate(query=query, y=1, outcome_type="binary", n_cf=1,
            method="weighted", objectives={"proximity": 0.1, "closeness": 0.9},
            max_changes=4
           ).display()

[17]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week
0	[43.50, 49.50)	Private	[ Masters, Prof-school, Doctorate]	Never-married	[ Tech-support, Protective-serv, Prof-specia...	Black	Female	[39.50, 41.50)

[18]:

cf.information()

optbinning (Version 1.0.0)
Copyright (c) 2019-2026 Guillermo Navas-Palencia, Apache License 2.0

  Status  : OPTIMAL

  Solver statistics
    Type                                 mip
    Number of variables                   42
    Number of constraints                 95
    Objective value                   9.0396
    Best objective bound              9.0396

  Objectives
    proximity                         5.5887
    closeness                         9.4231

  Timing
    Total time                          0.75 sec
    Fit                                 0.24 sec   ( 32.03%)
    Solver                              0.50 sec   ( 66.49%)
    Post-processing                     0.01 sec   (  2.23%)

Considering the hierarchical method, the highest priority is assigned to proximity, therefore, we get the minimum objective value with a small degradation ("priority_tol"=0.1).

[19]:

cf.generate(query=query, y=1, outcome_type="binary", n_cf=1,
            method="hierarchical", max_changes=4
           ).display()

[19]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week
0	[35.50, 37.50)	Private	[ Masters, Prof-school, Doctorate]	[ Married-AF-spouse, Married-civ-spouse]	Other-service	Black	Female	[25.50, 34.50)

[20]:

cf.information()

optbinning (Version 1.0.0)
Copyright (c) 2019-2026 Guillermo Navas-Palencia, Apache License 2.0

  Status  : OPTIMAL

  Solver statistics
    Type                                 mip
    Number of variables                   44
    Number of constraints                 97
    Objective value                  12.0849
    Best objective bound             12.0849

  Objectives
    proximity                         3.9661
    closeness                        12.0849

  Timing
    Total time                          0.46 sec
    Fit                                 0.24 sec   ( 51.90%)
    Solver                              0.21 sec   ( 45.52%)
    Post-processing                     0.01 sec   (  5.66%)

On the contrary, if we switch priorities and reduce the priority degradation, we obtain the same closeness objective value as the one generated with the weight "closeness": 0.9.

[21]:

cf.generate(query=query, y=1, outcome_type="binary", n_cf=1,
            method="hierarchical", objectives={"proximity": 1, "closeness": 2},
            priority_tol=0.001,
            max_changes=4
           ).display()

[21]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week
0	[43.50, 49.50)	Private	[ Masters, Prof-school, Doctorate]	Never-married	[ Tech-support, Protective-serv, Prof-specia...	Black	Female	[39.50, 41.50)

[22]:

cf.information()

optbinning (Version 1.0.0)
Copyright (c) 2019-2026 Guillermo Navas-Palencia, Apache License 2.0

  Status  : OPTIMAL

  Solver statistics
    Type                                 mip
    Number of variables                   44
    Number of constraints                 97
    Objective value                   5.5887
    Best objective bound              5.5887

  Objectives
    closeness                         9.4231
    proximity                         5.5887

  Timing
    Total time                          2.49 sec
    Fit                                 0.24 sec   (  9.64%)
    Solver                              2.24 sec   ( 90.12%)
    Post-processing                     0.01 sec   (  0.26%)

The hierarchical method becomes more interesting when several objectives come into play, as shown going forward.

Multiple counterfactuals

Now, let’s focus on the generation of multiple counterfactual explanations for a single input data point. The present implementation is able to generate n_cf counterfactuals simultaneously while imposing diversity constraints.

For example, we generate three counterfactuals such that a maximum of four features can be changed and enforcing (hard constraint) a diversity of features. The diversity of features to change guarantees different combinations of changed features for each counterfactual.

[23]:

cf.generate(query=query, y=1, outcome_type="binary", n_cf=3, max_changes=4,
            hard_constraints=["diversity_features"], time_limit=10
           ).display(show_only_changes=True, show_outcome=True)

[23]:

age	workclass	education	marital-status	occupation	race	sex	hours-per-week	outcome
[40.50, 43.50)	-	[ Masters, Prof-school, Doctorate]	-	[ Exec-managerial]	-	-	[55.50, inf)	0.633269
[49.50, 54.50)	-	[ Masters, Prof-school, Doctorate]	[ Married-AF-spouse, Married-civ-spouse]	-	-	-	[55.50, inf)	0.845609
[49.50, 54.50)	-	-	[ Married-AF-spouse, Married-civ-spouse]	[ Exec-managerial]	-	-	[55.50, inf)	0.591394

The generated counterfactuals change the following features:

age | education | occupation | hours-per-week
age | education | marital-status | hours-per-week
age | education | marital-status | occupation

[24]:

cf.information()

optbinning (Version 1.0.0)
Copyright (c) 2019-2026 Guillermo Navas-Palencia, Apache License 2.0

  Status  : FEASIBLE

  Solver statistics
    Type                                 mip
    Number of variables                 1041
    Number of constraints                450
    Objective value                  54.9108
    Best objective bound             40.3651

  Objectives
    proximity                        18.4831
    closeness                        36.4277

  Timing
    Total time                         10.62 sec
    Fit                                 0.24 sec   (  2.26%)
    Solver                             10.35 sec   ( 97.47%)
    Post-processing                     0.03 sec   (  0.28%)

The reported status is only feasible, not optimal. When generating multiple counterfactual adding several constraints, the time required to prove optimality might be in the order of 10 - 120s, so one needs to increase time_limit. However, good feasible solutions are generally achieved within a few seconds. Adding extra 10 seconds to time_limit, the proximity and closeness objective values are reduced by 0.4% and 0.8%, respectively.

[25]:

cf.generate(query=query, y=1, outcome_type="binary", n_cf=3, max_changes=4,
            hard_constraints=["diversity_features"], time_limit=20
           ).display(show_only_changes=True, show_outcome=True)

[25]:

age	workclass	education	marital-status	occupation	race	sex	hours-per-week	outcome
[40.50, 43.50)	-	[ Bachelors]	[ Married-AF-spouse, Married-civ-spouse]	-	-	-	[34.50, 39.50)	0.536857
[43.50, 49.50)	-	[ Masters, Prof-school, Doctorate]	-	[ Tech-support, Protective-serv, Prof-specia...	-	-	[39.50, 41.50)	0.502521
[37.50, 40.50)	-	[ Bachelors]	[ Married-AF-spouse, Married-civ-spouse]	[ ?, Armed-Forces, Farming-fishing]	-	-	-	0.507865

[26]:

cf.information()

optbinning (Version 1.0.0)
Copyright (c) 2019-2026 Guillermo Navas-Palencia, Apache License 2.0

  Status  : FEASIBLE

  Solver statistics
    Type                                 mip
    Number of variables                 1041
    Number of constraints                450
    Objective value                  43.7095
    Best objective bound             40.3651

  Objectives
    proximity                        14.0732
    closeness                        29.6363

  Timing
    Total time                         20.40 sec
    Fit                                 0.24 sec   (  1.18%)
    Solver                             20.14 sec   ( 98.71%)
    Post-processing                     0.02 sec   (  0.12%)

The previous conterfactuals, although showing diversity regarding features to change, some feature values appear several times. To guarantee unique combinations of feature changes and feature values, we add the hard constraint “diversity_values”.

[28]:

cf.generate(query=query, y=1, outcome_type="binary", n_cf=3, max_changes=4,
            hard_constraints=["diversity_features", "diversity_values"], time_limit=30
           ).display(show_only_changes=True, show_outcome=True)

[28]:

age	workclass	education	marital-status	occupation	race	sex	hours-per-week	outcome
[40.50, 43.50)	-	[ Assoc-acdm, Assoc-voc]	[ Married-AF-spouse, Married-civ-spouse]	-	-	-	[41.50, 49.50)	0.528592
[49.50, 54.50)	-	[ Masters, Prof-school, Doctorate]	[ Married-spouse-absent, Widowed, Divorced]	[ Tech-support, Protective-serv, Prof-specia...	-	-	-	0.509401
[43.50, 49.50)	-	[ Bachelors]	-	[ Exec-managerial]	-	-	[49.50, 55.50)	0.517386

[29]:

cf.information()

optbinning (Version 1.0.0)
Copyright (c) 2019-2026 Guillermo Navas-Palencia, Apache License 2.0

  Status  : OPTIMAL

  Solver statistics
    Type                                 mip
    Number of variables                 1065
    Number of constraints                450
    Objective value                  47.7114
    Best objective bound             47.7114

  Objectives
    proximity                        16.0561
    closeness                        31.6553

  Timing
    Total time                         26.16 sec
    Fit                                 0.24 sec   (  0.92%)
    Solver                             25.89 sec   ( 99.00%)
    Post-processing                     0.02 sec   (  0.09%)

Adding this extra constraint, the objective values slightly increase.

Generating counterfactual explanations - probability outcome

In some situations, having an outcome = 1 with a probability outcome > 0.5 might not be sufficient. For example, an algorithm might require a probability of 0.7 for acceptance.

[30]:

df_query = pd.DataFrame([query],columns=query.keys())

[31]:

scorecard.predict_proba(df_query)

[31]:

array([[9.99831847e-01, 1.68152834e-04]])

Initially, the probability of the query is close to 0. When outcome_type="probability", at least an additional constraint must be provided. The supported constraints are:

soft constraints: “diff_outcome”.
hard constraints: “min_outcome” and “max_outcome”.

In this first try, we aim to obtain a counterfactual with an outcome probability as close as possible to 0.7. The weighted approach is used, assigning unit weights to all objectives.

[32]:

cf.generate(query=df_query, y=0.7, outcome_type="probability", n_cf=2, max_changes=4,
            hard_constraints=["diversity_features"],
            soft_constraints={"diff_outcome": 1},
            ).display(show_only_changes=True, show_outcome=True)

[32]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week	outcome
0	[23.50, 25.50)	-	[ HS-grad]	-	[ ?, Armed-Forces, Farming-fishing]	[ Other, Amer-Indian-Eskimo, Black]	-	-	0.007156
0	[23.50, 25.50)	-	[ HS-grad]	-	[ ?, Armed-Forces, Farming-fishing]	-	-	-	0.007156

A weight=1 is not large enough given the rest of the objective values. A workaround might be to increase the corresponding weight.

[33]:

cf.generate(query=df_query, y=0.7, outcome_type="probability", n_cf=2, max_changes=4,
            hard_constraints=["diversity_features"],
            soft_constraints={"diff_outcome": 100}
           ).display(show_only_changes=True, show_outcome=True)

[33]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week	outcome
0	[43.50, 49.50)	-	[ Masters, Prof-school, Doctorate]	[ Married-AF-spouse, Married-civ-spouse]	[ ?, Armed-Forces, Farming-fishing]	-	-	-	0.701769
0	[40.50, 43.50)	-	[ Masters, Prof-school, Doctorate]	[ Married-AF-spouse, Married-civ-spouse]	-	-	-	[34.50, 39.50)	0.696745

[34]:

cf.information()

optbinning (Version 1.0.0)
Copyright (c) 2019-2026 Guillermo Navas-Palencia, Apache License 2.0

  Status  : OPTIMAL

  Solver statistics
    Type                                 mip
    Number of variables                  521
    Number of constraints                311
    Objective value                  32.6064
    Best objective bound             32.6064

  Objectives
    proximity                         9.1411
    closeness                        22.6536
    diff_outcome                      0.0081

  Timing
    Total time                          4.10 sec
    Fit                                 0.24 sec   (  5.85%)
    Solver                              3.83 sec   ( 93.31%)
    Post-processing                     0.03 sec   (  0.90%)

We might, however, want to guarantee a minimum probability outcome of 0.7. To do so, we add the hard constraint “min_outcome”.

[35]:

cf.generate(query=df_query, y=0.7, outcome_type="probability", n_cf=2, max_changes=4,
            hard_constraints=["diversity_features", "min_outcome"]
           ).display(show_only_changes=True, show_outcome=True)

[35]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week	outcome
0	[49.50, 54.50)	-	[ Masters, Prof-school, Doctorate]	[ Married-AF-spouse, Married-civ-spouse]	[ ?, Armed-Forces, Farming-fishing]	-	-	-	0.714410
0	[49.50, 54.50)	-	[ Masters, Prof-school, Doctorate]	[ Married-AF-spouse, Married-civ-spouse]	-	-	-	[34.50, 39.50)	0.732671

[36]:

cf.information()

optbinning (Version 1.0.0)
Copyright (c) 2019-2026 Guillermo Navas-Palencia, Apache License 2.0

  Status  : OPTIMAL

  Solver statistics
    Type                                 mip
    Number of variables                  521
    Number of constraints                311
    Objective value                  31.7704
    Best objective bound             31.7704

  Objectives
    proximity                         9.2375
    closeness                        22.5330

  Timing
    Total time                          2.24 sec
    Fit                                 0.24 sec   ( 10.73%)
    Solver                              1.98 sec   ( 88.68%)
    Post-processing                     0.01 sec   (  0.66%)

Moreover, it is possible to combine the previous constraints with diversity constraints.

[37]:

cf.generate(query=df_query, y=0.7, outcome_type="probability", n_cf=2,
            max_changes=4, method="hierarchical",
            objectives={"proximity": 2, "closeness": 1},
            hard_constraints=["min_outcome"],
            soft_constraints={"diversity_features": 2, "diversity_values": 1}
           ).display(show_only_changes=True, show_outcome=True)

[37]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week	outcome
0	[43.50, 49.50)	-	[ Masters, Prof-school, Doctorate]	[ Married-AF-spouse, Married-civ-spouse]	[ Adm-clerical]	-	-	-	0.727434
0	[49.50, 54.50)	-	[ Bachelors]	[ Married-AF-spouse, Married-civ-spouse]	-	-	-	[41.50, 49.50)	0.706417

[38]:

cf.information()

optbinning (Version 1.0.0)
Copyright (c) 2019-2026 Guillermo Navas-Palencia, Apache License 2.0

  Status  : OPTIMAL

  Solver statistics
    Type                                 mip
    Number of variables                  526
    Number of constraints                317
    Objective value                  -6.0000
    Best objective bound             -6.0000

  Objectives
    proximity                         9.8458
    diversity_features                2.0000
    closeness                        22.6946
    diversity_values                  6.0000

  Timing
    Total time                          4.14 sec
    Fit                                 0.24 sec   (  5.81%)
    Solver                              3.88 sec   ( 93.79%)
    Post-processing                     0.02 sec   (  0.44%)

Special and missing bins

The scorecard models might have bins for special and missing values. The parameter special_missing permits including these bins as feasible solutions for the generation of counterfactual explanations.

[39]:

cf = Counterfactual(scorecard=scorecard, special_missing=True)

[40]:

cf.fit(X)

[40]:

Counterfactual(scorecard=Scorecard(binning_process=BinningProcess(variable_names=['age',
                                                                                  'workclass',
                                                                                  'education',
                                                                                  'marital-status',
                                                                                  'occupation',
                                                                                  'race',
                                                                                  'sex',
                                                                                  'hours-per-week']),
                                   estimator=LogisticRegression(class_weight='balanced'),
                                   scaling_method='min_max',
                                   scaling_method_params={'max': 850,
                                                          'min': 300}),
               special_missing=True)

In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook.
On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.

[41]:

cf.generate(query=query, y=1, outcome_type="binary", n_cf=1, max_changes=4
           ).display(show_only_changes=True)

[41]:

	age	workclass	education	marital-status	occupation	race	sex	hours-per-week
0	[49.50, 54.50)	-	[ Assoc-acdm, Assoc-voc]	[ Married-AF-spouse, Married-civ-spouse]	-	-	-	Special