Skip to content

DEPR: 'A' for yearly frequency and YearEnd in favour of 'Y' #55252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Oct 6, 2023
Merged

DEPR: 'A' for yearly frequency and YearEnd in favour of 'Y' #55252

Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
f87ddbe
deprecate A in favour of Y, fix tests
natmokval Sep 22, 2023
7b0b956
correct offset related functions in frequencies.py, fix tests
natmokval Sep 22, 2023
ec6d3d9
correct docstrings and user_guide
natmokval Sep 22, 2023
606ebba
fix pre-commit error
natmokval Sep 22, 2023
1f10870
fix test in benchmarks
natmokval Sep 23, 2023
0dea433
add dictionary OFFSET_DEPR_FREQSTR, change warning msg
natmokval Sep 26, 2023
4498d87
Merge branch 'main' into depr-A-for-Year
natmokval Sep 26, 2023
dbd1da3
fix pre-commit errors
natmokval Sep 26, 2023
935280e
correct cpdef to_offset, add tests for warning
natmokval Sep 27, 2023
fd36bc7
Merge branch 'main' into depr-A-for-Year
natmokval Sep 27, 2023
9268a9b
replace A with Y in _adjust_bin_edges
natmokval Sep 27, 2023
9a383cd
add to dict DEPR_ABBREVS annual freqs with various fiscal year ends, …
natmokval Sep 28, 2023
ab0d6a6
add notes to whatsnew/v2.2.0.rst
natmokval Sep 29, 2023
4f91f7f
change the message for UserWarning, correct annual frequencies in tim…
natmokval Oct 2, 2023
31e0bf0
correct the order of checks in to_offset, add a tests for timedelta
natmokval Oct 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion asv_bench/benchmarks/tslibs/period.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ def time_now(self, freq):
self.per.now(freq)

def time_asfreq(self, freq):
self.per.asfreq("A")
self.per.asfreq("Y")

def time_str(self, freq):
str(self.per)
Expand Down
2 changes: 1 addition & 1 deletion doc/source/user_guide/io.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2332,7 +2332,7 @@ A few notes on the generated table schema:

.. ipython:: python

s_per = pd.Series(1, index=pd.period_range("2016", freq="A-DEC", periods=4))
s_per = pd.Series(1, index=pd.period_range("2016", freq="Y-DEC", periods=4))
build_table_schema(s_per)

* Categoricals use the ``any`` type and an ``enum`` constraint listing
Expand Down
26 changes: 13 additions & 13 deletions doc/source/user_guide/timeseries.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -895,7 +895,7 @@ into ``freq`` keyword arguments. The available date offsets and associated frequ
:class:`~pandas.tseries.offsets.BQuarterEnd`, ``'BQ``, "business quarter end"
:class:`~pandas.tseries.offsets.BQuarterBegin`, ``'BQS'``, "business quarter begin"
:class:`~pandas.tseries.offsets.FY5253Quarter`, ``'REQ'``, "retail (aka 52-53 week) quarter"
:class:`~pandas.tseries.offsets.YearEnd`, ``'A'``, "calendar year end"
:class:`~pandas.tseries.offsets.YearEnd`, ``'Y'``, "calendar year end"
:class:`~pandas.tseries.offsets.YearBegin`, ``'AS'`` or ``'BYS'``,"calendar year begin"
:class:`~pandas.tseries.offsets.BYearEnd`, ``'BA'``, "business year end"
:class:`~pandas.tseries.offsets.BYearBegin`, ``'BAS'``, "business year begin"
Expand Down Expand Up @@ -1258,7 +1258,7 @@ frequencies. We will refer to these aliases as *offset aliases*.
"BQ", "business quarter end frequency"
"QS", "quarter start frequency"
"BQS", "business quarter start frequency"
"A, Y", "year end frequency"
"Y", "year end frequency"
"BA, BY", "business year end frequency"
"AS, YS", "year start frequency"
"BAS, BYS", "business year start frequency"
Expand Down Expand Up @@ -1321,7 +1321,7 @@ frequencies. We will refer to these aliases as *period aliases*.
"W", "weekly frequency"
"M", "monthly frequency"
"Q", "quarterly frequency"
"A, Y", "yearly frequency"
"Y", "yearly frequency"
"H", "hourly frequency"
"min", "minutely frequency"
"s", "secondly frequency"
Expand All @@ -1331,8 +1331,8 @@ frequencies. We will refer to these aliases as *period aliases*.

.. deprecated:: 2.2.0

