ENH: Support expressions in `pd.qcut`

[mattharrison]

Pandas version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• I have confirmed this bug exists on the main branch of pandas.

Reproducible Example

import pandas as pd

small_df = pd.DataFrame(
    {'name': ['Alice', 'Bob', 'Charlie', 'David'],
     'score1': [90, 80, 70, 60],
     'score2': [85, 95, 75, 65]},
).convert_dtypes(dtype_backend='pyarrow')

result = (
    small_df
    .assign(
        score_bin=lambda df_: pd.qcut(df_['score1'], 2, labels=['low', 'high']),
        score_bin2=pd.qcut(pd.col('score2'), 2, labels=['low', 'high'])
    )
)

Issue Description

When using pd.qcut inside a .assign method, passing a column via pd.col('colname') does not work as expected. While direct column access (e.g., df_['score1']) works, using pd.col('score2') results in an error:

ValueError: Input array must be 1 dimensional

This limits the flexibility of using pd.qcut with the new pd.col API

Expected Behavior

Both score_bin and score_bin2 should be assigned correctly, with quantile bins computed for each column.

Installed Versions

INSTALLED VERSIONS

commit : 1a3230d
python : 3.11.13
python-bits : 64
OS : Darwin
OS-release : 24.6.0
Version : Darwin Kernel Version 24.6.0: Mon Jul 14 11:30:40 PDT 2025; root:xnu-11417.140.69~1/RELEASE_ARM64_T6041
machine : arm64
processor : arm
byteorder : little
LC_ALL : None
LANG : None
LOCALE : en_US.UTF-8

pandas : 3.0.0rc0
numpy : 2.4.0rc1
dateutil : 2.9.0.post0
pip : None
Cython : 3.2.2
sphinx : None
IPython : 9.8.0
adbc-driver-postgresql: None
adbc-driver-sqlite : None
bs4 : 4.14.3
bottleneck : None
fastparquet : None
fsspec : None
html5lib : None
hypothesis : None
gcsfs : None
jinja2 : 3.1.6
lxml.etree : 6.0.2
matplotlib : 3.10.7
numba : None
numexpr : None
odfpy : None
openpyxl : None
psycopg2 : None
pymysql : None
pyarrow : 22.0.0
pyiceberg : None
pyreadstat : None
pytest : None
python-calamine : None
pytz : 2025.2
pyxlsb : None
s3fs : None
scipy : 1.16.3
sqlalchemy : None
tables : None
tabulate : None
xarray : None
xlrd : None
xlsxwriter : None
zstandard : None
qtpy : None
pyqt5 : None

[rhshadrach]

This is currently not intended to work; reworking as a feature request.

It does not seem straightforward to allow pd.qcut to take an expression, but perhaps I'm missing something.

If we added Series.qcut, this would also be available. This can been considered before: #12640 (comment), I wonder if the advent of pd.col might change some thinking here. It sounds like the previous reason was that users can specify retbins=True which defeats chaining, but they can also specify as retbins=False (the default) which supports chaining so I'm not sure I understand the reasoning.

cc @mroeschke @jbrockmendel

[jbrockmendel]

If we added Series.qcut, this would also be available

It isn't obvious to me how that would make pd.col work in this context. Or do you mean it would make pd.col unnecessary?

It sounds like the previous reason was that

#12640 was before my time. If the idea of adding Series.qcut were to come up now, my comment would be "we should Series.qcut or pd.qcut, but not both"

[rhshadrach]

If we added Series.qcut, this would also be available

It isn't obvious to me how that would make pd.col work in this context. Or do you mean it would make pd.col unnecessary?

The implementation of pd.col works with chaining any method. We essentially track the methods being accessed and the arguments being passed when the expression is created. Then when that expression is passed to e.g. DataFrame.assign, we follow the chain starting with self[column_name].

The upshot is any Series method automatically works with pd.col.

If the idea of adding Series.qcut were to come up now, my comment would be "we should Series.qcut or pd.qcut, but not both"

Only thing we lose by deprecating pd.qcut is usage on NumPy arrays. I'm +1 on deprecating.