`wefe.debias.half_sibling_regression`.HalfSiblingRegression

class wefe.debias.half_sibling_regression.HalfSiblingRegression(verbose: bool = False, criterion_name: str | None = None)[source]

Bases: BaseDebias

Half Sibling Debias method.

This method proposes to learn spurious gender information via causal inference by utilizing the statistical dependency between gender-biased word vectors and gender definition word vectors. The learned spurious gender information is then subtracted from the gender-biased word vectors to achieve gender-debiasing as the following where $V_n$ are the debiased word vectors, Vn are non gender definition and $G$ is the approximated gender information:

\[V_n' := V_n - G\]

G is obtained by predicting Non gender definition word vectors ($V_n$) using the gender-definition word vectors ($V_d$):

\[G := E[V_n|V_d]\]

The Prediction is done by a Ridge Regression following the next steps:

Compute the weight matrix of a Ridge Regression using two sets of words

\[W = ((V_d)^T V_d + \alpha I)^{-1} (V_d)^TV_n\]

Compute the gender information:

\[G = V_d W\]

Subtract gender information from non gender definition words:

\[V_n' = V_n - G\]

This method is binary because it only allows 2 classes of the same bias criterion, such as male or female. For a multiclass debias (such as for Latinos, Asians and Whites), it is recommended to visit MulticlassHardDebias class.

Warning

This method requires three times the memory of the model when a copy of the model is made and two times the memory of the model if not. Make sure this much memory is available.

Examples

The following example shows how to execute Half Sibling Regression Debias method that reduces bias in a word embedding model:

>>> from wefe.debias.half_sibling_regression import HalfSiblingRegression
>>> from wefe.utils import load_test_model
>>> from wefe.datasets import fetch_debiaswe
>>>
>>> # load the model (in this case, the test model included in wefe)
>>> model = load_test_model()
>>> # load gender specific words, in this case the ones included in wefe
>>> debiaswe_wordsets = fetch_debiaswe()
>>> gender_specific = debiaswe_wordsets["gender_specific"]
>>>
>>> # instance and fit the method
>>> hsr = HalfSiblingRegression().fit(
...     model=model, definitional_words=gender_specific
... )
>>> # execute the debias on the words not included in the gender definition set
>>> debiased_model = hsr.transform(model = model)
Copy argument is True. Transform will attempt to create a copy of the original
model. This may fail due to lack of memory.
Model copy created successfully.
>>>
>>>
>>> # if you want the debias over a specific set of words  you can
>>> #include them in the target parameter
>>> debiased_model = hsr.transform(
...     model=model, target=["doctor", "nurse", "programmer"]
... )
Copy argument is True. Transform will attempt to create a copy of the original
model. This may fail due to lack of memory.
Model copy created successfully.
>>>
>>> # if you want to exclude a set of words from the debias process
>>> # you can include them in the ignore parameter
>>> debiased_model = hsr.transform(
...     model=model, ignore=["dress", "beard", "niece", "nephew"]
... )
Copy argument is True. Transform will attempt to create a copy of the original
model. This may fail due to lack of memory.
Model copy created successfully.

References

[1]: Yang, Zekun y Juan Feng: A causal inference method for reducing

gender bias in word embedding relations.

In Proceedings of the AAAI Conference on Artificial Intelligence, volumen 34, pages 9434–9441, 2020

[2]: https://github.com/KunkunYang/GenderBiasHSR

[3]: Bernhard Sch ̈olkopf, David W. Hogg, Dun Wang,

Daniel Foreman-Mackey, Dominik Jan-zing, Carl-Johann Simon-Gabriel,
and Jonas Peters.
Modeling confounding by half-sibling regression.
Proceedings of the National Academy of Sciences, 113(27):7391–7398, 2016

__init__(verbose: bool = False, criterion_name: str | None = None) → None[source]

Initialize a Half Sibling Regression Debias instance.

Parameters:

verbose (bool, optional) – True will print informative messages about the debiasing process, by default False.
criterion_name (Optional[str], optional) – The name of the criterion for which the debias is being executed, e.g., ‘Gender’. This will indicate the name of the model returning transform, by default None

fit(model: WordEmbeddingModel, definitional_words: list[str], alpha: float = 60) → BaseDebias[source]

Compute the weight matrix and the bias information.

Parameters:

model (WordEmbeddingModel) – The word embedding model to debias.
definitional_words (List[str]) – List of strings. This list contains words that embody bias information by definition.
alpha (float) – Ridge Regression constant. By default 60.

Returns:

The debias method fitted.

Return type:

BaseDebias

fit_transform(model: WordEmbeddingModel, target: list[str] | None = None, ignore: list[str] | None = None, copy: bool = True, **fit_params) → WordEmbeddingModel

Convenience method to execute fit and transform in a single call.

Parameters:

model (WordEmbeddingModel) – A word embedding model object.
target (Optional[List[str]], optional) – If a set of words is specified in target, the debias method will be applied only on the word embeddings of this set, by default None.
ignore (Optional[List[str]], optional) – If target is None and a set of words is specified in ignore, the debias method will debias all words except those specified in ignore, by default None.
copy (bool, optional) – If True, the debias will be performed on a copy of the model. If False, the debias will be applied on the same model delivered, causing its vectors to mutate. WARNING: Setting copy with True requires at least 2x RAM of the size of the model. Otherwise the execution of the debias may raise MemoryError, by default True.
verbose (bool, optional) – True will print informative messages about the debiasing process, by default True.

Returns:

The debiased word embedding model.

Return type:

WordEmbeddingModel

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

name: str = 'Half Sibling Regression'

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to fit 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.
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.

Parameters:

alpha (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for alpha parameter in fit.
definitional_words (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for definitional_words parameter in fit.
model (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for model parameter in fit.

Returns:

self – The updated object.

Return type:

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:: **params (dict) – Estimator parameters.
Returns:: self – Estimator instance.
Return type:: estimator instance

Configure whether metadata should be requested to be passed to the transform method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to transform 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 transform.
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.

Parameters:

copy (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for copy parameter in transform.
ignore (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for ignore parameter in transform.
model (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for model parameter in transform.
target (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for target parameter in transform.

Returns:

self – The updated object.

Return type:

object

short_name = 'HSR'

transform(model: WordEmbeddingModel, target: list[str] | None = None, ignore: list[str] | None = None, copy: bool = True) → WordEmbeddingModel[source]

Substracts the gender information from vectors.

Parameters:

model (WordEmbeddingModel) – The word embedding model to mitigate.
target (Optional[List[str]], optional) – If a set of words is specified in target, the debias method will be performed only on the word embeddings of this set. If None is provided, the debias will be performed on all non gender specific words (except those specified in ignore). Target words must not be included in the gender specific set. by default None.
ignore (Optional[List[str]], optional) – If target is None and a set of words is specified in ignore, the debias method will perform the debias in all non gender specific words except those specified in this set, by default [].
copy (bool, optional) – If True, the debias will be performed on a copy of the model. If False, the debias will be applied on the same model delivered, causing its vectors to mutate. WARNING: Setting copy with True requires RAM at least 2x of the size of the model, otherwise the execution of the debias may raise to MemoryError, by default True.

Returns:

The debiased embedding model.

Return type:

WordEmbeddingModel

wefe.debias.half_sibling_regression.HalfSiblingRegression

`wefe.debias.half_sibling_regression`.HalfSiblingRegression