crepes 是一个用于共形预测的 Python 包，它可以在任何标准分类器和回归器之上实现共形分类器、回归器以及预测系统，从而将原始预测转化为校准良好的 p 值和累积分布函数，或具有覆盖率保证的预测集和预测区间。

crepes 包实现了标准和蒙德里安共形分类器，以及标准、归一化和蒙德里安共形回归器和预测系统。虽然该包允许用户使用自己的函数来计算难度估计、非一致性分数和蒙德里安类别，但还有一个名为 crepes.extras 的独立模块，提供了这些方面的若干标准选项。为了检验交换性的基本假设，可以使用 crepes.martingales 模块中的类。

安装

从 PyPI：

pip install crepes

从 conda-forge：

conda install conda-forge::crepes

文档

完整的文档请参阅 crepes.readthedocs.io。

快速入门

让我们以来自 www.openml.org 的数据集为例，说明如何使用 crepes 生成并应用共形分类器。我们首先使用 sklearn 中的 train_test_split 将数据集划分为训练集和测试集，然后进一步将训练集划分为正式训练集和校准集：

from sklearn.datasets import fetch_openml
from sklearn.model_selection import train_test_split

dataset = fetch_openml(name="qsar-biodeg", parser="auto")

X = dataset.data.values.astype(float)
y = dataset.target.values

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.5)

X_prop_train, X_cal, y_prop_train, y_cal = train_test_split(X_train, y_train,
                                                            test_size=0.25)

现在我们将随机森林分类器“包装”起来，将其拟合到正式训练集，并通过 calibrate 方法拟合一个标准共形分类器：

from crepes import WrapClassifier
from sklearn.ensemble import RandomForestClassifier

rf = WrapClassifier(RandomForestClassifier(n_jobs=-1))

rf.fit(X_prop_train, y_prop_train)

rf.calibrate(X_cal, y_cal)

接下来，我们可以为测试集生成 p 值（一个列数等于类别数的数组）：

rf.predict_p(X_test)

array([[0.00427104, 0.74842304],
       [0.07874355, 0.2950549 ],
       [0.50529983, 0.01557963],
       ...,
       [0.8413356 , 0.00201167],
       [0.84402215, 0.00654927],
       [0.29601955, 0.07766093]])

我们还可以得到预测集，用二进制向量表示，其中 1 表示存在、0 表示不存在与列对应的类标签，在这里置信度为 90%：

rf.predict_set(X_test, confidence=0.9)

array([[0, 1],
       [0, 1],
       [1, 0],
       ...,
       [1, 0],
       [1, 0],
       [1, 0]])

由于我们掌握了真实的类标签，因此可以在 99% 的置信度下评估共形分类器（此处使用所有可用指标，这是默认设置）：

rf.evaluate(X_test, y_test, confidence=0.99)

{'error': 0.007575757575757569,
 'avg_c': 1.6325757575757576,
 'one_c': 0.36742424242424243,
 'empty': 0.0,
 'ks_test': 0.0033578466103315894,
 'time_fit': 1.9073486328125e-06,
 'time_evaluate': 0.04798746109008789}

为了控制不同目标群体中的错误率，可以使用所谓的蒙德里安共形分类器。蒙德里安共形分类器是通过在 calibrate 方法中提供一个函数或 MondrianCategorizer（定义在 crepes.extras 中），作为名为 mc 的额外参数来构建的。

为了说明，我们将使用底层模型的预测标签来形成类别。请注意，测试对象的预测集是基于相同的分类方式生成的（在后台进行）。

rf_mond = WrapClassifier(rf.learner)

rf_mond.calibrate(X_cal, y_cal, mc=rf_mond.predict)

rf_mond.predict_set(X_test)

array([[0, 1],
       [1, 1],
       [1, 0],
       ...,
       [1, 0],
       [1, 0],
       [1, 1]])

条件类共形分类器是蒙德里安共形分类器的一种特殊类型，其类别由真实标签构成；我们可以通过在调用 calibrate 时设置 class_cond=True 来生成一个。

rf_classcond = WrapClassifier(rf.learner)

rf_classcond.calibrate(X_cal, y_cal, class_cond=True)

rf_classcond.evaluate(X_test, y_test, confidence=0.99)

