Skip to content

Commit c9a98f0

Browse files
natmokvalnatmokval
authored
DEPR: ‘AS’, ‘BA’ and ‘BAS’ in favour of ‘YS’, ‘BY’ and ‘BYS’ (#55479)
* deprecate AS/BA/BAS in favour of YS/BY/BYS, fix tests * correct def get_start_end_field, correct docstrings and v0.20.0.rst * fix pre-commit error * add deprecated frequencies to dict DEPR_ABBREVS, add tests
1 parent 943c3cb commit c9a98f0

File tree

23 files changed

+148
-67
lines changed

23 files changed

+148
-67
lines changed

Diff for: ‎doc/source/user_guide/timeseries.rst

+7-7
Original file line numberDiff line numberDiff line change
@@ -896,9 +896,9 @@ into ``freq`` keyword arguments. The available date offsets and associated frequ
896896
:class:`~pandas.tseries.offsets.BQuarterBegin`, ``'BQS'``, "business quarter begin"
897897
:class:`~pandas.tseries.offsets.FY5253Quarter`, ``'REQ'``, "retail (aka 52-53 week) quarter"
898898
:class:`~pandas.tseries.offsets.YearEnd`, ``'Y'``, "calendar year end"
899-
:class:`~pandas.tseries.offsets.YearBegin`, ``'AS'`` or ``'BYS'``,"calendar year begin"
900-
:class:`~pandas.tseries.offsets.BYearEnd`, ``'BA'``, "business year end"
901-
:class:`~pandas.tseries.offsets.BYearBegin`, ``'BAS'``, "business year begin"
899+
:class:`~pandas.tseries.offsets.YearBegin`, ``'YS'`` or ``'BYS'``,"calendar year begin"
900+
:class:`~pandas.tseries.offsets.BYearEnd`, ``'BY'``, "business year end"
901+
:class:`~pandas.tseries.offsets.BYearBegin`, ``'BYS'``, "business year begin"
902902
:class:`~pandas.tseries.offsets.FY5253`, ``'RE'``, "retail (aka 52-53 week) year"
903903
:class:`~pandas.tseries.offsets.Easter`, None, "Easter holiday"
904904
:class:`~pandas.tseries.offsets.BusinessHour`, ``'bh'``, "business hour"
@@ -1259,9 +1259,9 @@ frequencies. We will refer to these aliases as *offset aliases*.
12591259
"QS", "quarter start frequency"
12601260
"BQS", "business quarter start frequency"
12611261
"Y", "year end frequency"
1262-
"BA, BY", "business year end frequency"
1263-
"AS, YS", "year start frequency"
1264-
"BAS, BYS", "business year start frequency"
1262+
"BY", "business year end frequency"
1263+
"YS", "year start frequency"
1264+
"BYS", "business year start frequency"
12651265
"h", "hourly frequency"
12661266
"bh", "business hour frequency"
12671267
"cbh", "custom business hour frequency"
@@ -1692,7 +1692,7 @@ the end of the interval.
16921692
.. warning::
16931693

16941694
The default values for ``label`` and ``closed`` is '**left**' for all
1695-
frequency offsets except for 'ME', 'Y', 'Q', 'BM', 'BA', 'BQ', and 'W'
1695+
frequency offsets except for 'ME', 'Y', 'Q', 'BM', 'BY', 'BQ', and 'W'
16961696
which all have a default of 'right'.
16971697

16981698
This might unintendedly lead to looking ahead, where the value for a later

Diff for: ‎doc/source/whatsnew/v0.20.0.rst

+16-4
Original file line numberDiff line numberDiff line change
@@ -886,11 +886,23 @@ This would happen with a ``lexsorted``, but non-monotonic levels. (:issue:`15622
886886

887887
This is *unchanged* from prior versions, but shown for illustration purposes:
888888

889-
.. ipython:: python
889+
.. code-block:: python
890890
891-
df = pd.DataFrame(np.arange(6), columns=['value'],
892-
index=pd.MultiIndex.from_product([list('BA'), range(3)]))
893-
df
891+
In [81]: df = pd.DataFrame(np.arange(6), columns=['value'],
892+
....: index=pd.MultiIndex.from_product([list('BA'), range(3)]))
893+
....:
894+
In [82]: df
895+
896+
Out[82]:
897+
value
898+
B 0 0
899+
1 1
900+
2 2
901+
A 0 3
902+
1 4
903+
2 5
904+
905+
[6 rows x 1 columns]
894906
895907
.. code-block:: python
896908

Diff for: ‎pandas/_libs/tslibs/dtypes.pyx

+40-4
Original file line numberDiff line numberDiff line change
@@ -192,9 +192,6 @@ OFFSET_TO_PERIOD_FREQSTR: dict = {
192192
"BQS": "Q",
193193
"QS": "Q",
194194
"BQ": "Q",
195-
"BA": "Y",
196-
"AS": "Y",
197-
"BAS": "Y",
198195
"MS": "M",
199196
"D": "D",
200197
"B": "B",
@@ -205,9 +202,9 @@ OFFSET_TO_PERIOD_FREQSTR: dict = {
205202
"ns": "ns",
206203
"h": "h",
207204
"Q": "Q",
208-
"Y": "Y",
209205
"W": "W",
210206
"ME": "M",
207+
"Y": "Y",
211208
"BY": "Y",
212209
"YS": "Y",
213210
"BYS": "Y",
@@ -244,6 +241,45 @@ DEPR_ABBREVS: dict[str, str]= {
244241
"A-SEP": "Y-SEP",
245242
"A-OCT": "Y-OCT",
246243
"A-NOV": "Y-NOV",
244+
"BA": "BY",
245+
"BA-DEC": "BY-DEC",
246+
"BA-JAN": "BY-JAN",
247+
"BA-FEB": "BY-FEB",
248+
"BA-MAR": "BY-MAR",
249+
"BA-APR": "BY-APR",
250+
"BA-MAY": "BY-MAY",
251+
"BA-JUN": "BY-JUN",
252+
"BA-JUL": "BY-JUL",
253+
"BA-AUG": "BY-AUG",
254+
"BA-SEP": "BY-SEP",
255+
"BA-OCT": "BY-OCT",
256+
"BA-NOV": "BY-NOV",
257+
"AS": "YS",
258+
"AS-DEC": "YS-DEC",
259+
"AS-JAN": "YS-JAN",
260+
"AS-FEB": "YS-FEB",
261+
"AS-MAR": "YS-MAR",
262+
"AS-APR": "YS-APR",
263+
"AS-MAY": "YS-MAY",
264+
"AS-JUN": "YS-JUN",
265+
"AS-JUL": "YS-JUL",
266+
"AS-AUG": "YS-AUG",
267+
"AS-SEP": "YS-SEP",
268+
"AS-OCT": "YS-OCT",
269+
"AS-NOV": "YS-NOV",
270+
"BAS": "BYS",
271+
"BAS-DEC": "BYS-DEC",
272+
"BAS-JAN": "BYS-JAN",
273+
"BAS-FEB": "BYS-FEB",
274+
"BAS-MAR": "BYS-MAR",
275+
"BAS-APR": "BYS-APR",
276+
"BAS-MAY": "BYS-MAY",
277+
"BAS-JUN": "BYS-JUN",
278+
"BAS-JUL": "BYS-JUL",
279+
"BAS-AUG": "BYS-AUG",
280+
"BAS-SEP": "BYS-SEP",
281+
"BAS-OCT": "BYS-OCT",
282+
"BAS-NOV": "BYS-NOV",
247283
"H": "h",
248284
"BH": "bh",
249285
"CBH": "cbh",

Diff for: ‎pandas/_libs/tslibs/fields.pyx

+2-2
Original file line numberDiff line numberDiff line change
@@ -253,8 +253,8 @@ def get_start_end_field(
253253
# month of year. Other offsets use month, startingMonth as ending
254254
# month of year.
255255

256-
if (freqstr[0:2] in ["MS", "QS", "AS"]) or (
257-
freqstr[1:3] in ["MS", "QS", "AS"]):
256+
if (freqstr[0:2] in ["MS", "QS", "YS"]) or (
257+
freqstr[1:3] in ["MS", "QS", "YS"]):
258258
end_month = 12 if month_kw == 1 else month_kw - 1
259259
start_month = month_kw
260260
else:

Diff for: ‎pandas/_libs/tslibs/offsets.pyx

+9-12
Original file line numberDiff line numberDiff line change
@@ -2414,7 +2414,7 @@ cdef class BYearEnd(YearOffset):
24142414

24152415
_outputName = "BusinessYearEnd"
24162416
_default_month = 12
2417-
_prefix = "BA"
2417+
_prefix = "BY"
24182418
_day_opt = "business_end"
24192419

24202420

@@ -2453,7 +2453,7 @@ cdef class BYearBegin(YearOffset):
24532453

24542454
_outputName = "BusinessYearBegin"
24552455
_default_month = 1
2456-
_prefix = "BAS"
2456+
_prefix = "BYS"
24572457
_day_opt = "business_start"
24582458

24592459

@@ -2552,7 +2552,7 @@ cdef class YearBegin(YearOffset):
25522552
"""
25532553

25542554
_default_month = 1
2555-
_prefix = "AS"
2555+
_prefix = "YS"
25562556
_day_opt = "start"
25572557

25582558

@@ -4540,10 +4540,10 @@ CDay = CustomBusinessDay
45404540
prefix_mapping = {
45414541
offset._prefix: offset
45424542
for offset in [
4543-
YearBegin, # 'AS'
4543+
YearBegin, # 'YS'
45444544
YearEnd, # 'Y'
4545-
BYearBegin, # 'BAS'
4546-
BYearEnd, # 'BA'
4545+
BYearBegin, # 'BYS'
4546+
BYearEnd, # 'BY'
45474547
BusinessDay, # 'B'
45484548
BusinessMonthBegin, # 'BMS'
45494549
BusinessMonthEnd, # 'BM'
@@ -4584,12 +4584,9 @@ _lite_rule_alias = {
45844584
"Q": "Q-DEC",
45854585

45864586
"Y": "Y-DEC", # YearEnd(month=12),
4587-
"AS": "AS-JAN", # YearBegin(month=1),
4588-
"YS": "AS-JAN",
4589-
"BA": "BA-DEC", # BYearEnd(month=12),
4590-
"BY": "BA-DEC",
4591-
"BAS": "BAS-JAN", # BYearBegin(month=1),
4592-
"BYS": "BAS-JAN",
4587+
"YS": "YS-JAN", # YearBegin(month=1),
4588+
"BY": "BY-DEC", # BYearEnd(month=12),
4589+
"BYS": "BYS-JAN", # BYearBegin(month=1),
45934590

45944591
"Min": "min",
45954592
"min": "min",

Diff for: ‎pandas/core/arrays/arrow/array.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -2526,7 +2526,7 @@ def _round_temporally(
25262526
raise ValueError(f"Must specify a valid frequency: {freq}")
25272527
pa_supported_unit = {
25282528
"Y": "year",
2529-
"AS": "year",
2529+
"YS": "year",
25302530
"Q": "quarter",
25312531
"QS": "quarter",
25322532
"M": "month",

Diff for: ‎pandas/core/indexes/datetimes.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -992,11 +992,11 @@ def date_range(
992992
993993
**Specify a unit**
994994
995-
>>> pd.date_range(start="2017-01-01", periods=10, freq="100AS", unit="s")
995+
>>> pd.date_range(start="2017-01-01", periods=10, freq="100YS", unit="s")
996996
DatetimeIndex(['2017-01-01', '2117-01-01', '2217-01-01', '2317-01-01',
997997
'2417-01-01', '2517-01-01', '2617-01-01', '2717-01-01',
998998
'2817-01-01', '2917-01-01'],
999-
dtype='datetime64[s]', freq='100AS-JAN')
999+
dtype='datetime64[s]', freq='100YS-JAN')
10001000
"""
10011001
if freq is None and com.any_none(periods, start, end):
10021002
freq = "D"

Diff for: ‎pandas/core/resample.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -2101,7 +2101,7 @@ def __init__(
21012101
else:
21022102
freq = to_offset(freq)
21032103

2104-
end_types = {"ME", "Y", "Q", "BM", "BA", "BQ", "W"}
2104+
end_types = {"ME", "Y", "Q", "BM", "BY", "BQ", "W"}
21052105
rule = freq.rule_code
21062106
if rule in end_types or ("-" in rule and rule[: rule.find("-")] in end_types):
21072107
if closed is None:
@@ -2299,7 +2299,7 @@ def _adjust_bin_edges(
22992299

23002300
if self.freq.name in ("BM", "ME", "W") or self.freq.name.split("-")[0] in (
23012301
"BQ",
2302-
"BA",
2302+
"BY",
23032303
"Q",
23042304
"Y",
23052305
"W",

Diff for: ‎pandas/core/series.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -5729,7 +5729,7 @@ def to_timestamp(
57295729
2023-01-01 1
57305730
2024-01-01 2
57315731
2025-01-01 3
5732-
Freq: AS-JAN, dtype: int64
5732+
Freq: YS-JAN, dtype: int64
57335733
57345734
Using `freq` which is the offset that the Timestamps will have
57355735

Diff for: ‎pandas/tests/arithmetic/test_datetime64.py

+3-3
Original file line numberDiff line numberDiff line change
@@ -1594,7 +1594,7 @@ def test_dt64arr_add_sub_offset_array(
15941594
Timestamp("2016-04-01"),
15951595
Timestamp("2017-04-01"),
15961596
],
1597-
"AS-APR",
1597+
"YS-APR",
15981598
),
15991599
(
16001600
"__sub__",
@@ -1616,7 +1616,7 @@ def test_dt64arr_add_sub_offset_array(
16161616
Timestamp("2015-10-01"),
16171617
Timestamp("2016-10-01"),
16181618
],
1619-
"AS-OCT",
1619+
"YS-OCT",
16201620
),
16211621
],
16221622
)
@@ -1625,7 +1625,7 @@ def test_dti_add_sub_nonzero_mth_offset(
16251625
):
16261626
# GH 26258
16271627
tz = tz_aware_fixture
1628-
date = date_range(start="01 Jan 2014", end="01 Jan 2017", freq="AS", tz=tz)
1628+
date = date_range(start="01 Jan 2014", end="01 Jan 2017", freq="YS", tz=tz)
16291629
date = tm.box_expected(date, box_with_array, False)
16301630
mth = getattr(date, op)
16311631
result = mth(offset)

Diff for: ‎pandas/tests/frame/methods/test_to_timestamp.py

+5-5
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ def test_to_timestamp(self, frame_or_series):
4444
if frame_or_series is Series:
4545
assert result.name == "A"
4646

47-
exp_index = date_range("1/1/2001", end="1/1/2009", freq="AS-JAN")
47+
exp_index = date_range("1/1/2001", end="1/1/2009", freq="YS-JAN")
4848
result = obj.to_timestamp("D", "start")
4949
tm.assert_index_equal(result.index, exp_index)
5050

@@ -88,7 +88,7 @@ def test_to_timestamp_columns(self):
8888
tm.assert_index_equal(result.columns, exp_index)
8989
tm.assert_numpy_array_equal(result.values, df.values)
9090

91-
exp_index = date_range("1/1/2001", end="1/1/2009", freq="AS-JAN")
91+
exp_index = date_range("1/1/2001", end="1/1/2009", freq="YS-JAN")
9292
result = df.to_timestamp("D", "start", axis=1)
9393
tm.assert_index_equal(result.columns, exp_index)
9494

@@ -112,14 +112,14 @@ def test_to_timestamp_columns(self):
112112

113113
result1 = df.to_timestamp("5min", axis=1)
114114
result2 = df.to_timestamp("min", axis=1)
115-
expected = date_range("2001-01-01", "2009-01-01", freq="AS")
115+
expected = date_range("2001-01-01", "2009-01-01", freq="YS")
116116
assert isinstance(result1.columns, DatetimeIndex)
117117
assert isinstance(result2.columns, DatetimeIndex)
118118
tm.assert_numpy_array_equal(result1.columns.asi8, expected.asi8)
119119
tm.assert_numpy_array_equal(result2.columns.asi8, expected.asi8)
120120
# PeriodIndex.to_timestamp always use 'infer'
121-
assert result1.columns.freqstr == "AS-JAN"
122-
assert result2.columns.freqstr == "AS-JAN"
121+
assert result1.columns.freqstr == "YS-JAN"
122+
assert result2.columns.freqstr == "YS-JAN"
123123

124124
def test_to_timestamp_invalid_axis(self):
125125
index = period_range(freq="Y", start="1/1/2001", end="12/1/2009")

Diff for: ‎pandas/tests/groupby/test_grouping.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -734,7 +734,7 @@ def test_list_grouper_with_nat(self):
734734
# GH 14715
735735
df = DataFrame({"date": date_range("1/1/2011", periods=365, freq="D")})
736736
df.iloc[-1] = pd.NaT
737-
grouper = Grouper(key="date", freq="AS")
737+
grouper = Grouper(key="date", freq="YS")
738738

739739
# Grouper in a list grouping
740740
result = df.groupby([grouper])

Diff for: ‎pandas/tests/indexes/datetimes/methods/test_to_period.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ def test_to_period_quarterlyish(self, off):
5656
prng = rng.to_period()
5757
assert prng.freq == "Q-DEC"
5858

59-
@pytest.mark.parametrize("off", ["BA", "AS", "BAS"])
59+
@pytest.mark.parametrize("off", ["BY", "YS", "BYS"])
6060
def test_to_period_annualish(self, off):
6161
rng = date_range("01-Jan-2012", periods=8, freq=off)
6262
prng = rng.to_period()

Diff for: ‎pandas/tests/indexes/datetimes/test_constructors.py

+3-3
Original file line numberDiff line numberDiff line change
@@ -648,7 +648,7 @@ def test_constructor_coverage(self):
648648
with pytest.raises(ValueError, match=msg):
649649
date_range(periods=10, freq="D")
650650

651-
@pytest.mark.parametrize("freq", ["AS", "W-SUN"])
651+
@pytest.mark.parametrize("freq", ["YS", "W-SUN"])
652652
def test_constructor_datetime64_tzformat(self, freq):
653653
# see GH#6572: ISO 8601 format results in stdlib timezone object
654654
idx = date_range(
@@ -981,8 +981,8 @@ def test_dti_constructor_years_only(self, tz_naive_fixture):
981981
rng3 = date_range("2014", "2020", freq="Y", tz=tz)
982982
expected3 = date_range("2014-12-31", "2019-12-31", freq="Y", tz=tz)
983983

984-
rng4 = date_range("2014", "2020", freq="AS", tz=tz)
985-
expected4 = date_range("2014-01-01", "2020-01-01", freq="AS", tz=tz)
984+
rng4 = date_range("2014", "2020", freq="YS", tz=tz)
985+
expected4 = date_range("2014-01-01", "2020-01-01", freq="YS", tz=tz)
986986

987987
for rng, expected in [
988988
(rng1, expected1),

Diff for: ‎pandas/tests/indexes/datetimes/test_date_range.py

+6-8
Original file line numberDiff line numberDiff line change
@@ -243,13 +243,12 @@ def test_date_range_gen_error(self):
243243
rng = date_range("1/1/2000 00:00", "1/1/2000 00:18", freq="5min")
244244
assert len(rng) == 4
245245

246-
@pytest.mark.parametrize("freq", ["AS", "YS"])
247-
def test_begin_year_alias(self, freq):
246+
def test_begin_year_alias(self):
248247
# see gh-9313
249-
rng = date_range("1/1/2013", "7/1/2017", freq=freq)
248+
rng = date_range("1/1/2013", "7/1/2017", freq="YS")
250249
exp = DatetimeIndex(
251250
["2013-01-01", "2014-01-01", "2015-01-01", "2016-01-01", "2017-01-01"],
252-
freq=freq,
251+
freq="YS",
253252
)
254253
tm.assert_index_equal(rng, exp)
255254

@@ -261,12 +260,11 @@ def test_end_year_alias(self):
261260
)
262261
tm.assert_index_equal(rng, exp)
263262

264-
@pytest.mark.parametrize("freq", ["BA", "BY"])
265-
def test_business_end_year_alias(self, freq):
263+
def test_business_end_year_alias(self):
266264
# see gh-9313
267-
rng = date_range("1/1/2013", "7/1/2017", freq=freq)
265+
rng = date_range("1/1/2013", "7/1/2017", freq="BY")
268266
exp = DatetimeIndex(
269-
["2013-12-31", "2014-12-31", "2015-12-31", "2016-12-30"], freq=freq
267+
["2013-12-31", "2014-12-31", "2015-12-31", "2016-12-30"], freq="BY"
270268
)
271269
tm.assert_index_equal(rng, exp)
272270

0 commit comments

Comments
 (0)