Aliases ``T``, ``S``, ``L``, ``U``, and ``N`` are deprecated in favour of the aliases
``min``, ``s``, ``ms``, ``us``, and ``ns``.
Aliases ``A``, ``T``, ``S``, ``L``, ``U``, and ``N`` are deprecated in favour of the aliases
``Y``, ``min``, ``s``, ``ms``, ``us``, and ``ns``.


Combining aliases
Expand Down Expand Up @@ -1383,7 +1383,7 @@ For some frequencies you can specify an anchoring suffix:
"(B)Q(S)\-SEP", "quarterly frequency, year ends in September"
"(B)Q(S)\-OCT", "quarterly frequency, year ends in October"
"(B)Q(S)\-NOV", "quarterly frequency, year ends in November"
"(B)A(S)\-DEC", "annual frequency, anchored end of December. Same as 'A'"
"(B)A(S)\-DEC", "annual frequency, anchored end of December. Same as 'Y'"
"(B)A(S)\-JAN", "annual frequency, anchored end of January"
"(B)A(S)\-FEB", "annual frequency, anchored end of February"
"(B)A(S)\-MAR", "annual frequency, anchored end of March"
Expand Down Expand Up @@ -1690,7 +1690,7 @@ the end of the interval.
.. warning::

The default values for ``label`` and ``closed`` is '**left**' for all
frequency offsets except for 'ME', 'A', 'Q', 'BM', 'BA', 'BQ', and 'W'
frequency offsets except for 'ME', 'Y', 'Q', 'BM', 'BA', 'BQ', and 'W'
which all have a default of 'right'.

This might unintendedly lead to looking ahead, where the value for a later
Expand Down Expand Up @@ -1995,7 +1995,7 @@ Because ``freq`` represents a span of ``Period``, it cannot be negative like "-3

.. ipython:: python

pd.Period("2012", freq="A-DEC")
pd.Period("2012", freq="Y-DEC")

pd.Period("2012-1-1", freq="D")

Expand All @@ -2008,7 +2008,7 @@ frequency. Arithmetic is not allowed between ``Period`` with different ``freq``

.. ipython:: python

p = pd.Period("2012", freq="A-DEC")
p = pd.Period("2012", freq="Y-DEC")
p + 1
p - 3
p = pd.Period("2012-01", freq="2M")
Expand Down Expand Up @@ -2050,7 +2050,7 @@ return the number of frequency units between them:

.. ipython:: python

pd.Period("2012", freq="A-DEC") - pd.Period("2002", freq="A-DEC")
pd.Period("2012", freq="Y-DEC") - pd.Period("2002", freq="Y-DEC")

PeriodIndex and period_range
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -2184,7 +2184,7 @@ method. Let's start with the fiscal year 2011, ending in December:

.. ipython:: python

p = pd.Period("2011", freq="A-DEC")
p = pd.Period("2011", freq="Y-DEC")
p

We can convert it to a monthly frequency. Using the ``how`` parameter, we can
Expand All @@ -2211,10 +2211,10 @@ input period:

p = pd.Period("2011-12", freq="M")

p.asfreq("A-NOV")
p.asfreq("Y-NOV")

Note that since we converted to an annual frequency that ends the year in
November, the monthly period of December 2011 is actually in the 2012 A-NOV
November, the monthly period of December 2011 is actually in the 2012 Y-NOV
period.

.. _timeseries.quarterly:
Expand Down
1 change: 1 addition & 0 deletions doc/source/whatsnew/v2.2.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,7 @@ Other Deprecations
- Deprecated downcasting behavior in :meth:`Series.where`, :meth:`DataFrame.where`, :meth:`Series.mask`, :meth:`DataFrame.mask`, :meth:`Series.clip`, :meth:`DataFrame.clip`; in a future version these will not infer object-dtype columns to non-object dtype, or all-round floats to integer dtype. Call ``result.infer_objects(copy=False)`` on the result for object inference, or explicitly cast floats to ints. To opt in to the future version, use ``pd.set_option("future.no_silent_downcasting", True)`` (:issue:`53656`)
- Deprecated including the groups in computations when using :meth:`DataFrameGroupBy.apply` and :meth:`DataFrameGroupBy.resample`; pass ``include_groups=False`` to exclude the groups (:issue:`7155`)
- Deprecated not passing a tuple to :class:`DataFrameGroupBy.get_group` or :class:`SeriesGroupBy.get_group` when grouping by a length-1 list-like (:issue:`25971`)
- Deprecated string ``A`` denoting frequency in :class:`YearEnd` and strings ``A-DEC``, ``A-JAN``, etc. denoting annual frequencies with various fiscal year ends (:issue:`52536`)
- Deprecated strings ``S``, ``U``, and ``N`` denoting units in :func:`to_timedelta` (:issue:`52536`)
- Deprecated strings ``T``, ``S``, ``L``, ``U``, and ``N`` denoting frequencies in :class:`Minute`, :class:`Second`, :class:`Milli`, :class:`Micro`, :class:`Nano` (:issue:`52536`)
- Deprecated strings ``T``, ``S``, ``L``, ``U``, and ``N`` denoting units in :class:`Timedelta` (:issue:`52536`)
Expand Down
2 changes: 2 additions & 0 deletions pandas/_libs/tslibs/dtypes.pxd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ cpdef bint is_supported_unit(NPY_DATETIMEUNIT reso)