{'error': 0.0018939393939394478,
 'avg_c': 1.740530303030303,
 'one_c': 0.25946969696969696,
 'empty': 0.0,
 'ks_test': 0.11458837583733483,
 'time_fit': 7.152557373046875e-07,
 'time_evaluate': 0.06147575378417969}

当使用归纳式共形预测器时，测试集上的预测 p 值（以及由此产生的误差）并不相互独立。然而，半在线共形预测器可以通过在每次预测后立即更新校准集来使它们相互独立（假设此时已知真实标签）。我们可以通过启用在线校准，即在调用上述方法时设置 online=True，同时提供真实标签，将共形分类器转变为半在线共形分类器，例如：

rf_classcond.predict_p(X_test, y_test, online=True)

array([[8.13837566e-05, 8.86436603e-01],
       [6.60518590e-02, 4.02350293e-01],
       [4.28646783e-01, 4.29930890e-02],
       ...,
       [7.05118942e-01, 9.45056960e-03],
       [7.27003479e-01, 1.27347189e-02],
       [1.76403756e-01, 1.21434924e-01]])

同样地，我们也可以在使用在线校准的情况下评估共形分类器：

rf_classcond.evaluate(X_test, y_test, confidence=0.99, online=True)

{'error': 0.007575757575757569,
 'avg_c': 1.6117424242424243,
 'one_c': 0.38825757575757575,
 'empty': 0.0,
 'ks_test': 0.14097384777782784,
 'time_fit': 1.9073486328125e-06,
 'time_evaluate': 0.05298352241516113}

我们还可以说明如何使用 crepes 来生成共形回归模型和预测系统。再次从 www.openml.org 导入数据集，将其分为训练集和测试集，然后将训练集进一步划分为正式训练集和校准集：

from sklearn.datasets import fetch_openml
from sklearn.model_selection import train_test_split

dataset = fetch_openml(name="house_sales", version=3, parser="auto")

X = dataset.data.values.astype(float)
y = dataset.target.values.astype(float)

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.5)
X_prop_train, X_cal, y_prop_train, y_cal = train_test_split(X_train, y_train,
                                                            test_size=0.25)

现在，我们使用 crepes 中的 WrapRegressor 类“包装”来自 sklearn 的 RandomForestRegressor，并按照常规方式将其拟合到正式训练集：

from sklearn.ensemble import RandomForestRegressor
from crepes import WrapRegressor

rf = WrapRegressor(RandomForestRegressor())
rf.fit(X_prop_train, y_prop_train)

接下来，我们可以通过 calibrate 方法利用校准集来拟合共形回归模型：

rf.calibrate(X_cal, y_cal)

此时，共形回归模型可以为测试集生成预测区间，这里我们使用 99% 的置信水平：

rf.predict_int(X_test, confidence=0.99)

array([[1938866.06, 3146372.54],
       [ 225335.1 , 1432841.58],
       [-403305.49,  804200.99],
       ...,
       [ 443742.33, 1651248.81],
       [-343684.48,  863822.  ],
       [-153629.93, 1053876.55]])

输出是一个 NumPy 数组，每一行对应一个测试样本，两列分别表示每个预测区间的下界和上界。

我们可以要求对区间进行裁剪，以排除不可能的值，在本例中即低于 0 的值；如果同时采用默认的置信水平（0.95），则输出的区间会更加紧凑：

rf.predict_int(X_test, y_min=0)

array([[2302049.84, 2783188.76],
       [ 588518.88, 1069657.8 ],
       [      0.  ,  441017.21],
       ...,
       [ 806926.11, 1288065.03],
       [  19499.3 ,  500638.22],
       [ 209553.85,  690692.77]])

上述区间并未归一化，也就是说它们的大小都相同（至少在裁剪之前是如此）。我们可以通过使用难度估计来进行归一化，从而使区间更具信息量：被认为更难的对象将被分配到更宽的区间。

为此，我们将使用 crepes.extras 模块中的 DifficultyEstimator。在这里，我们通过计算校准集中每个对象在其正式训练集中 k 个（默认 k=25）最近邻的标签标准差来估计难度。此外，还会向估计值添加一个小的常数 β，该参数可通过函数参数指定；下面我们直接使用默认值，即 β=0.01。

