balance: 一个用于平衡有偏数据样本的 Python 包

[!注意] balance 目前处于 测试阶段，并得到积极维护。请在 GitHub 上关注我们。

什么是 balance？

balance 是一个 Python 包，提供了一套 简单的工作流程和方法，用于在从有偏样本推断目标总体时， 处理有偏数据样本的问题。

有偏样本通常出现在 调查统计学 中，当受访者表现出 无响应偏差 或调查本身存在 抽样偏差（而非 完全随机缺失）时。类似的问题也会出现在 观察性研究 中，在比较接受治疗与未接受治疗的组别时，以及任何存在选择偏差的数据中。

在随机缺失假设 (MAR) 下，样本中的偏差有时可以通过利用辅助信息（即“协变量”或“特征”）来部分缓解——这些信息既存在于样本中的所有个体中，也存在于来自总体的样本中。例如，如果我们希望从某次调查的样本中进行推断，可以使用年龄、性别、教育程度等人口统计信息来调整无响应偏差。这可以通过利用辅助信息对样本进行加权，使其更接近总体分布来实现。

该包面向希望使用 Python 包来平衡有偏样本的研究人员，例如来自调查的数据。这种需求可能出现在调查方法学家、人口统计学家、用户体验研究人员、市场研究人员，以及广义上的数据科学家、统计学家和机器学习从业者中。

更多方法论背景可参见 Sarig, T., Galili, T., & Eilat, R. (2023). balance – a Python package for balancing biased data samples。

安装

要求

运行 balance 需要 Python 3.9、3.10、3.11、3.12、3.13 或 3.14。balance 可以在 Linux、OSX 和 Windows 上构建和运行。

所需的 Python 依赖项如下：

REQUIRES = [
    # Numpy 和 pandas：严格控制版本以确保二进制兼容性
    "numpy>=1.21.0,<2.0; python_version<'3.12'",
    "numpy>=1.24.0; python_version>='3.12'",
    "pandas>=1.5.0,<4.0.0; python_version<'3.12'",
    "pandas>=2.0.0,<4.0.0; python_version>='3.12'",
    # 科学计算栈
    "scipy>=1.7.0,<1.14.0; python_version<'3.12'",
    "scipy>=1.11.0; python_version>='3.12'",
    "scikit-learn>=1.0.0,<1.4.0; python_version<'3.12'",
    "scikit-learn>=1.3.0; python_version>='3.12'",
    "ipython",
    "patsy",
    "seaborn",
    "plotly",
    "matplotlib",
    "statsmodels",
    "session-info",
]

更多详细信息请参阅 pyproject.toml。

安装 balance

通过 PyPI 安装

我们建议通过 pip 从 PyPI 安装 balance 的最新稳定版本：

python -m pip install balance

安装将使用 PyPI 提供的 Python 轮包，适用于 OSX、Linux 和 Windows。

从源代码/Git 安装

您也可以从 Git 安装最新的（前沿）版本：

python -m pip install git+https://github.com/facebookresearch/balance.git

或者，如果您已经克隆了仓库：

cd balance
python -m pip install .

也可以使用开发依赖项：

cd balance
python -m pip install .[dev]

入门

balance 的高级工作流程

balance 的核心工作流程涉及为样本拟合和评估权重。对于样本中的每个单元（例如调查的受访者），balance 会拟合一个权重，这个权重可以粗略地理解为该受访者所代表的目标总体中的人数。其目的是帮助缓解覆盖偏差和无响应偏差，如图所示。

通过 balance 对调查数据进行加权的主要步骤如下：

1. 加载调查受访者的数据。
2. 加载我们希望校正的目标总体的相关数据。
3. 对样本协变量进行诊断，以评估是否需要进行加权。
4. 将样本调整至目标总体。
5. 评估结果。
6. 使用权重生成总体层面的估计值。
7. 保存输出的权重。

您可以在 通用框架 页面中找到上述步骤的逐步描述（附带代码）。

使用 balance 的代码示例

你可以运行以下代码来体验 balance 的基本工作流程（这些片段摘自 快速入门教程）：

首先，我们加载数据并进行调整：

from balance import load_data, Sample

# 加载模拟示例数据
target_df, sample_df = load_data()

# 将样本和目标数据导入 Sample 对象
sample = Sample.from_frame(sample_df, outcome_columns=["happiness"])
target = Sample.from_frame(target_df)