cpdef freq_to_period_freqstr(freq_n, freq_name)
cdef dict c_OFFSET_TO_PERIOD_FREQSTR
cdef dict c_OFFSET_DEPR_FREQSTR
cdef dict c_REVERSE_OFFSET_DEPR_FREQSTR
cdef dict c_DEPR_ABBREVS
cdef dict attrname_to_abbrevs
cdef dict npy_unit_to_attrname
Expand Down
1 change: 1 addition & 0 deletions pandas/_libs/tslibs/dtypes.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ from pandas._libs.tslibs.timedeltas import UnitChoices
_attrname_to_abbrevs: dict[str, str]
_period_code_map: dict[str, int]
OFFSET_TO_PERIOD_FREQSTR: dict[str, str]
OFFSET_DEPR_FREQSTR: dict[str, str]
DEPR_ABBREVS: dict[str, UnitChoices]

def periods_per_day(reso: int) -> int: ...
Expand Down
68 changes: 43 additions & 25 deletions pandas/_libs/tslibs/dtypes.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,19 +101,19 @@ cdef class PeriodDtypeBase:

_period_code_map = {
# Annual freqs with various fiscal year ends.
# eg, 2005 for A-FEB runs Mar 1, 2004 to Feb 28, 2005
"A-DEC": PeriodDtypeCode.A_DEC, # Annual - December year end
"A-JAN": PeriodDtypeCode.A_JAN, # Annual - January year end
"A-FEB": PeriodDtypeCode.A_FEB, # Annual - February year end
"A-MAR": PeriodDtypeCode.A_MAR, # Annual - March year end
"A-APR": PeriodDtypeCode.A_APR, # Annual - April year end
"A-MAY": PeriodDtypeCode.A_MAY, # Annual - May year end
"A-JUN": PeriodDtypeCode.A_JUN, # Annual - June year end
"A-JUL": PeriodDtypeCode.A_JUL, # Annual - July year end
"A-AUG": PeriodDtypeCode.A_AUG, # Annual - August year end
"A-SEP": PeriodDtypeCode.A_SEP, # Annual - September year end
"A-OCT": PeriodDtypeCode.A_OCT, # Annual - October year end
"A-NOV": PeriodDtypeCode.A_NOV, # Annual - November year end
# eg, 2005 for Y-FEB runs Mar 1, 2004 to Feb 28, 2005
"Y-DEC": PeriodDtypeCode.A_DEC, # Annual - December year end
"Y-JAN": PeriodDtypeCode.A_JAN, # Annual - January year end
"Y-FEB": PeriodDtypeCode.A_FEB, # Annual - February year end
"Y-MAR": PeriodDtypeCode.A_MAR, # Annual - March year end
"Y-APR": PeriodDtypeCode.A_APR, # Annual - April year end
"Y-MAY": PeriodDtypeCode.A_MAY, # Annual - May year end
"Y-JUN": PeriodDtypeCode.A_JUN, # Annual - June year end
"Y-JUL": PeriodDtypeCode.A_JUL, # Annual - July year end
"Y-AUG": PeriodDtypeCode.A_AUG, # Annual - August year end
"Y-SEP": PeriodDtypeCode.A_SEP, # Annual - September year end
"Y-OCT": PeriodDtypeCode.A_OCT, # Annual - October year end
"Y-NOV": PeriodDtypeCode.A_NOV, # Annual - November year end

# Quarterly frequencies with various fiscal year ends.
# eg, Q42005 for Q-OCT runs Aug 1, 2005 to Oct 31, 2005
Expand Down Expand Up @@ -156,22 +156,22 @@ _reverse_period_code_map = {
# Yearly aliases; careful not to put these in _reverse_period_code_map
_period_code_map.update({"Y" + key[1:]: _period_code_map[key]
for key in _period_code_map
if key.startswith("A-")})
if key.startswith("Y-")})

