DEPR: the method is_anchored() for offsets #56594

natmokval · 2023-12-21T22:55:53Z

closes DOC: DateOffset.is_anchored track down intention, fix docstring #55388

deprecated the method is_anchored() for offsets classes: Tick, Week, QuarterOffset, FY5253Mixin, BaseOffset

natmokval · 2023-12-28T15:49:45Z

in this PR is_anchored() is deprecated for offsets. @MarcoGorelli, could you please take a look at my PR?

MarcoGorelli · 2023-12-28T15:53:20Z

nice! @jbrockmendel I think you'd suggested this, fancy taking a look?

jbrockmendel · 2023-12-28T16:50:35Z

doc/source/whatsnew/v2.2.0.rst

@@ -592,6 +593,7 @@ Other Deprecations
 - Deprecated :meth:`Series.ravel`, the underlying array is already 1D, so ravel is not necessary (:issue:`52511`)
 - Deprecated :meth:`Series.resample` and :meth:`DataFrame.resample` with a :class:`PeriodIndex` (and the 'convention' keyword), convert to :class:`DatetimeIndex` (with ``.to_timestamp()``) before resampling instead (:issue:`53481`)
 - Deprecated :meth:`Series.view`, use :meth:`Series.astype` instead to change the dtype (:issue:`20251`)
+- Deprecated :meth:`offsets.Tick().is_anchored()`, use ``False`` instead (:issue:`55388`)


no parentheses

Thank you for reviewing this PR. I removed the parentheses

jbrockmendel · 2023-12-28T16:51:43Z

doc/source/whatsnew/v2.2.0.rst

@@ -584,6 +584,7 @@ Other Deprecations
 - Changed :meth:`Timedelta.resolution_string` to return ``h``, ``min``, ``s``, ``ms``, ``us``, and ``ns`` instead of ``H``, ``T``, ``S``, ``L``, ``U``, and ``N``, for compatibility with respective deprecations in frequency aliases (:issue:`52536`)
 - Deprecated :attr:`offsets.Day.delta`, :attr:`offsets.Hour.delta`, :attr:`offsets.Minute.delta`, :attr:`offsets.Second.delta`, :attr:`offsets.Milli.delta`, :attr:`offsets.Micro.delta`, :attr:`offsets.Nano.delta`, use ``pd.Timedelta(obj)`` instead (:issue:`55498`)
 - Deprecated :func:`pandas.api.types.is_interval` and :func:`pandas.api.types.is_period`, use ``isinstance(obj, pd.Interval)`` and ``isinstance(obj, pd.Period)`` instead (:issue:`55264`)
+- Deprecated :func:`pd.DateOffset().is_anchored()`, use ``DateOffset().n == 1`` instead (:issue:`55388`)