# 设置目标为样本的目标
sample_with_target = sample.set_target(target)

# 在调整之前检查样本与目标的基本诊断：
# sample_with_target.covars().plot()

你可以在 预调整诊断 页面中了解更多关于预调整数据评估的信息。

接下来，我们通过拟合平衡抽样权重将样本调整到总体：

# 使用 ipw 拟合抽样权重
adjusted = sample_with_target.adjust()

你可以在 将样本调整到总体 页面中了解更多关于调整过程的信息。

上述代码会生成一个带有权重的 adjusted 对象。我们可以评估权重对协变量平衡的好处，例如通过运行：

print(adjusted.summary())
    # 协变量 ASMD 降低：62.3%，设计效应：2.249
    # 协变量 ASMD（7 个变量）：0.335 -> 0.126
    # 模型性能：模型解释的偏差比例：0.174

adjusted.covars().plot(library = "seaborn", dist_type = "kde")

得到如下结果：

我们还可以通过以下方式检查权重对结果的影响：

# 对于结果：
print(adjusted.outcomes().summary())
    # 1 个结果：['happiness']
    # 平均结果：
    #             happiness
    # source
    # self        54.221388
    # unadjusted  48.392784
    #
    # 回应率（相对于样本中的受访者数量）：
    #    happiness
    # n     1000.0
    # %      100.0
adjusted.outcomes().plot()

你可以在 评估和使用调整权重 页面中了解更多关于调整后数据评估的信息。

最后，可以使用以下代码下载调整后的数据：

adjusted.to_download()  # 或者：
# adjusted.to_csv()

若想查看更详细的分步代码示例，包括代码输出打印和图表（静态及交互式），请前往 教程部分。

已实现的调整方法

balance 目前实现了多种调整方法。点击链接以了解每种方法的详细信息：

1. 使用 L1（LASSO）惩罚的逻辑回归。
2. 协变量平衡倾向得分（CBPS）。
3. 事后分层。
4. 拉格法。

已实现的诊断/评估方法

在诊断方面，主要工具（比较应用权重前后以及与目标总体的情况）包括：

1. 图表
   1. 条形图
   2. 密度图（用于权重和协变量）
   3. QQ 图
2. 统计摘要
   1. 偏差分布
      1. 基什设计效应
      2. 主要汇总统计（均值、中位数、方差、分位数）
   2. 协变量分布
      1. 绝对标准化均值差异（ASMD）。对于连续变量，它等同于 Cohen's d。分类变量会进行独热编码，针对每个类别计算 Cohen's d，而分类变量的 ASMD 定义为所有类别 Cohen's d 的平均值。

你可以在 评估和使用调整权重 页面中了解更多关于调整后数据评估的信息。

其他资源

• 演示文稿： "使用 'balance' Python 包平衡有偏数据样本" - 于 2023 年 6 月 1 日在以色列统计协会 (ISA) 大会上发表。

更多详情

获取帮助、提交错误报告和贡献代码

欢迎你：

• 访问 balance 官网了解更多。
• 在以下链接寻求帮助： https://github.com/facebookresearch/balance/issues/new?template=support_question.md
• 在以下链接提交错误报告和功能建议： https://github.com/facebookresearch/balance/issues
• 向 https://github.com/facebookresearch/balance 提交拉取请求。请参阅 CONTRIBUTING 文件以了解如何参与贡献。同时，请参考我们的 行为准则，了解我们对贡献者的期望。

引用 balance

Sarig, T., Galili, T., & Eilat, R. (2023). balance – 用于平衡有偏数据样本的 Python 包。 https://arxiv.org/abs/2307.06024

@misc{sarig2023balance,
      title={balance - 用于平衡有偏数据样本的 Python 包},
      author={Tal Sarig 和 Tal Galili 以及 Roee Eilat},
      year={2023},
      eprint={2307.06024},
      archivePrefix={arXiv},
      primaryClass={stat.CO}
}

许可证

balance 软件包采用 MIT 许可证 许可，网站上的所有文档（包括文字和图片）则采用 CC-BY 许可。

新闻

你可以关注我们的：

• 博客
• 变更日志

致谢 / 参与人员

balance 包由来自 中央应用科学 团队（位于门洛帕克和特拉维夫）的以下人员积极维护：Wesley Lee、Tal Sarig 和 Tal Galili。