_period_code_map.update({
"Q": 2000, # Quarterly - December year end (default quarterly)
"A": PeriodDtypeCode.A, # Annual
"Y": PeriodDtypeCode.A, # Annual
"W": 4000, # Weekly
"C": 5000, # Custom Business Day
})

cdef set _month_names = {
x.split("-")[-1] for x in _period_code_map.keys() if x.startswith("A-")
x.split("-")[-1] for x in _period_code_map.keys() if x.startswith("Y-")
}

# Map attribute-name resolutions to resolution abbreviations
_attrname_to_abbrevs = {
"year": "A",
"year": "Y",
"quarter": "Q",
"month": "M",
"day": "D",
Expand All @@ -192,9 +192,9 @@ OFFSET_TO_PERIOD_FREQSTR: dict = {
"BQS": "Q",
"QS": "Q",
"BQ": "Q",
"BA": "A",
"AS": "A",
"BAS": "A",
"BA": "Y",
"AS": "Y",
"BAS": "Y",
"MS": "M",
"D": "D",
"B": "B",
Expand All @@ -205,15 +205,19 @@ OFFSET_TO_PERIOD_FREQSTR: dict = {
"ns": "ns",
"H": "H",
"Q": "Q",
"A": "A",
"Y": "Y",
"W": "W",
"ME": "M",
"Y": "A",
"BY": "A",
"YS": "A",
"BYS": "A",
"BY": "Y",
"YS": "Y",
"BYS": "Y",
}
OFFSET_DEPR_FREQSTR: dict[str, str]= {
"M": "ME",
}
cdef dict c_OFFSET_TO_PERIOD_FREQSTR = OFFSET_TO_PERIOD_FREQSTR
cdef dict c_OFFSET_DEPR_FREQSTR = OFFSET_DEPR_FREQSTR
cdef dict c_REVERSE_OFFSET_DEPR_FREQSTR = {v: k for k, v in OFFSET_DEPR_FREQSTR.items()}

cpdef freq_to_period_freqstr(freq_n, freq_name):
if freq_n == 1:
Expand All @@ -226,6 +230,20 @@ cpdef freq_to_period_freqstr(freq_n, freq_name):

# Map deprecated resolution abbreviations to correct resolution abbreviations
DEPR_ABBREVS: dict[str, str]= {
"A": "Y",
"a": "Y",
"A-DEC": "Y-DEC",
"A-JAN": "Y-JAN",
"A-FEB": "Y-FEB",
"A-MAR": "Y-MAR",
"A-APR": "Y-APR",
"A-MAY": "Y-MAY",
"A-JUN": "Y-JUN",
"A-JUL": "Y-JUL",
"A-AUG": "Y-AUG",
"A-SEP": "Y-SEP",
"A-OCT": "Y-OKT",
"A-NOV": "Y-NOV",
"T": "min",
"t": "min",
"S": "s",
Expand Down
52 changes: 28 additions & 24 deletions pandas/_libs/tslibs/offsets.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ from cpython.datetime cimport (
time as dt_time,
timedelta,
)

import warnings

import_datetime()
Expand Down Expand Up @@ -48,7 +49,6 @@ from pandas._libs.tslibs.ccalendar import (
)
from pandas.util._exceptions import find_stack_level


from pandas._libs.tslibs.ccalendar cimport (
dayofweek,
get_days_in_month,
Expand All @@ -58,6 +58,8 @@ from pandas._libs.tslibs.ccalendar cimport (
from pandas._libs.tslibs.conversion cimport localize_pydatetime
from pandas._libs.tslibs.dtypes cimport (
c_DEPR_ABBREVS,
c_OFFSET_DEPR_FREQSTR,
c_REVERSE_OFFSET_DEPR_FREQSTR,
periods_per_day,
)
from pandas._libs.tslibs.nattype cimport (
Expand Down Expand Up @@ -2496,7 +2498,7 @@ cdef class YearEnd(YearOffset):
"""

_default_month = 12
_prefix = "A"
_prefix = "Y"
_day_opt = "end"

cdef readonly:
Expand Down Expand Up @@ -4447,7 +4449,7 @@ prefix_mapping = {
offset._prefix: offset
for offset in [
YearBegin, # 'AS'
YearEnd, # 'A'
YearEnd, # 'Y'
BYearBegin, # 'BAS'
BYearEnd, # 'BA'
BusinessDay, # 'B'
Expand Down Expand Up @@ -4489,8 +4491,7 @@ _lite_rule_alias = {
"W": "W-SUN",
"Q": "Q-DEC",

"A": "A-DEC", # YearEnd(month=12),
"Y": "A-DEC",
"Y": "Y-DEC", # YearEnd(month=12),
"AS": "AS-JAN", # YearBegin(month=1),
"YS": "AS-JAN",
"BA": "BA-DEC", # BYearEnd(month=12),
Expand Down Expand Up @@ -4615,21 +4616,22 @@ cpdef to_offset(freq, bint is_period=False):

tups = zip(split[0::4], split[1::4], split[2::4])
for n, (sep, stride, name) in enumerate(tups):
if is_period is False and name == "M":
if is_period is False and name in c_OFFSET_DEPR_FREQSTR:
warnings.warn(
"\'M\' will be deprecated, please use \'ME\' "
"for \'month end\'",
f"\'{name}\' will be deprecated, please use "
f"\'{c_OFFSET_DEPR_FREQSTR.get(name)}\' for Offsets.",
UserWarning,
stacklevel=find_stack_level(),
)
name = "ME"
if is_period is True and name == "ME":
name = c_OFFSET_DEPR_FREQSTR[name]
if is_period is True and name in c_REVERSE_OFFSET_DEPR_FREQSTR:
raise ValueError(
r"for Period, please use \'M\' "
"instead of \'ME\'"
f"for Period, please use "
f"\'{c_REVERSE_OFFSET_DEPR_FREQSTR.get(name)}\' "
f"instead of \'{name}\'"
)
elif is_period is True and name == "M":
name = "ME"
elif is_period is True and name in c_OFFSET_DEPR_FREQSTR:
name = c_OFFSET_DEPR_FREQSTR.get(name)

if sep != "" and not sep.isspace():
raise ValueError("separator must be spaces")
Expand All @@ -4639,15 +4641,6 @@ cpdef to_offset(freq, bint is_period=False):
if not stride:
stride = 1

if prefix in c_DEPR_ABBREVS:
warnings.warn(
f"\'{prefix}\' is deprecated and will be removed in a "
f"future version. Please use \'{c_DEPR_ABBREVS.get(prefix)}\' "
f"instead of \'{prefix}\'.",
FutureWarning,
stacklevel=find_stack_level(),
)
prefix = c_DEPR_ABBREVS[prefix]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same as in the other PR, it's not clear to me why this moved down - could you explain please?

Copy link
Contributor Author

@natmokval natmokval Oct 3, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

because I wanted to keep this together with line 4668: offset = _get_offset(prefix) where we use this prefix. There is no need to do it, I can move it back.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah that might be better - wouldn't we risk missing the if prefix in {"D", "H", "min", "s", "ms", "us", "ns"}: like this?

Copy link
Contributor Author

@natmokval natmokval Oct 3, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm, I agree, we might have problems if frequency is 'T', 'S', 'L', 'U', or 'N'. Maybe we should check
if prefix in c_DEPR_ABBREVS: before we are doing if prefix in {"D", "H", "min", "s", "ms", "us", "ns"}:
I will update my PR

Copy link
Contributor Author

@natmokval natmokval Oct 4, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I moved the check if prefix in c_DEPR_ABBREVS: back to line 4642 and added a test that fails if the order of the checks isn't correct.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added a test that fails if the order of the checks isn't correct.

this is music to my ears - well done!

if prefix in {"D", "H", "min", "s", "ms", "us", "ns"}:
# For these prefixes, we have something like "3H" or
# "2.5T", so we can construct a Timedelta with the
Expand All @@ -4660,8 +4653,19 @@ cpdef to_offset(freq, bint is_period=False):
# into the offset
offset *= stride_sign
else:
if prefix in c_DEPR_ABBREVS:
warnings.warn(
f"\'{prefix}\' is deprecated and will be removed "
f"in a future version. Please use "
f"\'{c_DEPR_ABBREVS.get(prefix)}\' "
f"instead of \'{prefix}\'.",
FutureWarning,
stacklevel=find_stack_level(),
)
prefix = c_DEPR_ABBREVS[prefix]

stride = int(stride)
offset = _get_offset(name)
offset = _get_offset(prefix)
offset = offset * int(np.fabs(stride) * stride_sign)

if delta is None:
Expand Down
2 changes: 1 addition & 1 deletion pandas/_libs/tslibs/timestamps.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1249,7 +1249,7 @@ cdef class _Timestamp(ABCTimestamp):
>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651')
>>> # Year end frequency
>>> ts.to_period(freq='Y')
Period('2020', 'A-DEC')
Period('2020', 'Y-DEC')

>>> # Month end frequency
>>> ts.to_period(freq='M')
Expand Down
Loading