Skip to content

Commit fdc35f8

Browse files
committed
update docs and error messages for labels
1 parent 06c5d24 commit fdc35f8

File tree

1 file changed

+14
-5
lines changed

1 file changed

+14
-5
lines changed

pandas/core/reshape/tile.py

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
is_datetime64tz_dtype,
1717
is_datetime_or_timedelta_dtype,
1818
is_integer,
19+
is_list_like,
1920
is_scalar,
2021
is_timedelta64_dtype,
2122
)
@@ -66,11 +67,12 @@ def cut(
6667
``right == True`` (the default), then the `bins` ``[1, 2, 3, 4]``
6768
indicate (1,2], (2,3], (3,4]. This argument is ignored when
6869
`bins` is an IntervalIndex.
69-
labels : array or bool, optional
70+
labels : array or False, default None
7071
Specifies the labels for the returned bins. Must be the same length as
7172
the resulting bins. If False, returns only integer indicators of the
7273
bins. This affects the type of the output container (see below).
73-
This argument is ignored when `bins` is an IntervalIndex.
74+
This argument is ignored when `bins` is an IntervalIndex. If True,
75+
raises an error.
7476
retbins : bool, default False
7577
Whether to return the bins or not. Useful when bins is provided
7678
as a scalar.
@@ -287,10 +289,10 @@ def qcut(
287289
q : int or list-like of int
288290
Number of quantiles. 10 for deciles, 4 for quartiles, etc. Alternately
289291
array of quantiles, e.g. [0, .25, .5, .75, 1.] for quartiles.
290-
labels : array or bool, default None
292+
labels : array or False, default None
291293
Used as labels for the resulting bins. Must be of the same length as
292294
the resulting bins. If False, return only integer indicators of the
293-
bins.
295+
bins. If True, raises an error.
294296
retbins : bool, optional
295297
Whether to return the (bins, labels) or not. Can be useful if bins
296298
is given as a scalar.
@@ -396,11 +398,18 @@ def _bins_to_cuts(
396398
labels = _format_labels(
397399
bins, precision, right=right, include_lowest=include_lowest, dtype=dtype
398400
)
399-
else:
401+
elif labels:
402+
raise ValueError(
403+
"User desired bin labels must be passed in as an argument, "
404+
"not just `True`"
405+
)
406+
elif is_list_like(labels):
400407
if len(labels) != len(bins) - 1:
401408
raise ValueError(
402409
"Bin labels must be one fewer than the number of bin edges"
403410
)
411+
else:
412+
labels = Categorical(labels, categories=labels, ordered=True)
404413
if not is_categorical_dtype(labels):
405414
labels = Categorical(labels, categories=labels, ordered=True)
406415

0 commit comments

Comments
 (0)