balance 包的开发曾由并仍在由多位同事共同完成，其中包括：Roee Eilat、Tal Galili、Daniel Haimovich、Kevin Liou、Steve Mandala、Adam Obeng（Meta 内部初始版本的作者）、Tal Sarig、Luke Sonnet、Sean Taylor、Barak Yair Reif、Soumyadip Sarkar 等。如果您过去曾参与 balance 的相关工作，请发送邮件至我们，以便将您的名字加入此列表。

balance 包于 2022 年底由 Tal Sarig、Tal Galili 和 Steve Mandala 共同开源。

品牌设计由 Meta AI 设计与市场团队的 Dana Beaty 完成。有关徽标文件，请参阅此处。

balance 快速上手指南

balance 是一个 Python 包，旨在帮助研究人员和数据科学家处理有偏数据样本（biased data samples）。它通过利用辅助信息（协变量）为样本拟合权重，从而将样本调整至目标总体分布，有效缓解调查统计、观察性研究中的无响应偏差和选择偏差。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS, 或 Windows。
• Python 版本：需要 Python 3.9 至 3.14 之间的版本。
• 核心依赖：安装时会自动解决以下主要依赖库的版本兼容性问题：
  • numpy, pandas
  • scipy, scikit-learn
  • statsmodels, seaborn, matplotlib, plotly
  • patsy, ipython

注意：该工具目前处于 Beta 阶段，但正在积极维护中。

安装步骤

推荐使用 pip 从 PyPI 安装最新稳定版本。国内用户若遇到下载速度慢的问题，可指定清华或阿里镜像源。

方式一：通过 PyPI 安装（推荐）

# 使用默认源
python -m pip install balance

# 或使用国内镜像源加速（推荐中国开发者使用）
python -m pip install balance -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装（获取最新开发版）

如果您需要体验最新的功能（bleeding edge），可以直接从 GitHub 安装：

python -m pip install git+https://github.com/facebookresearch/balance.git

或者克隆仓库后本地安装：

git clone https://github.com/facebookresearch/balance.git
cd balance
python -m pip install .

基本使用

balance 的核心工作流包括：加载数据 -> 定义样本与目标总体 -> 诊断偏差 -> 拟合权重 -> 评估结果。

以下是最简化的代码示例，演示如何加载模拟数据并执行加权调整：

1. 加载数据并初始化

首先导入必要的模块，加载示例数据，并将数据封装为 Sample 对象。

from balance import load_data, Sample

# 加载模拟示例数据 (target_df 为目标总体，sample_df 为有偏样本)
target_df, sample_df = load_data()

# 将 DataFrame 转换为 Sample 对象
# outcome_columns 指定需要分析的结果变量（如幸福感）
sample = Sample.from_frame(sample_df, outcome_columns=["happiness"])
target = Sample.from_frame(target_df)

# 将目标总体设定为样本的调整目标
sample_with_target = sample.set_target(target)

# (可选) 查看调整前的协变量诊断图
# sample_with_target.covars().plot()

2. 执行加权调整

使用默认的逆概率加权（IPW）方法拟合权重，将样本调整至与目标总体一致。

# 拟合平衡权重
adjusted = sample_with_target.adjust()

3. 评估结果

调整完成后，可以查看摘要统计信息以确认偏差是否降低（如 ASMD 减少比例），并可视化协变量分布。

# 打印调整摘要
print(adjusted.summary())
# 输出示例:
# Covar ASMD reduction: 62.3%, design effect: 2.249
# Covar ASMD (7 variables):0.335 -> 0.126

# 可视化调整后的协变量分布 (使用 seaborn)
adjusted.covars().plot(library="seaborn", dist_type="kde")

4. 分析结果变量与导出

检查权重对结果变量（如 happiness）均值的影响，并导出带有权重的数据。

# 查看结果变量的汇总统计
print(adjusted.outcomes().summary())

# 可视化结果变量分布
adjusted.outcomes().plot()

# 导出数据（包含计算出的权重）
adjusted.to_csv("balanced_data.csv") 
# 或者获取下载链接
# adjusted.to_download()

通过以上步骤，您即可完成从有偏样本到平衡样本的完整处理流程。更多高级用法（如使用 CBPS、事后分层等方法）请参考官方文档教程部分。