.. image:: sphinx/source/_images/Gamma_Facet_Logo_RGB_LB.svg

FACET 是一个面向人类可解释性 AI 的开源库。 它结合了先进的模型检查和基于模型的仿真技术，从而能够更好地解释您的监督式机器学习模型。

FACET 由以下几个关键组件组成：

+-----------------+-----------------------------------------------------------------------+ | |spacer| | 模型检查 | | | | | |inspect| | FACET 引入了一种新算法，用于量化机器学习模型中特征之间的依赖关系和交互作用。| | | 这一面向人类可解释性 AI 的新工具为流行的 SHAP <https://shap.readthedocs.io/en/stable/>__ 方法所提供的样本级解释增添了全局视角。| | | 要了解更多关于 FACET 模型检查功能的信息，请参阅下方的入门示例。 | +-----------------+-----------------------------------------------------------------------+ | |spacer| | 模型仿真 | | | | | |sim| | FACET 的模型仿真算法利用机器学习模型进行 虚拟实验，以帮助识别能够优化预测结果的情形。| | | 为了量化仿真的不确定性，FACET 使用了一系列自助法算法，包括平稳自助法和分层自助法。| | | 关于 FACET 自助法仿真的示例，请参阅下方的快速入门示例。 | +-----------------+-----------------------------------------------------------------------+ | |spacer| | 增强的机器学习工作流 | | | | | |pipe| | FACET 提供了一个高效且透明的机器学习工作流，通过新增的模型选择、检查和仿真能力，增强了| | | scikit-learn <https://scikit-learn.org/stable/index.html>__ 经过验证的流水线范式。| | | 此外，FACET 还引入了 | | | sklearndf <https://github.com/BCG-X-Official/sklearndf>__ | | | [文档 <https://bcg-x-official.github.io/sklearndf/index.html>__]| | | 一个增强版的 scikit-learn，其对 pandas 数据框的支持更加完善，确保特征的端到端可追溯性。| +-----------------+-----------------------------------------------------------------------+

.. Begin-Badges

|pypi| |conda| |azure_build| |azure_code_cov| |python_versions| |code_style| |made_with_sphinx_doc| |License_badge|

.. End-Badges

安装

FACET 同时支持 PyPI 和 Anaconda。我们建议将 FACET 安装在一个专用的环境中。

Anaconda

.. code-block:: sh

    conda create -n facet
    conda activate facet
    conda install -c bcg_gamma -c conda-forge gamma-facet


Pip
~~~

macOS 和 Linux:
^^^^^^^^^^^^^^^^

.. code-block:: sh

    python -m venv facet
    source facet/bin/activate
    pip install gamma-facet

Windows:
^^^^^^^^

.. code-block:: dosbatch

    python -m venv facet
    facet\Scripts\activate.bat
    pip install gamma-facet


快速入门
----------

以下快速入门指南提供了一个最小化的示例工作流，帮助您快速上手 FACET。
如需更多教程和 API 参考，请参阅 `FACET 文档 <https://bcg-x-official.github.io/facet/docs-version/2-0>`__。

新版本的变更和新增内容已在 `发布说明 <https://bcg-x-official.github.io/facet/docs-version/2-0/release_notes.html>`__ 中总结。


增强的机器学习工作流

为了演示 FACET 的模型检查功能，我们首先创建一个流水线来拟合一个学习器。在这个简单的例子中，我们将使用| 糖尿病数据集 <https://web.stanford.edu/~hastie/Papers/LARS/diabetes.data>， 该数据集包含年龄、性别、BMI 和血压，以及 6 项血清指标作为特征。此数据集曾被用于这篇| 论文 <https://statweb.stanford.edu/~tibs/ftp/lars.pdf>。 该数据集的转换版本也可在 scikit-learn 上找到| 此处 <https://scikit-learn.org/stable/datasets/toy_dataset.html#diabetes-dataset>__。

