docs: update freq description for pd.Timedelta.ceil to match DatetimeIndex.ceil's freq description

[robert-nash]

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
td = pd.Timedelta('1001ms')
td.ceil("s")
td.ceil("min")
td.ceil("m")

Issue Description

Calling td.ceil("m") causes the error:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "timedeltas.pyx", line 2011, in pandas._libs.tslibs.timedeltas.Timedelta.ceil
  File "timedeltas.pyx", line 1934, in pandas._libs.tslibs.timedeltas.Timedelta._round
  File "timedeltas.pyx", line 2309, in pandas._libs.tslibs.timedeltas.get_unit_for_round
  File "offsets.pyx", line 756, in pandas._libs.tslibs.offsets.BaseOffset.nanos.__get__
ValueError: <MonthEnd> is a non-fixed frequency

Expected Behavior

td.ceil("m") should behave the same as td.ceil("min")

The documentation for pandas.Timedelta.ceil states that the freq parameter uses the same units as class constructor Timedelta.

The documentation for pandas.Timedelta lists (‘minutes’, ‘minute’, ‘min’, or ‘m’) as one of the possible value lines. This suggests to me that "min" and "m" are equivalent.

It seems that either the documentation could be clearer or there is a bug?

Installed Versions

INSTALLED VERSIONS

commit : 0691c5c
python : 3.12.4
python-bits : 64
OS : Windows
OS-release : 11
Version : 10.0.22631
machine : AMD64
processor : Intel64 Family 6 Model 154 Stepping 3, GenuineIntel
byteorder : little
LC_ALL : None
LANG : en_US.UTF-8
LOCALE : English_United Kingdom.1252

pandas : 2.2.3
numpy : 2.0.1
pytz : 2024.2
dateutil : 2.9.0.post0
pip : 24.1
Cython : None
sphinx : None
IPython : None
adbc-driver-postgresql: None
adbc-driver-sqlite : None
bs4 : None
blosc : None
bottleneck : None
dataframe-api-compat : None
fastparquet : None
fsspec : None
html5lib : None
hypothesis : None
gcsfs : None
jinja2 : 3.1.4
lxml.etree : None
matplotlib : None
numba : None
numexpr : None
odfpy : None
openpyxl : None
pandas_gbq : None
psycopg2 : None
pymysql : None
pyarrow : None
pyreadstat : None
pytest : None
python-calamine : None
pyxlsb : None
s3fs : None
scipy : 1.14.0
sqlalchemy : None
tables : None
tabulate : None
xarray : None
xlrd : None
xlsxwriter : None
zstandard : None
tzdata : 2024.2
qtpy : None
pyqt5 : None

[nicholasyfu1]

I can work on this

[rhshadrach]

Thanks for the report!

@natmokval & @MarcoGorelli - I believe you've been doing a lot of work here. It looks like m used to be equivalent to ME but m will be removed in pandas 3.0. Do we want to allow m here to used for minute now? Even if we want to eventually do so, I think it might make sense to wait for 3.1 or 3.2 so that code raises for 3.0 rather than changing results.

[MarcoGorelli]

Thanks for the ping, will take a look

[MarcoGorelli]

I think the docs need updated, I just tried going back to pandas 1.5.3 and it looks like ceil('m') never worked to begin with

In [1]: import pandas as pd
   ...: td = pd.Timedelta('1001ms')
   ...: td.ceil("s")
   ...: td.ceil("min")
   ...: td.ceil("m")
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[1], line 5
      3 td.ceil("s")
      4 td.ceil("min")
----> 5 td.ceil("m")

File ~/scratch/.39venv/lib/python3.9/site-packages/pandas/_libs/tslibs/timedeltas.pyx:1781, in pandas._libs.tslibs.timedeltas.Timedelta.ceil()

File ~/scratch/.39venv/lib/python3.9/site-packages/pandas/_libs/tslibs/timedeltas.pyx:1735, in pandas._libs.tslibs.timedeltas.Timedelta._round()

File ~/scratch/.39venv/lib/python3.9/site-packages/pandas/_libs/tslibs/offsets.pyx:821, in pandas._libs.tslibs.offsets.BaseOffset.nanos.__get__()

ValueError: <MonthEnd> is a non-fixed frequency

In [2]: pd.__version__
Out[2]: '1.5.3'

[MarcoGorelli]

The documentation for pandas.Timedelta.ceil states that the freq parameter uses the same units as class constructor Timedelta.

@robert-nash where does it say this? looking at the docs, I see

The frequency level to ceil the index to. Must be a fixed frequency like ‘S’ (second) not ‘ME’ (month end). See frequency aliases for a list of possible freq values.

and the list shows the offset aliases https://pandas.pydata.org/docs/user_guide/timeseries.html#timeseries-offset-aliases

[robert-nash]

@MarcoGorelli The documentation for pandas.Timedelta.ceil I linked to looks like this to me. Do let me know if I missing something!

https://pandas.pydata.org/docs/reference/api/pandas.Timedelta.ceil.html#pandas.Timedelta.ceil

[MarcoGorelli]

ah thanks @robert-nash , the DatetimeIndex.ceil and Timedelta.ceil docs say different things. I'd say that the latter needs updating so its description of freq matches the one from the former

[rhshadrach]

@MarcoGorelli - I think it's currently the case that pd.Timedelta('1001m') is allowed and will give minutes, but pd.Timedelta('1001m').ceil('m') will raise. This is because the m in .ceil('m') was interpreted as Month End.

But now using m for Month End is being removed, we have the opportunity to allow the m in .ceil('m') to signify minutes. Is this not desirable?

Please keep in mind I'm quite unfamiliar with this area of pandas 😆

[eightyseven]

take
I'm a beginner and I’m planning to go through the docs in detail and do some testing to figure out how Timedelta.ceil behaves, hoping to update the docs to reflect the correct info and make sure it matches up with DatetimeIndex.ceil.

[eightyseven]

take

[Swati-Sneha]

Even I have been trying to edit the documentation, but I am facing issue in python make.py html.

reading sources... [ 98%] whatsnew/v0.19.0 .. whatsnew/v1.3.1
Exception occurred:
  File "/Users/swatisneha/miniforge3/envs/pandas-dev/lib/python3.10/multiprocessing/connection.py", line 383, in _recv
    raise EOFError
EOFError

I also tried to remove my changes and build it again, but the error persists.

[tohfas]

Hi, I am looking for this issue for my university assignment. Can this issue be assigned to me? Please let me know. Thanks.

[Wong2333]

take

[MarcoGorelli]

But now using m for Month End is being removed, we have the opportunity to allow the m in .ceil('m') to signify minutes. Is this not desirable?

maybe..will think about this

EDIT: I can't commit to driving / reviewing this right now, but I won't block it either