.. -- mode: rst --

|许可证|_ |GitHub操作|_ |ReadTheDocs|_ |下载量|_ |Pypy|_ |Conda版本|_

.. |许可证| image:: https://img.shields.io/github/license/dccuchile/wefe .. _许可证: https://github.com/dccuchile/wefe/blob/master/LICENSE

.. |ReadTheDocs| image:: https://readthedocs.org/projects/wefe/badge/?version=latest .. _ReadTheDocs: https://wefe.readthedocs.io/en/latest/?badge=latest

.. |GitHub操作| image:: https://github.com/dccuchile/wefe/actions/workflows/ci.yaml/badge.svg?branch=master .. _GitHub操作: https://github.com/dccuchile/wefe/actions

.. |下载量| image:: https://pepy.tech/badge/wefe .. _下载量: https://pepy.tech/project/wefe

.. |Pypy| image:: https://badge.fury.io/py/wefe.svg .. _Pypy: https://pypi.org/project/wefe/

.. |Conda版本| image:: https://anaconda.org/pbadilla/wefe/badges/version.svg .. _Conda版本: https://anaconda.org/pbadilla/wefe

WEFE：词嵌入公平性评估框架

.. image:: ./docs/logos/WEFE_2.png :width: 300 :alt: WEFE标志 :align: center

词嵌入公平性评估（WEFE）是一个开源库，用于测量和缓解词嵌入模型中的偏见。它将许多现有的公平性指标整合到一个统一的框架中，并提供了一个标准接口用于：

封装以前工作中的现有公平性指标并设计新的指标。
将公平性指标使用的测试词封装到称为查询的标准对象中。
使用用户给定的查询在给定的预训练词嵌入模型上计算公平性指标。

WEFE还通过类似于scikit-learn的fit-transform接口标准化了缓解偏见的过程。这种标准化将缓解过程分为两个阶段：

计算要对模型执行的转换的逻辑（fit）。
在模型上执行缓解转换（transform）。

官方文档可在此链接 <https://wefe.readthedocs.io/>_找到。

安装

有两种不同的方法安装WEFE：

使用pip安装包::

pip install wefe

使用conda：

使用conda安装包::

conda install -c pbadilla wefe

要求

如果尚未安装这些包，它们将随包一起安装：

numpy
scipy
scikit-learn
scipy
pandas
gensim
plotly
requests
tqdm
semantic_version

贡献

您可以通过执行以下命令下载代码::

git clone https://github.com/dccuchile/wefe

要贡献，请访问文档中的贡献 <https://wefe.readthedocs.io/en/latest/user_guide/contribute.html>_部分。

开发要求

要安装WEFE开发、测试和编译文档所需的依赖项，请运行::

pip install -r requirements-dev.txt

测试

所有单元测试都在wefe/tests文件夹中。它使用pytest作为运行框架。

要运行测试，请执行::

pytest tests

要检查覆盖率，请运行::

pytest tests --cov-report xml:cov.xml --cov wefe

然后::

coverage report -m

构建文档

文档使用sphinx创建。它可以在项目根目录的docs文件夹中找到。要编译文档，请运行：

.. code-block:: bash

cd docs
make html

然后，您可以在docs/_build/html/index.html查看文档

更新日志

版本0.4.1

修复了RIPA中最后一对目标词未包含的错误。
在文档中添加了一个基准测试，将WEFE与其他测量和偏见缓解库进行比较。
在文档中添加了一个库自原始论文发布以来的变更页面。

版本0.4.0

实现了3种新的偏见缓解方法（去偏）：双重硬去偏、半兄弟回归和排斥吸引中和。
重构了库的文档结构。现在，文档分为用户指南和理论框架。用户指南不包含理论信息。相反，理论文档可以在概念指南中找到。
改进了API文档和示例。添加了由社区贡献的多语言示例。
用户指南现在完全可执行，因为它们现在是笔记本形式。
还对API文档以及指标和去偏示例进行了重要改进。
改进了库对指标和去偏方法的测试机制。
修复了查询的错误repr。现在集合按正确顺序排列。
为WordEmbeddingModel实现了repr。
测试CI从CircleCI迁移到GithubActions。
许可证更改为MIT。