在本快速入门中，我们将使用 10 次重复的 5 折交叉验证来训练一个随机森林回归模型，以预测一年后的疾病进展。借助| sklearndf，我们可以创建一个与 pandas DataFrame 兼容的工作流。然而，FACET 还提供了额外的功能，可以使用样本对象 (Sample) 来跟踪我们的特征矩阵和目标向量，并轻松比较超参数配置，甚至多个学习器之间的差异，这得益于 LearnerSelector。

.. code-block:: Python

# 标准导入
import pandas as pd
from sklearn.model_selection import RepeatedKFold, GridSearchCV

# sklearndf 中的一些实用导入
from sklearndf.pipeline import RegressorPipelineDF
from sklearndf.regression import RandomForestRegressorDF

# 相关的 FACET 导入
from facet.data import Sample
from facet.selection import LearnerSelector, ParameterSpace

# 声明数据的 URL
data_url = 'https://web.stanford.edu/~hastie/Papers/LARS/diabetes.data'

# 从 URL 导入数据
diabetes_df = pd.read_csv(data_url, delimiter='\t').rename(
    # 重命名列以提高可读性
    columns={
        'S1': 'TC', # 总血清胆固醇
        'S2': 'LDL', # 低密度脂蛋白
        'S3': 'HDL', # 高密度脂蛋白
        'S4': 'TCH', # 总胆固醇与 HDL 的比值
        'S5': 'LTG', # 拉莫三嗪浓度
        'S6': 'GLU', # 血糖水平
        'Y': 'Disease_progression' # 与基线相比一年后的疾病进展度
    }
)

创建 FACET 示例对象

diabetes_sample = Sample(observations=diabetes_df, target_name="Disease_progression")

# 为随机森林回归器创建一个（简单的）管道
rnd_forest_reg = RegressorPipelineDF(
    regressor=RandomForestRegressorDF(n_estimators=200, random_state=42)
)

# 定义用于相互“竞争”的模型的参数空间
rnd_forest_ps = ParameterSpace(rnd_forest_reg)
rnd_forest_ps.regressor.min_samples_leaf = [8, 11, 15]
rnd_forest_ps.regressor.max_depth = [4, 5, 6]

# 创建重复 k 折交叉验证迭代器
rkf_cv = RepeatedKFold(n_splits=5, n_repeats=10, random_state=42)

# 根据性能对候选模型进行排名
selector = LearnerSelector(
    searcher_type=GridSearchCV,
    parameter_space=rnd_forest_ps,
    cv=rkf_cv,
    n_jobs=-3,
    scoring="r2"
).fit(diabetes_sample)

# 获取总结报告
selector.summary_report()

.. image:: sphinx/source/_images/ranker_summary.png :width: 600

从这个最简工作流中可以看出，对于叶节点中的最小样本数，取值 11；对于树的最大深度，取值 5，是所考虑的三个值中表现最好的。 这种方法可以很容易地扩展到学习器的其他超参数，以及多个学习器。

模型检查

FACET 为 `scikit-learn <https://scikit-learn.org/stable/index.html>`__ 的估计器实现了多种模型检查方法。
FACET 通过提供补充 SHAP 局部视角的全局指标来增强模型检查功能（有关正式描述，请参阅
`[arXiv:2107.12436] <https://arxiv.org/abs/2107.12436>`__）。

模型中每对特征的关键全局指标包括：

- **协同性**

  模型将一个特征的信息与另一个特征结合以预测目标的程度。例如，假设我们使用年龄和性别来预测心血管健康状况，而拟合的模型包含了两者之间复杂的交互作用。这意味着这两个特征在预测心血管健康方面具有协同性。此外，这两个特征对模型都很重要，去掉任何一个都会显著影响模型性能。假设年龄在共同贡献中比性别提供了更多的信息。这种不对称的贡献意味着 (age, gender) 的协同性低于 (gender, age) 的协同性。换一种方式来理解：把预测结果看作一个你试图到达的目标坐标。从起点出发，年龄比性别更能让你接近这个目标，然而你需要同时利用两者才能达到。协同性反映了这样一个事实：性别从年龄那里获得的帮助更多（从性别角度看协同性更高），而年龄从性别那里获得的帮助较少（从年龄角度看协同性更低），从而共同达到预测结果。*由此引出一个重要点：协同性是两个相互作用的特征为模型预测贡献的全局信息所具有的天然非对称属性。* 协同性用百分比表示，范围从 0%（完全自主）到 100%（完全协同）。