:meth:DateOffset.is_anchored, use ``obj.n == 1` for non-Tick subclasses (for Tick this was always False)

thanks, I did as you suggested

jbrockmendel · 2023-12-28T16:52:07Z

pandas/_libs/tslibs/offsets.pyx

        """
        Return boolean whether the frequency is a unit frequency (n=1).

+        .. deprecated:: 2.2.0
+            The is_anchored is deprecated and will be removed in a future version.


"The is_anchored is deprecated" -> "is_anchored is deprecated"

jbrockmendel · 2023-12-28T16:52:22Z

pandas/_libs/tslibs/offsets.pyx

        """
        Return boolean whether the frequency is a unit frequency (n=1).

+        .. deprecated:: 2.2.0
+            The is_anchored is deprecated and will be removed in a future version.
+            Do ``DateOffset().n == 1`` instead of ``DateOffset().is_anchored()``.


"Use obj.n == 1"

jbrockmendel · 2023-12-28T16:52:42Z

pandas/_libs/tslibs/offsets.pyx

        Examples
        --------
        >>> pd.DateOffset().is_anchored()
        True
        >>> pd.DateOffset(2).is_anchored()
        False
        """
+        warnings.warn(
+            f"{type(self).__name__}.is_anchored() is deprecated and will be removed "
+            f"in a future version, please use {type(self).__name__}.n == 1 instead.",


{type(self).name}.n -> obj.n

jbrockmendel · 2023-12-28T16:53:23Z

pandas/_libs/tslibs/offsets.pyx

+
+        Examples
+        --------
+        >>> pd.offsets.Tick().is_anchored()


Tick should never be initialized directly; use a subclass here

thank you, I will use Hour

jbrockmendel · 2023-12-28T16:55:13Z

pandas/tests/indexes/interval/test_interval_range.py

@@ -84,7 +84,7 @@ def test_constructor_timestamp(self, closed, name, freq, periods, tz):
        tm.assert_index_equal(result, expected)

        # GH 20976: linspace behavior defined from start/end/periods
-        if not breaks.freq.is_anchored() and tz is None:
+        if not breaks.freq.n == 1 and tz is None:
            # matches expected only for non-anchored offsets and tz naive


comment here refers to anchoring. i suspect the comment (which i suspect i wrote) misunderstood what "is_anchored" really meant

thanks, I removed the comment

…ove the comment

natmokval · 2024-01-02T22:57:46Z

I found some inconsistency in the behavior of the classes BusinessHour and CustomBusinessHour.
We always return False for pd.offsets.Hour().is_anchored()
But unexpectedly I get True for

pd.offsets.BusinessHour().is_anchored()
pd.offsets.CustomBusinessHour().is_anchored()

I am not sure, is it a bug?

And messages in the FutureWarning are different:

Hour.is_anchored is deprecated and will be removed in a future version, please use False instead.
BusinessHour.is_anchored is deprecated and will be removed in a future version, please use 'obj.n == 1' instead.

The reason is they are non-Tick subclasses.

Should we fix it before we deprecate is_anchored? What do you think, @jbrockmendel?

MarcoGorelli · 2024-01-04T12:32:02Z

just for reference, here's the (only) use-case I found of is_anchored in the wild:

https://github.com/pastas/pastas/blob/dbe3275e012143605e3a162bfbb8ff0983d966e6/pastas/timeseries_utils.py#L160-L185

It wouldn't work for converting '2W-Tue' to '14D' though, so I'm not sure is_anchored is what they really wanted in the first place

I doubt anyone's using it for business hour / custom business hour - I think it's fine to just deprecate

MarcoGorelli · 2024-01-09T16:07:10Z

/preview

github-actions · 2024-01-09T16:07:20Z

Website preview of this PR available at: https://pandas.pydata.org/preview/56594/

MarcoGorelli · 2024-01-10T16:06:01Z

pandas/_libs/tslibs/offsets.pyx

@@ -3597,6 +3641,12 @@ cdef class FY5253Mixin(SingleConstructorOffset):
        self.variation = state.pop("variation")

    def is_anchored(self) -> bool:
+        warnings.warn(
+            f"{type(self).__name__}.is_anchored is deprecated and will be removed "
+            f"in a future version, please use \'obj.n == 1\' instead.",


do we not want to say about self.startingMonth is not None and self.weekday is not None in this one?

I am not sure about this. I think, there is no need to check if parameters startingMonth and weekday are not None. For subclasses of the class FY5253Mixin we initialize these parameters in constructor and set them 0 and 1 accordingly.

pandas/pandas/_libs/tslibs/offsets.pyx

Lines 3579 to 3580 in 1381f70

def __init__(

self, n=1, normalize=False, weekday=0, startingMonth=1, variation="nearest"

right, thanks, they can't actually be None, so the is_anchored definition was too complex to begin with

if we check:

>>> pd.offsets.FY5253().is_anchored() FutureWarning: FY5253.is_anchored is deprecated and will be removed in a future version, please use 'obj.n == 1' instead. True >>> pd.offsets.FY5253(n=1, startingMonth=1, weekday=1).is_anchored() True

On the other hand for the class Week we have

>>> pd.offsets.Week(1).is_anchored() FutureWarning: Week.is_anchored is deprecated and will be removed in a future version, please use 'obj.n == 1 and obj.weekday is not None' instead. False >>> pd.offsets.Week(n=1, weekday=0).is_anchored() True

but also, trying to pass None just raises

In [12]: FY5253(n=1, weekday=1, startingMonth=1).is_anchored() <ipython-input-12-37644e23496a>:1: FutureWarning: FY5253.is_anchored is deprecated and will be removed in a future version, please use 'obj.n == 1' instead. FY5253(n=1, weekday=1, startingMonth=1).is_anchored() Out[12]: True In [13]: FY5253(n=1, weekday=None, startingMonth=None).is_anchored() --------------------------------------------------------------------------- TypeError Traceback (most recent call last) Cell In[13], line 1 ----> 1 FY5253(n=1, weekday=None, startingMonth=None).is_anchored() File offsets.pyx:3627, in pandas._libs.tslibs.offsets.FY5253Mixin.__init__() TypeError: an integer is required In [14]: FY5253(n=1, weekday=None, startingMonth=1).is_anchored() --------------------------------------------------------------------------- TypeError Traceback (most recent call last) Cell In[14], line 1 ----> 1 FY5253(n=1, weekday=None, startingMonth=1).is_anchored() File offsets.pyx:3628, in pandas._libs.tslibs.offsets.FY5253Mixin.__init__() TypeError: an integer is required In [15]: FY5253(n=1, weekday=1, startingMonth=None).is_anchored() --------------------------------------------------------------------------- TypeError Traceback (most recent call last) Cell In[15], line 1 ----> 1 FY5253(n=1, weekday=1, startingMonth=None).is_anchored() File offsets.pyx:3627, in pandas._libs.tslibs.offsets.FY5253Mixin.__init__() TypeError: an integer is required

MarcoGorelli

nice one, thanks @natmokval , let's backport this

natmokval · 2024-01-10T16:42:47Z

thanks @MarcoGorelli for reviewing this PR

…r offsets) (#56813) Backport PR #56594: DEPR: the method is_anchored() for offsets Co-authored-by: Natalia Mokeeva <91160475+natmokval@users.noreply.github.com>

phofl · 2024-01-11T21:02:10Z

pandas/_libs/tslibs/offsets.pyx

+        False
+        """
+        warnings.warn(
+            f"{type(self).__name__}.is_anchored is deprecated and will be removed "


I don't understand this deprecation, how can I check for the equivalent attribute here? Use False is not really helpful

for this class it's always False

for others you typically need to check that obj.n==1 and obj.weekday is None (if it has a weekday attribute) and obj.startingMonth is None (if it has a startingMonth attribute)

what are you using it for?

We are generally looking for freqs that aren’t anchored

I thought a little bit about this and the deprecations isn’t great, it makes those checks significantly more complex than before for users

I thought that we can advise users use False, because is_anchored always returns False for Tick subclasses.
Do you think it would be better to use some expression that is always False instead of False, like pd.offsets.Hour().n == None?

I mostly don’t want to have different check for every group, that’s what makes this ugly

That helps, thx

We have to make a decision about shifting divisions, this basically goes back how the offset behaves on different values, e.g. if it can shift different values to the same target (if it's anchored for example) then we have to make a different decision compared to if every value maps to a distinct target value

e.g. if it can shift different values to the same target (if it's anchored for example)

An example might help here. I think what you're referring to is what past-me thought is_anchored meant (xref #44025), e.g "W-SUN" would be anchored, but "W" would not (it would act like "7D"). pd.DateOffset(day=1) would, but pd.DateOffset(days=1) would not.

NB: the "is equivalent to" i gave about isn't quite right.

idx = pd.Index([pd.Timestamp("2020-01-01"), pd.Timestamp("2020-01-02")]) print(idx.shift(1, freq=pd.tseries.offsets.Week(1))) print(idx.shift(1, freq=pd.tseries.offsets.Week(1, weekday=2)))

DatetimeIndex(['2020-01-08', '2020-01-09'], dtype='datetime64[ns]', freq=None) DatetimeIndex(['2020-01-08', '2020-01-08'], dtype='datetime64[ns]', freq=None)

The first one just shifts 7 days, so everything is fine

The second one shifts to a specific weekday though, which is an issue for us, because it maps 2 different days to the same target

That matches what I think a more-useful is_anchored would mean. My guess is we can come up with examples (e.g. the day=1 vs days=1 above) where checking is_anchored would be wrong for your use case.

idx = pd.Index([pd.Timestamp("2020-01-01"), pd.Timestamp("2020-01-02")]) print(idx.shift(1, freq=pd.tseries.offsets.Week(2))) print(idx.shift(1, freq=pd.tseries.offsets.Week(2, weekday=2)))

DatetimeIndex(['2020-01-15', '2020-01-16'], dtype='datetime64[ns]', freq=None) DatetimeIndex(['2020-01-15', '2020-01-15'], dtype='datetime64[ns]', freq=None)

The first one just shifts 14 days, and the second one shifts to a specific weekday

Yet neither "is_anchored":

In [21]: pd.tseries.offsets.Week(2).is_anchored() Out[21]: False In [22]: pd.tseries.offsets.Week(2, weekday=2).is_anchored() Out[22]: False

natmokval added 2 commits December 22, 2023 16:53

deprecate is_anchored, fix tests

287fdef

fix tests

8c870f6

natmokval force-pushed the depr-is-anchored branch from 900c44c to 8c870f6 Compare December 28, 2023 09:58

natmokval added 3 commits December 28, 2023 13:39

fix tests

df78796

Merge branch 'main' into depr-is-anchored

005198b

correct DateOffset and Tick docstrings, add notes to v2.2.0

e703817

natmokval changed the title ~~DEPR: is_anchored()~~ DEPR: the method is_anchored() for offsets Dec 28, 2023

fix pylint error

d031fad

natmokval marked this pull request as ready for review December 28, 2023 15:46

natmokval requested a review from MarcoGorelli as a code owner December 28, 2023 15:46

MarcoGorelli requested a review from jbrockmendel December 28, 2023 15:53

jbrockmendel reviewed Dec 28, 2023

View reviewed changes

correct notes in v2.2.0, correct warning messages in is_anchored, rem…

b0d7ef4

…ove the comment

MarcoGorelli reviewed Jan 10, 2024

View reviewed changes

MarcoGorelli approved these changes Jan 10, 2024

View reviewed changes

MarcoGorelli added this to the 2.2 milestone Jan 10, 2024

MarcoGorelli added Frequency DateOffsets Deprecate Functionality to remove in pandas labels Jan 10, 2024

MarcoGorelli merged commit f40475f into pandas-dev:main Jan 10, 2024
56 checks passed

github-actions bot mentioned this pull request Jan 10, 2024

DEPR: List of deprecations to be removed in 4.0 #56596

Open

12 tasks

meeseeksmachine pushed a commit to meeseeksmachine/pandas that referenced this pull request Jan 10, 2024

Backport PR pandas-dev#56594: DEPR: the method is_anchored() for offsets

bfa5629

meeseeksmachine mentioned this pull request Jan 10, 2024

Backport PR #56594 on branch 2.2.x (DEPR: the method is_anchored() for offsets) #56813

Merged

lithomas1 mentioned this pull request Jan 10, 2024

DEPR: List of deprecations to be removed in 3.0 #50578

Open

phofl reviewed Jan 11, 2024

View reviewed changes

natmokval mentioned this pull request Feb 17, 2024

DEPR: remove deprecated method is_anchored #57473

Merged

pmhatre1 pushed a commit to pmhatre1/pandas-pmhatre1 that referenced this pull request May 7, 2024

DEPR: the method is_anchored() for offsets (pandas-dev#56594)

9056a30

	def __init__(
	self, n=1, normalize=False, weekday=0, startingMonth=1, variation="nearest"

DEPR: the method is_anchored() for offsets #56594

DEPR: the method is_anchored() for offsets #56594

Conversation

natmokval commented Dec 21, 2023 • edited

natmokval commented Dec 28, 2023 • edited

MarcoGorelli commented Dec 28, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

natmokval commented Jan 2, 2024

MarcoGorelli commented Jan 4, 2024

MarcoGorelli commented Jan 9, 2024

github-actions bot commented Jan 9, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MarcoGorelli left a comment

Choose a reason for hiding this comment

natmokval commented Jan 10, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

phofl Jan 12, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MarcoGorelli Jan 12, 2024 • edited

Choose a reason for hiding this comment

natmokval commented Dec 21, 2023 •

edited

natmokval commented Dec 28, 2023 •

edited

phofl Jan 12, 2024 •

edited

MarcoGorelli Jan 12, 2024 •

edited