首先拟合难度估计器，然后结合校准对象及其标签以及难度估计器来校准共形回归模型：

from crepes.extras import DifficultyEstimator

de = DifficultyEstimator()
de.fit(X_prop_train, y=y_prop_train)

rf.calibrate(X_cal, y_cal, de=de)

要获得预测区间，只需将测试对象传递给 predict_int 方法即可，因为难度估计将由内置的难度估计器自动计算：

rf.predict_int(X_test, y_min=0)

array([[1769594.36212355, 3315644.23787645],
       [ 693827.99796647,  964348.68203353],
       [ 124886.97469338,  276008.52530662],
       ...,
       [ 661373.45043166, 1433617.68956833],
       [ 178769.2939384 ,  341368.2260616 ],
       [ 222837.12801117,  677409.49198883]])

根据所使用的难度估计器，归一化的区间有时可能会大得不合理，甚至可能是先前观察到的最大误差的数倍。此外，如果难度估计器毫无信息量，例如完全随机，则不同大小的区间可能会给人造成一种错觉，即认为具有较窄区间的情况其预测误差会更低。理想情况下，对于那些几乎无法提供有关预期误差信息的难度估计器，应该导致区间大小更加均匀分布。

Mondrian 共形回归模型可以用来解决这些问题，它通过将对象空间划分为互不重叠的所谓 Mondrian 类别，并为每个类别构建一个（标准）共形回归模型。我们可以通过在 calibrate 方法中提供一个函数或 MondrianCategorizer（定义在 crepes.extras 中），作为名为 mc 的额外参数，来构建 Mondrian 共形回归模型。

这里我们使用 MondrianCategorizer；它可以以多种方式拟合，下面展示的是如何利用上面拟合的难度估计器，将难度估计值分成 20 个桶来形成类别。

from crepes.extras import MondrianCategorizer

mc_diff = MondrianCategorizer()
mc_diff.fit(X_cal, de=de, no_bins=20)

rf.calibrate(X_cal, y_cal, mc=mc_diff)

在进行预测时，测试对象将根据内置的 MondrianCategorizer（或标注函数）被分配到相应的 Mondrian 类别：

rf.predict_int(X_test, y_min=0)

array([[1152528.9 , 3932709.7 ],
       [ 692366.75,  965809.93],
       [ 124254.81,  276640.69],
       ...,
       [ 622939.57, 1472051.57],
       [ 155346.82,  364790.7 ],
       [ 239474.31,  660772.31]])

与半在线共形分类器类似，我们也可以为共形回归模型启用在线校准；这同样是通过在调用相关方法时设置 online=True 来实现的，同时还需要提供真实的标签，例如：

rf.predict_p(X_test, y_test, online=True)

array([0.09369225, 0.52548032, 0.49992477, ..., 0.72979714, 0.87495964,
       0.58352253])

我们可以很容易地从共形回归器切换到共形预测系统。后者会生成累积分布函数（共形预测分布）。基于这些分布，我们不仅可以生成预测区间，还可以得到分位数、校准后的点预测以及针对给定目标值的 p 值。接下来我们就来看看如何实现这一点。

其实只需要在 calibrate 方法中添加一个参数：将 cps=True 传入即可。

例如，我们可以通过向 calibrate 方法同时提供 Mondrian 分类器和难度估计器，来构建归一化的 Mondrian 共形预测系统。这里我们将考虑根据点预测结果进行分箱后形成的 Mondrian 类别：

mc_pred = MondrianCategorizer()
mc_pred.fit(X_cal, f=rf.predict, no_bins=5)

rf.calibrate(X_cal, y_cal, de=de, mc=mc_pred, cps=True)

现在我们可以使用共形预测系统进行预测，方法有多种，比如 predict_percentiles：

rf.predict_percentiles(X_test, higher_percentiles=[90, 95, 99])

array([[3120432.14791764, 3403976.16608241, 3952384.13595105],
       [ 930191.36994287,  979804.59585495, 1075762.49571536],
       [ 236278.82580469,  253387.66592079,  329933.49293406],
       ...,
       [1336110.21956702, 1477739.04927264, 1751666.10820498],
       [ 298621.13482031,  317029.35735016,  399388.68783836],
       [ 564574.75363948,  615226.06727944,  762212.9912238 ]])