- **冗余性**

  模型中一个特征在预测目标时对另一个特征信息的重复程度。例如，假设我们使用房屋面积和卧室数量来预测房价。这两个特征捕捉的信息相似：卧室越多，房屋通常越大，平均价格也越高。因此，(number of bedrooms, house size) 的冗余性会大于 (house size, number of bedrooms) 的冗余性。这是因为房屋面积比卧室数量更清楚地知道后者在预测房价方面的作用，所以从卧室数量的角度来看，其冗余性更大。另一种理解方式是：移除房屋面积对模型性能的影响会比移除卧室数量更大，因为房屋面积能够更好地弥补卧室数量缺失带来的影响。这也意味着，在模型中，房屋面积的重要性可能高于卧室数量。*这里的重要点是，与协同性一样，冗余性也是特征对在预测结果方面所具有的全局信息的天然非对称属性。* 冗余性用百分比表示，范围从 0%（完全独特）到 100%（完全冗余）。

.. code-block:: Python

    # 拟合模型检查器
    from facet.inspection import LearnerInspector
    inspector = LearnerInspector(
        pipeline=selector.best_estimator_,
        n_jobs=-3
    ).fit(diabetes_sample)

**协同性**

.. code-block:: Python

    # 将协同性可视化为矩阵
    from pytools.viz.matrix import MatrixDrawer
    synergy_matrix = inspector.feature_synergy_matrix()
    MatrixDrawer(style="matplot%").draw(synergy_matrix, title="Synergy Matrix")

.. image:: sphinx/source/_images/synergy_matrix.png
    :width: 600

对于任意特征对 (A, B)，第一个特征 (A) 代表行，第二个特征 (B) 代表列。例如，查看 `LTG`（拉莫三嗪）这一行时，它与其他特征之间的协同性几乎为零（≤ 1%）。然而，从 `LTG` 这一列往下看（即从其他特征相对于 `LTG` 的角度），我们会发现许多特征（行）受益于与 `LTG` 的协同作用（例如，LDL 最高可达 27%）。由此我们可以得出结论：

- `LTG` 是一个高度自主的特征，与其他特征在预测一年后疾病进展方面的协同性极低。
- 其他特征在预测一年后疾病进展中的贡献，部分得益于 `LTG` 的存在。

当研究影响时，必须仔细考虑特征对之间的高协同性，因为两者的值共同决定了最终结果。鉴于 `LDL` 与 `LTG` 在预测一年后疾病进展方面的协同性接近 27%，单独考虑 `LDL` 而不结合 `LTG` 提供的背景信息是没有太大意义的。

**冗余性**

.. code-block:: Python

    # 将冗余性可视化为矩阵
    redundancy_matrix = inspector.feature_redundancy_matrix()
    MatrixDrawer(style="matplot%").draw(redundancy_matrix, title="Redundancy Matrix")

.. image:: sphinx/source/_images/redundancy_matrix.png
    :width: 600


对于任意特征对 (A, B)，第一个特征 (A) 代表行，第二个特征 (B) 代表列。例如，如果我们从 `LDL`（低密度脂蛋白）的角度来看特征对 (`LDL`, `TC`)，则在 `LDL` 行和 `TC` 列的交界处可以看到 38% 的冗余性。这意味着 `LDL` 用于预测疾病进展的信息中有 38% 在 `TC` 中被重复了。从 `TC` 的角度看待 (`TC`, `LDL`) 时，也会得到相同的冗余性，但并非所有情况都具有对称性（如 `LTG` 与 `TCH` 的例子）。

如果我们来看 `TCH`，它与 `LTG` 和 `HDL` 分别有 22% 到 32% 的冗余度，但
`LTG` 和 `HDL` 之间并不具备同样的冗余性——这意味着 `TCH` 与这两个特征分别共享不同的信息。


**聚类冗余**