版本0.3.2

修复了RNSB错误，其中分类标签被互换，当属性大小不同时可能产生错误结果。
修复了RNSB复制笔记本
更新了WEFE案例研究分数。
改进了WEAT、RNSB、RIPA的文档示例。
为RNSB添加了holdout参数，允许指示在训练分类器时是否执行留出。
改进了RNSB评估的打印。

版本0.3.1

更新WEFE原始案例研究
热修复：修复了执行WEFE原始案例研究的多个错误。
fetch_eds top_n_race_occupations参数设置为10。
预处理：get_embeddings_from_set现在返回一个包含丢失的预处理词的列表，而不是原始词。版本 0.3.0

实现了 Bolukbasi 等人 2016 年提出的硬消偏方法。
实现了 Thomas Manzini 等人 2019 年提出的多类硬消偏方法。
实现了一个获取函数来检索 gn-glove 女性-男性词集。
将单词、集合和查询到嵌入的转换逻辑移至独立模块：preprocessing
增强了度量预处理参数 preprocessor_args 和 secondary_preprocessor_args，将其改为预处理器列表 preprocessors，并添加参数 strategy 指示是考虑所有转换后的词（'all'）还是仅考虑首个遇到的词（'first'）。
将 WordEmbeddingModel 属性 model 和 model_name 分别重命名为 wv 和 name。
将每个度量中 run_query 的 word_embedding 参数重命名为 model。

版本 0.2.2

添加了 RIPA 度量（感谢 @stolenpyjak 的贡献！）。
修复了 Literal 类型错误，使 WEFE 兼容 Python 3.7。

版本 0.2.1

兼容性修复。

版本 0.2.0

将 run_query 可选参数 warn_filtered_words 重命名为 warn_not_found_words。
为 run_query 添加了 word_preprocessor_args 参数，允许在词嵌入中搜索单词之前指定转换。
为 run_query 添加了 secondary_preprocessor_args 参数，允许在词嵌入中搜索单词之前指定第二个预处理转换。使用此参数不需要指定第一个预处理器。
在 WordEmbeddingModel 中实现了 __getitem__ 函数。该方法允许使用索引从存储在实例中的模型获取单词的嵌入。
移除了类和实例变量名中的下划线。
改进了创建对象和执行方法时的类型和验证异常消息。
修复了在计算具有两列相同名称聚合的排名时出现的错误。
现在使用 pandas corr 方法计算排名相关性。
将度量模板、名称和短名称更改为类变量。
在 RNSB 中实现了 random_state，以允许实验复现。
run_query 现在返回参数中请求的默认度量作为结果，并在字典的其他变量中返回所有可能有用的计算值。
修复了 API 文档问题：现在显示类的方法。
为 WEAT 实现了 p 值

引用

如果在学术出版物中使用此包，请引用以下论文：

P. Badilla, F. Bravo-Marquez, 和 J. Pérez WEFE: The Word Embeddings Fairness Evaluation Framework In Proceedings of the 29th International Joint Conference on Artificial Intelligence and the 17th Pacific Rim International Conference on Artificial Intelligence (IJCAI-PRICAI 2020), Yokohama, Japan. <https://www.ijcai.org/Proceedings/2020/60>_

Bibtex:

.. code-block:: latex

@InProceedings{wefe2020,
    title     = {WEFE: The Word Embeddings Fairness Evaluation Framework},
    author    = {Badilla, Pablo and Bravo-Marquez, Felipe and Pérez, Jorge},
    booktitle = {Proceedings of the Twenty-Ninth International Joint Conference on
               Artificial Intelligence, {IJCAI-20}},
    publisher = {International Joint Conferences on Artificial Intelligence Organization},
    pages     = {430--436},
    year      = {2020},
    month     = {7},
    doi       = {10.24963/ijcai.2020/60},
    url       = {https://doi.org/10.24963/ijcai.2020/60},
    }