.. _developers-utils: ======================== 开发者工具 ======================== Scikit-learn 包含一些帮助开发的工具。这些工具位于 :mod:`sklearn.utils` 中，包括多个类别的工具。以下所有函数和类都在 :mod:`sklearn.utils` 模块中。 .. warning :: 这些工具旨在在 scikit-learn 包内部使用。它们不能保证在不同版本的 scikit-learn 之间保持稳定。特别是回溯功能，随着 scikit-learn 依赖项的演变，将会被移除。 .. currentmodule:: sklearn.utils 验证工具 ================ 这些工具用于检查和验证输入。当你编写一个接受数组、矩阵或稀疏矩阵作为参数的函数时，应根据需要使用以下工具。 - :func:`assert_all_finite` : 如果数组包含 NaN 或 Inf，则抛出错误。 - :func:`as_float_array` : 将输入转换为浮点数数组。如果传递稀疏矩阵，则返回稀疏矩阵。 - :func:`check_array` : 检查输入是否为 2D 数组，对稀疏矩阵引发错误。可以选择允许的稀疏矩阵格式，以及允许 1D 或 N 维数组。默认调用 :func:`assert_all_finite` 。 - :func:`check_X_y` : 检查 X 和 y 是否具有一致的长度，对 X 调用 check_array，对 y 调用 column_or_1d。对于多标签分类或多目标回归，指定 multi_output=True，此时将对 y 调用 check_array。 - :func:`indexable` : 检查所有输入数组是否具有一致的长度，并且可以使用 safe_index 进行切片或索引。这用于验证交叉验证的输入。 - :func:`validation.check_memory` 检查输入是否类似于 ``joblib.Memory`` ，这意味着它可以转换为 ``sklearn.utils.Memory`` 实例（通常是一个表示 ``cachedir`` 的字符串）或具有相同的接口。 如果你的代码依赖于随机数生成器，它不应该使用像 ``numpy.random.random`` 或 ``numpy.random.normal`` 这样的函数。这种方法可能会导致单元测试中的重复性问题。相反，应该使用 ``numpy.random.RandomState`` 对象，它是从一个传递给类或函数的 ``random_state`` 参数构建的。下面的函数 :func:`check_random_state` 可以用来创建一个随机数生成器对象。 - :func:`check_random_state` : 从一个参数 ``random_state`` 创建一个 ``np.random.RandomState`` 对象。 - 如果 ``random_state`` 是 ``None`` 或 ``np.random`` ，则返回一个随机初始化的 ``RandomState`` 对象。 - 如果 ``random_state`` 是一个整数，则它被用来种子化一个新的 ``RandomState`` 对象。 - 如果 ``random_state`` 是一个 ``RandomState`` 对象，则它被直接传递。 例如:: >>> from sklearn.utils import check_random_state >>> random_state = 0 >>> random_state = check_random_state(random_state) >>> random_state.rand(4) array([0.5488135 , 0.71518937, 0.60276338, 0.54488318]) 在开发你自己的 scikit-learn 兼容估计器时，可以使用以下辅助函数。 - :func:`validation.check_is_fitted` : 检查在调用 ``transform`` 、 ``predict`` 或类似方法之前，估计器是否已经被拟合。这个辅助函数允许在估计器中引发标准化的错误消息。 - :func:`validation.has_fit_parameter` : 检查在给定估计器的 ``fit`` 方法中是否支持某个参数。 高效的线性代数和数组操作 ======================== - :func:`extmath.randomized_range_finder` : 构建一个正交矩阵，其范围近似于输入的范围。这在下面的 :func:`extmath.randomized_svd` 中使用。 - :func:`extmath.randomized_svd` : 计算 k-截断的随机 SVD。该算法找到精确的截断奇异值分解 使用随机化来加速计算。在希望仅提取少量成分的大型矩阵上，它特别快速。 - `arrayfuncs.cholesky_delete` ： （用于 :func:`~sklearn.linear_model.lars_path` ） 从 Cholesky 分解中移除一个项。 - :func:`arrayfuncs.min_pos` ：（用于 ``sklearn.linear_model.least_angle`` ） 在数组中找到正数值的最小值。 - :func:`extmath.fast_logdet` ：高效计算矩阵行列式的对数。 - :func:`extmath.density` ：高效计算稀疏向量的密度。 - :func:`extmath.safe_sparse_dot` ：能够正确处理 ``scipy.sparse`` 输入的点积。如果输入是密集的，它等价于 ``numpy.dot`` 。 - :func:`extmath.weighted_mode` ： ``scipy.stats.mode`` 的扩展，允许每个项具有实值权重。 - :func:`resample` ：以一致的方式重新采样数组或稀疏矩阵。用于下面的 :func:`shuffle` 。 - :func:`shuffle` ：以一致的方式打乱数组或稀疏矩阵。用于 :func:`~sklearn.cluster.k_means` 。 高效随机采样 ============ - :func:`random.sample_without_replacement` ：实现高效算法，从大小为 ``n_population`` 的总体中无放回地采样 ``n_samples`` 个整数。 稀疏矩阵的高效例程 ================== ``sklearn.utils.sparsefuncs`` Cython 模块托管了编译扩展，以高效处理 ``scipy.sparse`` 数据。 - :func:`sparsefuncs.mean_variance_axis` ：计算 CSR 矩阵指定轴上的均值和方差。 用于在 :class:`~sklearn.cluster.KMeans` 中规范化容差停止准则。 - :func:`sparsefuncs_fast.inplace_csr_row_normalize_l1` 和 :func:`sparsefuncs_fast.inplace_csr_row_normalize_l2` ：可用于将单个稀疏样本归一化为单位 L1 或 L2 范数，如在 :class:`~sklearn.preprocessing.Normalizer` . - :func:`sparsefuncs.inplace_csr_column_scale` : 可以用于将CSR矩阵的列乘以一个常数比例（每列一个比例）。 用于在 :class:`~sklearn.preprocessing.StandardScaler` 中将特征缩放到单位标准差。 - :func:`~sklearn.neighbors.sort_graph_by_row_values` : 可以用于对CSR稀疏矩阵进行排序，使得每行的值按递增顺序存储。 这对于在使用预计算的稀疏距离矩阵的估计器中提高效率很有用。 图例程 ====== - :func:`graph.single_source_shortest_path_length` : （目前未在scikit-learn中使用） 返回从一个单一源点到所有连接节点的最短路径。代码改编自 `networkx `_ 。 如果将来需要再次使用，使用 ``graph_shortest_path`` 中的Dijkstra算法单次迭代会快得多。 测试函数 ======== - :func:`discovery.all_estimators` : 返回scikit-learn中所有估计器的列表，用于测试一致的行为和接口。 - :func:`discovery.all_displays` : 返回scikit-learn中所有显示（与绘图API相关）的列表，用于测试一致的行为和接口。 - :func:`discovery.all_functions` : 返回scikit-learn中所有函数的列表，用于测试一致的行为和接口。 多类和多标签实用函数 ==================== - :func:`multiclass.is_multilabel` : 用于检查任务是否为多标签分类的辅助函数。 - :func:`multiclass.unique_labels` : 用于从不同格式的目标中提取有序的唯一标签的辅助函数。 辅助函数 ======== - :class:`gen_even_slices` : 生成器，用于创建直到 ``n`` 的 ``n`` -packs 切片。 用于 :func:`~sklearn.decomposition.dict_learning` 和 :func:`~sklearn.cluster.k_means` . - :class:`gen_batches` : 生成器，用于从0到 ``n`` 创建包含批量大小的元素的切片 - :func:`safe_mask` : 辅助函数，用于将掩码转换为numpy数组或scipy稀疏矩阵期望的格式（稀疏矩阵仅支持整数索引，而numpy数组支持布尔掩码和整数索引）。 - :func:`safe_sqr` : 用于统一平方（ ``**2`` ）数组、矩阵和稀疏矩阵的辅助函数。 哈希函数 ======== - :func:`murmurhash3_32` 提供了一个Python包装器，用于 ``MurmurHash3_x86_32`` C++非加密哈希函数。此哈希函数适用于实现查找表、布隆过滤器、计数最小草图、特征哈希和隐式定义的稀疏随机投影:: >>> from sklearn.utils import murmurhash3_32 >>> murmurhash3_32("some feature", seed=0) == -384616559 True >>> murmurhash3_32("some feature", seed=0, positive=True) == 3910350737 True ``sklearn.utils.murmurhash`` 模块也可以从其他cython模块中“cimported”，以便在跳过Python解释器开销的同时，从MurmurHash的高性能中受益。 警告和异常 ========== - :class:`deprecated` : 用于将函数或类标记为已弃用的装饰器。 - :class:`~sklearn.exceptions.ConvergenceWarning` : 自定义警告，用于捕获收敛问题。在 ``sklearn.covariance.graphical_lasso`` 中使用。