如上文所述，对于一对特征而言，冗余和协同是从这对特征中其中一个“视角”来衡量的，因此会得到两个不同的值。然而，也可以计算出一种对称版本的指标，这不仅简化了分析视角，还允许将 (1 - 指标) 作为特征之间的距离使用。利用这种距离，可以应用层次聚类中的单链接法来生成树状图可视化结果。这有助于识别低距离的特征群，即那些在预测结果时“协同”工作的特征。随后，这些信息可用于将高度冗余的特征群缩减为一个子集，或者突出显示那些应始终一起考虑的高度协同特征群。

让我们以冗余为例进行说明。

.. code-block:: Python

    # 使用树状图可视化冗余
    from pytools.viz.dendrogram import DendrogramDrawer
    redundancy = inspector.feature_redundancy_linkage()
    DendrogramDrawer().draw(data=redundancy, title="冗余树状图")

.. image:: sphinx/source/_images/redundancy_dendrogram.png
    :width: 600

根据树状图，我们可以看到 (`LDL`, `TC`) 和 (`HDL`, `TCH`) 这两对特征各自构成了树状图中的一个簇，而 `LTG` 和 `BMI` 则具有最高的重要性。作为下一步行动，我们可以探索移除 `TCH` 以及 `TC` 或 `LDL` 中的一个对模型的影响，从而进一步简化模型并获得一组独立的特征子集。

更多详细信息请参阅
`API 参考 <https://bcg-x-official.github.io/facet/apidoc/facet.html>`__。


模型模拟

以 BMI 特征为例，它是一个重要且高度独立的特征，我们按照以下步骤进行模拟：

• 我们使用 FACET 的 ContinuousRangePartitioner 将 BMI 的观测值范围划分为等大小的区间。每个区间由该区间的中心值代表。
• 对于每个区间，模拟器会创建原始样本的人工副本，假设待模拟的变量在所有观测中都取相同的值——即代表该区间的值。然后，模拟器使用选择器获取的最佳估计器，基于全样本训练的模型重新预测所有目标值，并确定由此带来的目标变量提升。
• FACET 的 SimulationDrawer 允许我们以 matplotlib 和纯文本两种方式可视化结果。

.. code-block:: Python

# FACET 导入
from facet.validation import BootstrapCV
from facet.simulation import UnivariateUpliftSimulator
from facet.data.partition import ContinuousRangePartitioner
from facet.simulation.viz import SimulationDrawer

# 创建自助法交叉验证迭代器
bscv = BootstrapCV(n_splits=1000, random_state=42)

SIM_FEAT = "BMI"
simulator = UnivariateUpliftSimulator(
    model=selector.best_estimator_,
    sample=diabetes_sample,
    n_jobs=-3
)

# 将模拟范围划分为等大小的区间
partitioner = ContinuousRangePartitioner()

# 运行模拟
simulation = simulator.simulate_feature(feature_name=SIM_FEAT, partitioner=partitioner)

# 可视化结果
SimulationDrawer().draw(data=simulation, title=SIM_FEAT)

.. image:: sphinx/source/_images/simulation_output.png

从图中我们可以得出结论：较高的 BMI 值与一年后疾病进展的加剧相关，当 BMI 达到 28 或以上时，一年后的疾病进展显著增加，至少提高了 26 个点。

贡献

FACET 稳定可靠，并将持续得到长期支持。

欢迎并感谢大家对 FACET 的贡献。如有任何错误报告或功能请求/改进，请使用相应的 GitHub 表单 <https://github.com/BCG-X-Official/facet/issues>_；如果您希望直接提交代码，请打开一个 PR 来解决相应的问题。

对于任何重大更改，请先通过 issue 或发送邮件至我们的团队邮箱 FacetTeam@bcg.com 与我们讨论。

有关贡献的更多信息，请参阅我们的 贡献指南 <https://bcg-x-official.github.io/facet/contribution_guide.html>__。

许可证

FACET 根据 LICENSE <https://github.com/BCG-X-Official/facet/blob/develop/LICENSE>_ 文件的规定，采用 Apache 2.0 许可证授权。

致谢

FACET 构建于两个流行的机器学习库之上：

