.. -- 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

要求

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

1. numpy
2. scipy
3. scikit-learn
4. scipy
5. pandas
6. gensim
7. plotly
8. requests
9. tqdm
10. 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},
    }

团队

• Pablo Badilla <https://github.com/pbadillatorrealba/>_
• Felipe Bravo-Marquez <https://felipebravom.com/>_
• Jorge Pérez <https://users.dcc.uchile.cl/~jperez/>_
• María José Zambrano <https://github.com/mzambrano1/>_

贡献者

我们感谢所有让 WEFE 得以成长的贡献者，特别是 stolenpyjak <https://github.com/stolenpyjak/>_ 和 mspl13 <https://github.com/mspl13/>_ 实现了新的度量。

我们还要感谢 alan-cueva <https://github.com/alan-cueva/>_ 开始开发 上下文化嵌入模型的度量，以及 harshvr15 <https://github.com/harshvr15/>_ 提供的多语言偏见测量示例。

非常感谢你们 😊！