pandas.cut#

pandas.cut(x, bins, right=True, labels=None, retbins=False, precision=3, include_lowest=False, duplicates='raise', ordered=True)[源代码][源代码]#

将值分箱到离散区间中。

当你需要将数据值分段并排序到箱中时，请使用 cut。这个函数对于将连续变量转换为分类变量也很有用。例如，cut 可以将年龄转换为年龄段组。支持分箱到相等数量的箱中，或预先指定的箱数组。

参数:

xarray-like

要分箱的输入数组。必须是1维的。

binsint, 标量的序列, 或 IntervalIndex

用于分箱的标准。

int : 定义了 x 范围内等宽箱的数量。x 的范围在每侧扩展了0.1%，以包括 x 的最小值和最大值。
标量序列 : 定义了箱边缘，允许非均匀宽度。不会扩展 x 的范围。
IntervalIndex : 定义了要使用的精确区间。注意，用于 bins 的 IntervalIndex 必须是非重叠的。

right布尔值, 默认为 True

指示 bins 是否包括右边缘。如果 right == True``（默认值），那么 `bins` ``[1, 2, 3, 4] 表示 (1,2], (2,3], (3,4]。当 bins 是 IntervalIndex 时，此参数将被忽略。

标签数组或 False, 默认 None

指定返回的箱的标签。必须与结果箱的长度相同。如果为 False，则仅返回箱的整数指示符。这会影响输出容器的类型（见下文）。当 bins 是 IntervalIndex 时，此参数将被忽略。如果为 True，则会引发错误。当 ordered=False 时，必须提供标签。

retbins布尔值, 默认为 False

是否返回箱子。当 bins 作为标量提供时很有用。

精度int, 默认 3

存储和显示箱标签的精度。

include_lowest布尔值, 默认为 False

第一个区间是否应该是左包含的。

重复项{默认 ‘raise’, ‘drop’}, 可选

如果 bin 边缘不唯一，引发 ValueError 或删除非唯一项。

有序布尔值, 默认为 True

标签是否有序。适用于返回的类型 Categorical 和 Series（带有 Categorical dtype）。如果为 True，则生成的分类将是有序的。如果为 False，则生成的分类将是无序的（必须提供标签）。

返回:

出类别型, 序列, 或 ndarray

一个类似数组的对象，表示 x 每个值对应的 bin。类型取决于 labels 的值。

None（默认）：对于 Series x 返回一个 Series，对于所有其他输入返回一个 Categorical。存储的值是 Interval 数据类型。
标量序列 : 对于 Series x 返回一个 Series，对于所有其他输入返回一个 Categorical。存储的值是序列中的类型。
False : 返回一个整数的 ndarray。

binsnumpy.ndarray 或 IntervalIndex.

计算或指定的箱子。仅当 retbins=True 时返回。对于标量或序列 bins，这是一个包含计算箱子的 ndarray。如果设置 duplicates=drop，bins 将删除非唯一的箱子。对于 IntervalIndex bins，这等于 bins。

参见

qcut: 将变量离散化为基于等级或基于样本分位数的等大小桶。
分类: 用于存储来自一组固定值的数据的数组类型。
系列: 带有轴标签的一维数组（包括时间序列）。
IntervalIndex: 实现有序、可切片集合的不可变索引。
numpy.histogram_bin_edges: 计算直方图函数使用的箱子的边缘的函数。

备注

任何 NA 值在结果中将是 NA。越界值在结果的 Series 或 Categorical 对象中将是 NA。

numpy.histogram_bin_edges 可以与 cut 一起使用，根据某些预定义的方法计算箱子。

更多示例请参考用户指南。

示例

将数据离散化为三个等大小的区间。

>>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3)
... 
[(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0], (5.0, 7.0], ...
Categories (3, interval[float64, right]): [(0.994, 3.0] < (3.0, 5.0] ...

>>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3, retbins=True)
... 
([(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0], (5.0, 7.0], ...
Categories (3, interval[float64, right]): [(0.994, 3.0] < (3.0, 5.0] ...
array([0.994, 3.   , 5.   , 7.   ]))

发现相同的箱子，但为它们分配特定的标签。注意返回的 Categorical 的类别是 labels 并且是有序的。

>>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3, labels=["bad", "medium", "good"])
['bad', 'good', 'medium', 'medium', 'good', 'bad']
Categories (3, object): ['bad' < 'medium' < 'good']

ordered=False 在传递标签时将导致无序类别。此参数可用于允许非唯一标签：

>>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3, labels=["B", "A", "B"], ordered=False)
['B', 'B', 'A', 'A', 'B', 'B']
Categories (2, object): ['A', 'B']

labels=False 意味着你只想返回分箱。

>>> pd.cut([0, 1, 1, 2], bins=4, labels=False)
array([0, 1, 1, 3])

将一个 Series 作为输入返回一个具有分类数据类型的 Series：

>>> s = pd.Series(np.array([2, 4, 6, 8, 10]), index=["a", "b", "c", "d", "e"])
>>> pd.cut(s, 3)
... 
a    (1.992, 4.667]
b    (1.992, 4.667]
c    (4.667, 7.333]
d     (7.333, 10.0]
e     (7.333, 10.0]
dtype: category
Categories (3, interval[float64, right]): [(1.992, 4.667] < (4.667, ...

将一个 Series 作为输入返回一个带有映射值的 Series。它用于根据区间对数值进行映射。

>>> s = pd.Series(np.array([2, 4, 6, 8, 10]), index=["a", "b", "c", "d", "e"])
>>> pd.cut(s, [0, 2, 4, 6, 8, 10], labels=False, retbins=True, right=False)
... 
(a    1.0
 b    2.0
 c    3.0
 d    4.0
 e    NaN
 dtype: float64,
 array([ 0,  2,  4,  6,  8, 10]))

当 bins 不是唯一时使用 drop 可选

>>> pd.cut(
...     s,
...     [0, 2, 4, 6, 10, 10],
...     labels=False,
...     retbins=True,
...     right=False,
...     duplicates="drop",
... )
... 
(a    1.0
 b    2.0
 c    3.0
 d    3.0
 e    NaN
 dtype: float64,
 array([ 0,  2,  4,  6, 10]))

将 IntervalIndex 传递给 bins 会得到这些类别。注意，未被 IntervalIndex 覆盖的值会设置为 NaN。0 在第一个箱子的左边（该箱子在右边闭合），而 1.5 落在两个箱子之间。

>>> bins = pd.IntervalIndex.from_tuples([(0, 1), (2, 3), (4, 5)])
>>> pd.cut([0, 0.5, 1.5, 2.5, 4.5], bins)
[NaN, (0.0, 1.0], NaN, (2.0, 3.0], (4.0, 5.0]]
Categories (3, interval[int64, right]): [(0, 1] < (2, 3] < (4, 5]]

使用 np.histogram_bin_edges 与 cut

>>> pd.cut(
...     np.array([1, 7, 5, 4]),
...     bins=np.histogram_bin_edges(np.array([1, 7, 5, 4]), bins="auto"),
... )
... 
[NaN, (5.0, 7.0], (3.0, 5.0], (3.0, 5.0]]
Categories (3, interval[float64, right]): [(1.0, 3.0] < (3.0, 5.0] < (5.0, 7.0]]