• scikit-learn <https://scikit-learn.org/stable/index.html>__ 的学习算法和流水线技术构成了底层算法的实现。此外，我们还努力使 FACET 的 API 与 scikit-learn 的 API 保持一致。
• SHAP <https://shap.readthedocs.io/en/latest/>__ 的实现用于估算 Shapley 值，FACET 随后将其分解为协同、冗余和独立向量。

BCG GAMMA

如果您想了解更多关于 FACET 团队的信息，请访问 关于我们 <https://bcg-x-official.github.io/facet/about_us.html>__ 页面。

我们始终在寻找充满热情且才华横溢的数据科学家加入 BCG GAMMA 团队。如需了解更多信息，您可以访问 BCG GAMMA <https://www.bcg.com/en-gb/beyond-consulting/bcg-gamma/default>， 或查看 职业机会 <https://www.bcg.com/en-gb/beyond-consulting/bcg-gamma/careers>。

.. |pipe| image:: sphinx/source/_images/icons/pipe_icon.png :width: 100px :class: facet_icon

.. |inspect| image:: sphinx/source/_images/icons/inspect_icon.png :width: 100px :class: facet_icon

.. |sim| image:: sphinx/source/_images/icons/sim_icon.png :width: 100px :class: facet_icon

.. |spacer| unicode:: 0x2003 0x2003 0x2003 0x2003 0x2003 0x2003

.. Begin-Badges

.. |conda| image:: https://anaconda.org/bcg_gamma/gamma-facet/badges/version.svg :target: https://anaconda.org/BCG_Gamma/gamma-facet

.. |pypi| image:: https://badge.fury.io/py/gamma-facet.svg :target: https://pypi.org/project/gamma-facet/

.. |azure_build| image:: https://dev.azure.com/gamma-facet/facet/_apis/build/status/BCG-X-Official.facet?repoName=BCG-X-Official%2Ffacet&branchName=develop :target: https://dev.azure.com/gamma-facet/facet/_build?definitionId=7&_a=summary

.. |azure_code_cov| image:: https://img.shields.io/azure-devops/coverage/gamma-facet/facet/7/2.0.x :target: https://dev.azure.com/gamma-facet/facet/_build?definitionId=7&_a=summary

.. |python_versions| image:: https://img.shields.io/badge/python-3.7|3.8|3.9-blue.svg :target: https://www.python.org/downloads/release/python-380/

.. |code_style| image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black

.. |made_with_sphinx_doc| image:: https://img.shields.io/badge/Made%20with-Sphinx-1f425f.svg :target: https://bcg-x-official.github.io/facet/index.html

.. |license_badge| image:: https://img.shields.io/badge/License-Apache%202.0-olivegreen.svg :target: https://opensource.org/licenses/Apache-2.0

.. 结束-徽章

FACET 快速上手指南

FACET 是一个开源的可解释人工智能（XAI）库，旨在通过先进的模型检查和基于模型的模拟技术，为监督学习模型提供更深入的洞察。它补充了 SHAP 等局部解释方法，提供了全局视角的特征依赖与交互量化，并增强了 scikit-learn 的工作流。

环境准备

• 操作系统: macOS, Linux, Windows
• Python 版本: 支持主流 Python 3.x 版本（具体兼容版本请参考 PyPI 页面）
• 前置依赖:
  • scikit-learn: FACET 深度集成并增强了 scikit-learn 的功能。
  • pandas: 用于数据处理，FACET 通过 sklearndf 提供对 DataFrame 的原生支持。
  • numpy, matplotlib 等科学计算库。
• 推荐配置: 建议在独立的虚拟环境中安装，以避免依赖冲突。

安装步骤

FACET 支持通过 Conda 和 Pip 进行安装。

方式一：使用 Conda (推荐)

适用于 Anaconda 或 Miniconda 用户。

# 创建名为 facet 的新环境
conda create -n facet

# 激活环境
conda activate facet

# 从 bcg_gamma 和 conda-forge 频道安装
conda install -c bcg_gamma -c conda-forge gamma-facet

方式二：使用 Pip

macOS 和 Linux

# 创建虚拟环境
python -m venv facet

# 激活环境
source facet/bin/activate

