BiasResampler

class empulse.samplers.BiasResampler(*, strategy='statistical parity', transform_feature=None, random_state=None)

Sampler which resamples instances to remove bias against a subgroup.

Read more in the User Guide.

Parameters:

strategy{‘statistical parity’, ‘demographic parity’} or Callable, default=’statistical parity’

Determines how the group weights are computed. Group weights determine how much to over or undersample each combination of target and sensitive feature. For example, a weight of 2 for the pair (y_true == 1, sensitive_feature == 0) means that the resampled dataset should have twice as many instances with y_true == 1 and sensitive_feature == 0 compared to the original dataset.

• 'statistical_parity' or 'demographic parity': probability of positive predictions are equal between subgroups of sensitive feature.

• Callable: function which computes the group weights based on the target and sensitive feature. Callable accepts two arguments: y_true and sensitive_feature and returns the group weights. Group weights are a 2x2 matrix where the rows represent the target variable and the columns represent the sensitive feature. The element at position (i, j) is the weight for the pair (y_true == i, sensitive_feature == j).

transform_featureOptional[Callable], default=None

Function which transforms sensitive_feature before resampling the training data. The function takes in the sensitive feature in the form of a numpy.ndarray and outputs the transformed sensitive feature as a numpy.ndarray. This can be useful if you want to transform a continuous variable to a binary variable at fit time.

random_stateint or numpy.random.RandomState, optional

Random number generator seed for reproducibility.

Attributes:

sample_indices_numpy.ndarray

Indices of the samples that were selected.

References

[1]

Rahman, S., Janssens, B., & Bogaert, M. (2025). Profit-driven pre-processing in B2B customer churn modeling using fairness techniques. Journal of Business Research, 189, 115159. doi:10.1016/j.jbusres.2024.115159

Examples

import numpy as np
from empulse.samplers import BiasResampler
from sklearn.datasets import make_classification

X, y = make_classification()
high_clv = np.random.randint(0, 2, y.shape)

sampler = BiasResampler()
sampler.fit_resample(X, y, sensitive_feature=high_clv)

Example with passing high-clv indicator through cross-validation:

import numpy as np
from empulse.samplers import BiasResampler
from imblearn.pipeline import Pipeline
from sklearn import set_config
from sklearn.datasets import make_classification
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import cross_val_score

set_config(enable_metadata_routing=True)

X, y = make_classification()
high_clv = np.random.randint(0, 2, y.shape)

pipeline = Pipeline([
    ('sampler', BiasResampler().set_fit_resample_request(sensitive_feature=True)),
    ('model', LogisticRegression())
])

cross_val_score(pipeline, X, y, params={'sensitive_feature': high_clv})

Example with passing clv through a grid search and dynamically determining high_clv customer based on training data:

import numpy as np
from empulse.samplers import BiasResampler
from imblearn.pipeline import Pipeline
from sklearn import set_config
from sklearn.datasets import make_classification
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import GridSearchCV

set_config(enable_metadata_routing=True)

X, y = make_classification()
clv = np.random.rand(y.size)

def to_high_clv(clv: np.ndarray) -> np.ndarray:
    return (clv > np.median(clv)).astype(np.int8)

pipeline = Pipeline([
    ('sampler', BiasResampler(
        transform_feature=to_high_clv
    ).set_fit_resample_request(sensitive_feature=True)),
    ('model', LogisticRegression())
])
param_grid = {'model__C': np.logspace(-5, 2, 10)}

grid_search = GridSearchCV(pipeline, param_grid=param_grid)
grid_search.fit(X, y, sensitive_feature=clv)

fit(X, y, **params)

Check inputs and statistics of the sampler.

You should use fit_resample in all cases.

Parameters:

X{array-like, dataframe, sparse matrix} of shape (n_samples, n_features)

Data array.

yarray-like of shape (n_samples,)

Target array.

Returns:

selfobject

Return the instance itself.

fit_resample(X, y, *, sensitive_feature=None)

Resample the data according to the strategy.

Parameters:

X2D array-like, shape=(n_samples, n_features)

y1D array-like, shape=(n_samples,)

sensitive_feature1D array-like, shape=(n_samples,)

Sensitive attribute used to determine which instances to resample.

Returns:

X2D array-like, shape=(n_samples, n_features)

Resampled training data.

y1D array-like, shape=(n_samples,)

Resampled target values.

get_feature_names_out(input_features=None)

Get output feature names for transformation.

Parameters:

input_featuresarray-like of str or None, default=None

Input features.

• If input_features is None, then feature_names_in_ is used as feature names in. If feature_names_in_ is not defined, then the following input feature names are generated: [“x0”, “x1”, …, “x(n_features_in_ - 1)”].

• If input_features is an array-like, then input_features must match feature_names_in_ if feature_names_in_ is defined.

Returns:

feature_names_outndarray of str objects

Same as input features.

get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest

A MetadataRequest encapsulating routing information.

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deepbool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict

Parameter names mapped to their values.

set_fit_resample_request(*, sensitive_feature='$UNCHANGED$')

Request metadata passed to the fit_resample method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to fit_resample if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to fit_resample.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters:

sensitive_featurestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for sensitive_feature parameter in fit_resample.

Returns:

selfobject

The updated object.

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:

**paramsdict

Estimator parameters.

Returns:

selfestimator instance

Estimator instance.