Cleanlab 内部模块 latent_algebra 解析噪声矩阵与潜在分布代数运算的数学内核【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab导读cleanlab.internal.latent_algebra是 Cleanlab 数据质量与置信学习Confident Learning管线中负责潜在分布代数运算的数学内核模块。它集中实现了一组将P(noisy label)、P(noisy label | true label)、P(true label | noisy label)、P(true label)等潜在项相互换算的精确闭式函数。阅读本文后你将理解噪声矩阵noise matrix与逆噪声矩阵inverse noise matrix的定义与互算原理、py_method四种潜在先验估计策略的取舍以及这些函数如何支撑 count.py 中的estimate_latent与 classification.py 中的 CleanLearning 等上游能力。一、模块定位精确闭式方程的计算等价物在 Cleanlab 的整体架构中latent_algebra属于cleanlab.internal内部模块完整模块索引见 docs/source/cleanlab/internal/index.rst。根据 latent_algebra.py 的模块级 docstring本模块遵循三条核心设计原则精确性保证对其中每一个函数只要输入是精确的输出就保证精确——每个函数都是一条具有闭式精确形式的数学方程的计算等价物误差传播如果输入不精确误差自然会随运算传播因此上游常配合裁剪、收敛等数值技巧统一记号全模块约定用K表示分类任务中的类别数。模块中的核心潜在项包括记号含义形状psP(labels k)观测到的含噪标签的类别先验fraction/prior(K,)或(1, K)pyP(true_labels k)潜在真实标签的类别先验(K,)或(1, K)noise_matrixP(labelk_s \| true_labelk_y)真实类别被误标为其他类别的比例(K, K)列和为 1inverse_noise_matrixP(true_labelk_y \| labelk_s)含噪类别中来自各类真实标签的比例(K, K)列和为 1pyxP(true_labelk \| x)给定样本x的真实类别后验(N, K)模块通过Tuple类型标注见 latent_algebra.py显式约束这些数组的形状任何形状不符的输入都会触发ValueError或UserWarning详见下文各函数。二、基础向量关系噪声矩阵与逆噪声矩阵为什么可以互算理解本模块的关键在于两条向量层面的恒等关系代码注释中反复出现见 latent_algebra.py 与 latent_algebra.py正向关系P(labelk | true_labelk) · p(true_labelk) P(labelk)即noise_matrix · py ps。因此给定py与noise_matrix可推出ps反向关系P(true_labelk | labelk) · p(labelk) P(true_labelk)即inverse_noise_matrix · ps py。因此给定ps与inverse_noise_matrix可推出py。这两条关系分别对应compute_inv_noise_matrix与compute_noise_matrix_from_inverse两个互逆函数也是_converge_estimatescount.py通过迭代迫使三个潜在估计在数值上自洽的理论依据。三、函数逐一详解模块共导出 6 个函数见 latent_algebra.py下文按从原始数据到潜在量的依赖顺序展开。3.1 compute_ps_py_inv_noise_matrix从含噪标签一步到位签名compute_ps_py_inv_noise_matrix(labels, noise_matrix) - (ps, py, inverse_noise_matrix)这是唯一一个直接接受原始标签向量作为输入的入口函数。它内部分两步完成latent_algebra.pyps value_counts(labels) / float(len(labels)) # p(labelsk) py, inverse_noise_matrix compute_py_inv_noise_matrix(ps, noise_matrix)输入约束latent_algebra.pylabels离散的含噪标签向量数据集有K类时标签必须取值于{0,1,...,K-1}noise_matrix形状(K, K)的条件概率矩阵假设列和为 1。ps的计算借助 util.py 中的value_counts它内部使用np.unique统计频次并支持num_classes参数为缺失类别补零。3.2 compute_py_inv_noise_matrix矩阵求逆求真实类别先验签名compute_py_inv_noise_matrix(ps, noise_matrix) - (py, inverse_noise_matrix)核心计算一行完成latent_algebra.pypy np.linalg.inv(noise_matrix).dot(ps)这是向量恒等式noise_matrix · py ps的矩阵求逆解法当noise_matrix不可逆时代码注释说明会退化为使用伪逆。随后执行两步数值处理裁剪为合法概率latent_algebra.py调用clip_values(py, lowCLIPPING_LOWER_BOUND, high1.0, new_sum1.0)保证没有类别概率为 0 且总和归一为 1.0计算逆噪声矩阵委托给compute_inv_noise_matrix。其中CLIPPING_LOWER_BOUND 1e-6见 constants.py注释明确No class should have probability 0, so we use .000001。3.3 compute_inv_noise_matrix由贝叶斯公式推导逆噪声矩阵签名compute_inv_noise_matrix(py, noise_matrix, *, psNone) - inverse_noise_matrix这是模块中最具教学价值的函数docstring 中给出了逐元素 for 循环版本latent_algebra.py直观展示其贝叶斯本质K len(py) # ps 是 p(labelsk) noise_matrix * p(true_labelsk) if ps is None: ps noise_matrix.dot(py) inverse_noise_matrix np.empty(shape(K, K)) for k_s in range(K): # k_s含噪标签 label k_s 的类别值 for k_y in range(K): # k_y猜测的真实标签 y 的类别值 # P(true_label|label) P(label|y) * P(true_label) / P(labels) inverse_noise_matrix[k_y][k_s] noise_matrix[k_s][k_y] * py[k_y] / ps[k_s]向量化实现latent_algebra.py等价但更高效joint noise_matrix * py # 联合分布 P(label, true_label) ps joint.sum(axis1) if ps is None else ps # 若未预计算 ps则从联合分布边缘化得到 inverse_noise_matrix joint.T / np.clip(ps, a_minTINY_VALUE, a_maxNone) return clip_noise_rates(inverse_noise_matrix)值得注意的工程细节ps之所以是可选关键字参数是因为它可以由py与noise_matrix快速推出若已预计算则传入以省去一次矩阵乘法latent_algebra.py除法分母用np.clip(ps, a_minTINY_VALUE, ...)保护其中TINY_VALUE 1e-100见 constants.py避免零除结果经过clip_noise_ratesutil.py将非对角噪声率裁剪到[0, 1)先保留对角线对角项不是噪声率而是P(labelk|true_labelk)的一致性概率将非对角元素np.clip到[0, 0.9999]再按列归一化使列和为 1。3.4 compute_noise_matrix_from_inverse逆运算还原噪声矩阵签名compute_noise_matrix_from_inverse(ps, inverse_noise_matrix, *, pyNone) - noise_matrix它是 3.3 的逆变换基于反向恒等式P(labels|y) P(true_label|labels) · P(labels) / P(true_label)。for 循环版本latent_algebra.pyK len(ps) # py 是 p(true_labelk) inverse_noise_matrix * p(labelk) if py is None: py inverse_noise_matrix.dot(ps) noise_matrix np.empty(shape(K, K)) for k_s in range(K): for k_y in range(K): # P(labels|y) P(true_label|labels) * P(labels) / P(true_label) noise_matrix[k_s][k_y] inverse_noise_matrix[k_y][k_s] * ps[k_s] / py[k_y]向量化实现latent_algebra.pyjoint (inverse_noise_matrix * ps).T py joint.sum(axis0) if py is None else py noise_matrix joint / np.clip(py, a_minTINY_VALUE, a_maxNone) return clip_noise_rates(noise_matrix)返回的noise_matrix列和为 1代表每个真实类别被标成其他类别的比例。3.5 compute_py四种策略估计真实类别先验核心差异所在签名compute_py(ps, noise_matrix, inverse_noise_matrix, *, py_methodcnt, true_labels_class_countsNone) - py这是模块中策略选项最丰富的函数。py_method提供四种取值latent_algebra.py默认cnt因为它在噪声矩阵估计不佳时依然稳健——它只依赖矩阵对角线而非全部概率而对角线通常最容易估准。四种方法的具体计算latent_algebra.pypy_method公式特点cnt默认py inverse_noise_matrix.diagonal() / clip(noise_matrix.diagonal()) * ps只用对角项最稳健等价于(true_labels_class_counts / labels_class_counts) * ps天然避免除以零噪声率eqnpy np.linalg.inv(noise_matrix).dot(ps)直接矩阵求逆精确但噪声敏感marginalpy true_labels_class_counts / sum(true_labels_class_counts)由 confident joint 的列边缘计数直接归一化必须传入true_labels_class_counts否则抛出ValueErrorlatent_algebra.pymarginal_pspy np.dot(inverse_noise_matrix, ps)用逆噪声矩阵作用于ps输入校验与兜底latent_algebra.py若ps形状既非(K,)也非(1, K)如(3,1,1)或(K,1)会发出UserWarning提示shape should be (K, ) or (1, K)若py_method不在四者之列抛出ValueError错误信息明确列出合法取值[cnt, eqn, marginal, marginal_ps]无论哪种方法最后统一经过clip_values(py, lowCLIPPING_LOWER_BOUND, high1.0, new_sum1.0)裁剪归一latent_algebra.py。3.6 compute_pyx逐样本修正预测概率签名compute_pyx(pred_probs, noise_matrix, inverse_noise_matrix) - pyx该函数将模型输出的含噪预测pred_probs : P(labelk|x)修正为真实标签后验pyx : P(true_labelk|x)同样采用对角项稳健策略latent_algebra.pypyx ( pred_probs * inverse_noise_matrix.diagonal() / np.clip(noise_matrix.diagonal(), a_minTINY_VALUE, a_maxNone) ) return np.apply_along_axis( func1dclip_values, axis1, arrpyx, **{low: 0.0, high: 1.0, new_sum: 1.0} )约束与校验pred_probs必须是(N, K)的二维数组否则抛出ValueErrorlatent_algebra.py错误信息包含 but shape should be (N, K)列顺序必须对应类别 0,1,2,...文档要求pred_probs应使用 3 折或更高折数的交叉验证计算防止过拟合导致概率失真输出逐行调用clip_values归一化为和 1 的合法概率分布。四、数值安全的三个基石latent_algebra的数值稳健性依赖 util.py 与 constants.py 中的三个基础工具clip_noise_rates(noise_matrix)util.py假设列和为 1将对角线一致性概率与噪声率区别对待——噪声率裁剪到[0, 0.9999]对角线原样保留最后整体按列重新归一化clip_values(x, low, high, new_sum)util.py裁剪到[low, high]后按比例重缩放以保持总和默认保持原和也可用new_sum指定新和如归一化到 1.0对多维输入会抛出TypeError常量TINY_VALUE 1e-100用于除法分母下界保护CLIPPING_LOWER_BOUND 1e-6用于概率下界裁剪constants.py。五、在上游管线中的实际调用latent_algebra不是孤立模块它是 Cleanlab 潜在量估计的计算底座。5.1 count.pyestimate_latent 与 _converge_estimatescount.py 从latent_algebra导入compute_py、compute_inv_noise_matrix、compute_noise_matrix_from_inverse等函数。核心消费者是estimate_latentcount.py它从confident_joint出发按如下步骤组装潜在量用value_counts_fill_missing_classes得到pscount.py由confident_joint的行/列和分别归一化得到noise_matrix与inv_noise_matrixcount.py调用compute_py(ps, noise_matrix, inv_noise_matrix, py_methodpy_method, true_labels_class_counts...)求真实类别先验count.py若converge_latent_estimatesTrue调用_converge_estimates迭代使三者数值自洽count.py。_converge_estimatescount.py是模块互逆性质最精彩的落地外层noise_matrix_iterations3次、内层inv_noise_matrix_iterations5次的嵌套循环中反复执行compute_inv_noise_matrix→compute_py→compute_noise_matrix_from_inverse。docstring 特别提醒迭代次数不宜过高3–10 次足够否则小的偏差会被反复放大且必须先收敛inverse_noise_matrix与py因为逆噪声矩阵依赖潜在量py噪声矩阵依赖已知量ps故最后更新。estimate_latent又被estimate_py_and_noise_matrices_from_probabilitiescount.py与 classification.py 中的 CleanLearning 等更高层 API 调用构成从含噪标签 交叉验证概率到潜在分布估计的完整链路。5.2 classification.pyCleanLearning 中的使用classification.py 导入compute_py_inv_noise_matrix在拟合流程中classification.py据此得到py与逆噪声矩阵供后续噪声率校准使用。六、测试验证数学性质的可复现保证tests/test_latent_algebra.py 用一组紧凑的用例验证了模块的数学正确性核心测试数据tests/test_latent_algebra.pys [0] * 10 [1] * 5 [2] * 15 nm np.array([[1.0, 0.0, 0.2], [0.0, 0.7, 0.2], [0.0, 0.3, 0.6]])关键断言包括互逆性compute_ps_py_inv_noise_matrix的结果满足np.dot(inv, ps) ≈ py且np.dot(nm, py) ≈ ps误差 1e-3tests/test_latent_algebra.py即验证两条向量恒等式正逆一致compute_inv_noise_matrix(py, nm)与compute_noise_matrix_from_inverse(ps, inv, pypy)都能还原出原始矩阵tests/test_latent_algebra.py异常路径compute_py对非法ps形状发出UserWarning、对缺失true_labels_class_counts的marginal模式抛出ValueErrortests/test_latent_algebra.py、tests/test_latent_algebra.pypyx 归一性compute_pyx输出每行和与 1 的偏差 1e-4且对一维pred_probs输入抛出包含 should be (N, K) 的ValueErrortests/test_latent_algebra.py。这些测试以极小代价覆盖了精确输入 → 精确输出的核心承诺是理解函数边界条件的最佳入口。七、使用建议与限制何时直接调用本模块通常你不需要直接使用latent_algebra而是通过cleanlab.count.estimate_latent、estimate_py_and_noise_matrices_from_probabilities或 CleanLearning 间接受益本模块面向需要自行实现置信学习算法的进阶用户多标签支持estimate_latent明确声明不支持多标签分类count.pylatent_algebra的矩阵公式同样针对单标签多分类设计输入前提所有noise_matrix/inverse_noise_matrix输入都假设列和为 1传入前需确认pred_probs务必来自交叉验证以避免过拟合latent_algebra.py数值建议py_method优先选择默认cnt仅在对矩阵整体估计有信心时尝试eqn启用converge_latent_estimates时保持默认迭代次数即可。综上latent_algebra以不到 400 行代码将置信学习所需的全部潜在分布代数运算封装为精确、可逆、数值安全的函数集合是理解 Cleanlab 从含噪标签中恢复真实分布原理的必读模块。【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考