# 安装 FACET
pip install gamma-facet

Windows

REM 创建虚拟环境
python -m venv facet

REM 激活环境
facet\Scripts\activate.bat

REM 安装 FACET
pip install gamma-facet

注意：国内用户若遇到下载速度慢的问题，可在 pip 命令后添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 使用清华镜像源。Conda 用户可配置清华或中科大镜像通道。

基本使用

以下示例演示了如何使用 FACET 构建增强的机器学习工作流，进行模型选择，并执行模型检查（特征协同性分析）。本例使用糖尿病数据集预测疾病进展。

1. 增强型机器学习工作流与模型选择

FACET 引入 Sample 对象来追踪特征和目标，并使用 LearnerSelector 轻松比较不同的超参数配置。

# 标准导入
import pandas as pd
from sklearn.model_selection import RepeatedKFold, GridSearchCV

# sklearndf 导入 (FACET 增强的 scikit-learn)
from sklearndf.pipeline import RegressorPipelineDF
from sklearndf.regression import RandomForestRegressorDF

# FACET 核心导入
from facet.data import Sample
from facet.selection import LearnerSelector, ParameterSpace

# 1. 加载数据
data_url = 'https://web.stanford.edu/~hastie/Papers/LARS/diabetes.data'
diabetes_df = pd.read_csv(data_url, delimiter='\t').rename(
    columns={
        'S1': 'TC', 'S2': 'LDL', 'S3': 'HDL', 
        'S4': 'TCH', 'S5': 'LTG', 'S6': 'GLU', 
        'Y': 'Disease_progression'
    }
)

# 2. 创建 FACET Sample 对象
diabetes_sample = Sample(observations=diabetes_df, target_name="Disease_progression")

# 3. 定义随机森林回归管道
rnd_forest_reg = RegressorPipelineDF(
    regressor=RandomForestRegressorDF(n_estimators=200, random_state=42)
)

# 4. 定义超参数搜索空间
rnd_forest_ps = ParameterSpace(rnd_forest_reg)
rnd_forest_ps.regressor.min_samples_leaf = [8, 11, 15]
rnd_forest_ps.regressor.max_depth = [4, 5, 6]

# 5. 设置交叉验证策略 (10 次重复的 5 折 CV)
rkf_cv = RepeatedKFold(n_splits=5, n_repeats=10, random_state=42)

# 6. 模型选择与训练
selector = LearnerSelector(
    searcher_type=GridSearchCV,
    parameter_space=rnd_forest_ps,
    cv=rkf_cv,
    n_jobs=-3,
    scoring="r2"
).fit(diabetes_sample)

# 7. 查看最佳模型摘要
print(selector.summary_report())

2. 模型检查：特征协同性 (Synergy)

FACET 能够量化特征之间的全局交互作用（协同性），这是 SHAP 等局部解释方法所不具备的。

from facet.inspection import LearnerInspector
from pytools.viz.matrix import MatrixDrawer

# 1. 初始化并拟合检查器 (使用上一步选出的最佳模型)
inspector = LearnerInspector(
    pipeline=selector.best_estimator_,
    n_jobs=-3
).fit(diabetes_sample)

# 2. 获取特征协同矩阵
synergy_matrix = inspector.feature_synergy_matrix()

# 3. 可视化协同矩阵
# 矩阵行表示特征 A，列表示特征 B。值表示 A 对 B 预测能力的贡献程度。
MatrixDrawer(style="matplot%").draw(synergy_matrix, title="Synergy Matrix")

结果解读：

• 协同性 (Synergy): 衡量模型如何结合两个特征的信息来预测目标。该指标是不对称的。例如，若特征 A 能显著提升特征 B 的预测能力，但反之亦然程度较低，则 (B, A) 的协同值会高于 (A, B)。
• 冗余性 (Redundancy): 衡量一个特征在多大程度上重复了另一个特征的信息（同样是不对称的）。

通过上述流程，您可以快速构建透明、可追溯的机器学习管道，并深入理解模型内部特征间的复杂交互关系。更多高级功能（如模型模拟、自助法不确定性量化）请参阅官方文档。