与半在线共形分类器和回归器类似，我们也可以为共形预测系统启用在线校准；这里我们以默认的 95% 置信水平生成预测区间：

rf.predict_int(X_test, y_test, y_min=0, online=True)

array([[1719676.80439219, 3707173.76806116],
       [ 684289.27240227, 1032856.71531186],
       [ 127189.61835749,  274385.59426486],
       ...,
       [ 630347.70469164, 1594876.58130005],
       [ 167399.51044545,  337513.60197203],
       [ 232815.51352497,  641580.14787679]])

我们还可以为每个测试样本获取完整的共形预测分布，其由阈值定义：

rf.predict_cpds(X_test)

对于 Mondrian 共形预测系统（或任何半在线共形预测系统），输出是一个包含每个测试样本对应 CPD 的向量；而对于标准或归一化的共形预测系统（未启用在线校准），输出则是一个二维数组。

此处未展示最终的向量嵌套向量结构，而是给出了一个随机测试样本的 CPD 图：

此外，我们还可以利用共形检验鞅来检验交换性假设。假设我们已经通过半在线共形预测器获得了 p 值，例如：

p_values = rf.predict_p(X_test, y_test, online=True)

现在我们可以使用 crepes.martingales 模块中的任意共形检验鞅算法，来检验这些 p 值是否独立且均匀地分布在 [0, 1] 区间内。如果交换性假设成立，则观察到鞅值超过 c 的概率不超过 1/c。这意味着错误拒绝该假设的概率被限制在 1/c 以内。下面演示如何使用 Simple Jumper 为上述 p 值计算鞅值：

from crepes.martingales import SimpleJumper

martingale_values = SimpleJumper().apply(p_values)

我们还可以查询使鞅值超过指定阈值的最小索引：

SimpleJumper().apply(np.sort(p_values), c=100)

由于在上述示例中 p 值已排序，共形检验鞅会较早检测到交换性假设的违反，并返回较低的索引。而如果提供的是原始（未排序）p 值，则共形检验鞅很可能无法检测到任何数据漂移，只会返回 p 值向量的长度。

示例

有关如何使用本包和模块的更多示例，请参阅 文档、使用 WrapClassifier 和 WrapRegressor 的 Jupyter 笔记本、使用 ConformalClassifier、ConformalRegressor 和 ConformalPredictiveSystem 的 Jupyter 笔记本，以及 关于共形检验鞅使用的 Jupyter 笔记本。

您也可以查看我在 COPA 2024 大会上的教程幻灯片及其配套的 Jupyter 笔记本：

COPA 2024 教程幻灯片 和 COPA 2024 教程笔记本。

引用 crepes

欢迎您引用以下论文：

Boström, H. 2024. 使用 crepes 在 Python 中进行共形预测。第 13 届共形与概率预测应用研讨会论文集，PMLR 230:236–249 链接

BibTeX 条目：

