cut(x, bins, right: 'bool' = True, labels=None, retbins: 'bool' = False, precision: 'int' = 3, include_lowest: 'bool' = False, duplicates: 'str' = 'raise', ordered: 'bool' = True)
Use cut
when you need to segment and sort data values into bins. This function is also useful for going from a continuous variable to a categorical variable. For example, cut
could convert ages to groups of age ranges. Supports binning into an equal number of bins, or a pre-specified array of bins.
Any NA values will be NA in the result. Out of bounds values will be NA in the resulting Series or Categorical object.
Reference the user guide <reshaping.tile.cut>
for more examples.
The input array to be binned. Must be 1-dimensional.
The criteria to bin by.
Indicates whether :None:None:`bins` includes the rightmost edge or not. If right == True
(the default), then the :None:None:`bins` [1, 2, 3, 4]
indicate (1,2], (2,3], (3,4]. This argument is ignored when :None:None:`bins` is an IntervalIndex.
Specifies the labels for the returned bins. Must be the same length as the resulting bins. If False, returns only integer indicators of the bins. This affects the type of the output container (see below). This argument is ignored when :None:None:`bins` is an IntervalIndex. If True, raises an error. When :None:None:`ordered=False`, labels must be provided.
Whether to return the bins or not. Useful when bins is provided as a scalar.
The precision at which to store and display the bins labels.
Whether the first interval should be left-inclusive or not.
If bin edges are not unique, raise ValueError or drop non-uniques.
Whether the labels are ordered or not. Applies to returned types Categorical and Series (with Categorical dtype). If True, the resulting categorical will be ordered. If False, the resulting categorical will be unordered (labels must be provided).
An array-like object representing the respective bin for each value of x. The type depends on the value of :None:None:`labels`.
The computed or specified bins. Only returned when :None:None:`retbins=True`. For scalar or sequence :None:None:`bins`, this is an ndarray with the computed bins. If set :None:None:`duplicates=drop`, :None:None:`bins` will drop non-unique bin. For an IntervalIndex :None:None:`bins`, this is equal to :None:None:`bins`.
Bin values into discrete intervals.
Categorical
Array type for storing data that come from a fixed set of values.
IntervalIndex
Immutable Index implementing an ordered, sliceable set.
Series
One-dimensional array with axis labels (including time series).
qcut
Discretize variable into equal-sized buckets based on rank or based on sample quantiles.
Discretize into three equal-sized bins.
This example is valid syntax, but we were not able to check execution>>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3)This example is valid syntax, but we were not able to check execution
... # doctest: +ELLIPSIS [(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)
... # doctest: +ELLIPSIS ([(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. ]))
Discovers the same bins, but assign them specific labels. Notice that the returned Categorical's categories are :None:None:`labels` and is ordered.
>>> 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
will result in unordered categories when labels are passed. This parameter can be used to allow non-unique labels:
>>> 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
implies you just want the bins back.
>>> pd.cut([0, 1, 1, 2], bins=4, labels=False) array([0, 1, 1, 3])
Passing a Series as an input returns a Series with categorical dtype:
This example is valid syntax, but we were not able to check execution>>> s = pd.Series(np.array([2, 4, 6, 8, 10]),
... index=['a', 'b', 'c', 'd', 'e'])
... pd.cut(s, 3)
... # doctest: +ELLIPSIS 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, ...
Passing a Series as an input returns a Series with mapping value. It is used to map numerically to intervals based on bins.
This example is valid syntax, but we were not able to check execution>>> 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)
... # doctest: +ELLIPSIS (a 1.0 b 2.0 c 3.0 d 4.0 e NaN dtype: float64, array([ 0, 2, 4, 6, 8, 10]))
Use :None:None:`drop` optional when bins is not unique
>>> pd.cut(s, [0, 2, 4, 6, 10, 10], labels=False, retbins=True,
... right=False, duplicates='drop')
... # doctest: +ELLIPSIS (a 1.0 b 2.0 c 3.0 d 3.0 e NaN dtype: float64, array([ 0, 2, 4, 6, 10]))
Passing an IntervalIndex for :None:None:`bins` results in those categories exactly. Notice that values not covered by the IntervalIndex are set to NaN. 0 is to the left of the first bin (which is closed on the right), and 1.5 falls between two bins.
>>> bins = pd.IntervalIndex.from_tuples([(0, 1), (2, 3), (4, 5)])See :
... 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]]
The following pages refer to to this document either explicitly or contain code examples using this.
pandas.core.arrays.interval.IntervalArray
pandas.core.reshape.tile.cut
pandas.core.indexes.interval.IntervalIndex
pandas._libs.interval.Interval
Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.
Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)
SVG is more flexible but power hungry; and does not scale well to 50 + nodes.
All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them