@inproceedings{bostrom2024,
  title={使用 crepes 在 Python 中进行共形预测},
  author={Bostr{\"o}m, Henrik},
  booktitle={第 13 届共形与概率预测应用研讨会论文集},
  pages={236--249},
  year={2024},
  organization={PMLR}
}

该软件包的早期版本曾在以下文献中介绍：

Boström, H., 2022. crepes：用于生成共形回归器和预测系统的 Python 软件包。第 11 届共形与概率预测应用研讨会论文集，PMLR 179:24–41 链接

BibTeX 条目：

@inproceedings{bostrom2022,
  title={crepes：用于生成共形回归器和预测系统的 Python 软件包},
  author={Bostr{\"o}m, Henrik},
  booktitle={第 11 届共形与概率预测应用研讨会论文集},
  pages={24--41},
  year={2022},
  organization={PMLR}
}

参考文献

[1] Vovk, V., Gammerman, A. 和 Shafer, G.，2022年。随机世界中的算法学习。第二版。施普林格出版社 链接

[2] Papadopoulos, H., Proedrou, K., Vovk, V. 和 Gammerman, A.，2002年。回归的归纳置信机。欧洲机器学习会议，第345–356页。链接

[3] Johansson, U., Boström, H., Löfström, T. 和 Linusson, H.，2014年。基于随机森林的回归共形预测。机器学习，97(1–2)，第155–176页。链接

[4] Boström, H., Linusson, H., Löfström, T. 和 Johansson, U.，2017年。加速共形回归森林的难度估计。数学与人工智能年鉴，81(1–2)，第125–144页。链接

[5] Boström, H. 和 Johansson, U.，2020年。蒙德里安共形回归器。载于《共形与概率预测及其应用》。PMLR，第128卷，第114–133页。链接

[6] Vovk, V., Petej, I., Nouretdinov, I., Manokhin, V. 和 Gammerman, A.，2020年。共形预测分布的高效计算版本。神经计算，第397期，第292–308页。链接

[7] Boström, H., Johansson, U. 和 Löfström, T.，2021年。蒙德里安共形预测分布。载于《共形与概率预测及其应用》。PMLR，第152卷，第24–38页。链接

[8] Vovk, V.，2022年。通用预测系统。模式识别，第126卷：第108536页。链接

---

作者：亨里克·博斯特伦（bostromh@kth.se） 版权所有 2025年 亨里克·博斯特伦 许可证：BSD 3条款

crepes 快速上手指南

crepes 是一个用于**共形预测（Conformal Prediction）**的 Python 库。它可以将任何标准的分类器或回归器包装起来，生成具有覆盖率保证的校准 P 值、累积分布函数、预测集或预测区间。

环境准备

• 操作系统: Windows, macOS, Linux
• Python 版本: 建议 Python 3.8 及以上
• 核心依赖:
  • numpy
  • scikit-learn (用于数据划分和基础模型)
  • scipy (部分统计功能)

注意：安装 crepes 时，上述依赖通常会自动安装。请确保已配置好基础的 Python 开发环境。

安装步骤

你可以选择通过 PyPI 或 conda-forge 进行安装。国内用户若遇到网络问题，可配置清华或阿里镜像源。

方式一：使用 pip 安装（推荐）

pip install crepes

国内加速安装（使用清华源）：

pip install crepes -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 conda 安装

conda install conda-forge::crepes

基本使用

以下示例展示如何使用 crepes 构建一个标准的共形分类器。流程分为三步：数据划分 -> 模型训练与校准 -> 生成预测集。

1. 数据准备与划分

共形预测需要将数据划分为三个部分：训练集（训练基础模型）、校准集（计算非一致性分数）和测试集。

from sklearn.datasets import fetch_openml
from sklearn.model_selection import train_test_split

# 加载示例数据集
dataset = fetch_openml(name="qsar-biodeg", parser="auto")
X = dataset.data.values.astype(float)
y = dataset.target.values

# 第一步：划分为训练集和测试集
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.5)

# 第二步：将训练集进一步划分为“真实训练集”和“校准集”
X_prop_train, X_cal, y_prop_train, y_cal = train_test_split(X_train, y_train,
                                                            test_size=0.25)

2. 包装模型并校准

使用 WrapClassifier 包装任意 sklearn 分类器（此处为随机森林），先在真实训练集上拟合，再在校准集上进行校准。

from crepes import WrapClassifier
from sklearn.ensemble import RandomForestClassifier

# 包装随机森林分类器
rf = WrapClassifier(RandomForestClassifier(n_jobs=-1))

# 在真实训练集上训练基础模型
rf.fit(X_prop_train, y_prop_train)

# 在校准集上进行共形校准
rf.calibrate(X_cal, y_cal)

3. 生成预测结果

校准完成后，可以生成预测集（Prediction Sets）。以下代码生成置信度为 90% 的预测集，输出为二进制向量（1 表示包含该类，0 表示不包含）。

# 生成 90% 置信水平的预测集
prediction_sets = rf.predict_set(X_test, confidence=0.9)

print(prediction_sets[:5]) 
# 输出示例:
# array([[0, 1],
#        [0, 1],
#        [1, 0],
#        ...,
#        [1, 0],
#        [1, 0]])

你也可以直接获取校准后的 P 值：

p_values = rf.predict_p(X_test)
print(p_values[:2])
# 输出示例:
# array([[0.00427104, 0.74842304],
#        [0.07874355, 0.2950549 ]])

提示：crepes 同样支持回归任务（WrapRegressor）和更高级的 Mondrian 共形预测（针对不同类别或群体单独校准），具体用法可参考官方文档。