BUG: inferred_freq is infers the wrong freq 2BQS-OCT instead of 2BQS-JAN

[MMCMA]

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

dates = pd.date_range('20151231', periods=500, freq='6BME',
                          unit='s') + pd.offsets.BDay(1)
inferred_freq = pd.Index(dates).inferred_freq

Issue Description

The code above, infers the wrong frequency, it should be 2BQS-JAN and not 2BQS-OCT

DatetimeIndex(['2016-01-01', '2016-07-01', '2017-01-02', '2017-07-03',
               '2018-01-01', '2018-07-02', '2019-01-01', '2019-07-01',
               '2020-01-01', '2020-07-01',
               ...
               '2261-01-01', '2261-07-01', '2262-01-01', '2262-07-01',
               '2263-01-01', '2263-07-01', '2264-01-01', '2264-07-01',
               '2265-01-02', '2265-07-03'],
              dtype='datetime64[s]', length=500, freq=None)
2BQS-OCT

Expected Behavior

2BQS-JAN should be the correct freq

Installed Versions

INSTALLED VERSIONS

commit : d9cdd2e
python : 3.12.4.final.0
python-bits : 64
OS : Windows
OS-release : 11
Version : 10.0.26100
machine : AMD64
processor : Intel64 Family 6 Model 186 Stepping 2, GenuineIntel
byteorder : little
LC_ALL : None
LANG : None
LOCALE : English_Switzerland.1252
pandas : 2.2.2
numpy : 1.26.4
pytz : 2024.1
dateutil : 2.9.0
setuptools : 72.1.0
pip : 24.2
Cython : 3.0.11
pytest : 8.3.2
hypothesis : None
sphinx : None
blosc : None
feather : None
xlsxwriter : 3.1.9
lxml.etree : 5.2.2
html5lib : 1.1
pymysql : None
psycopg2 : 2.9.9
jinja2 : 3.1.4
IPython : 8.21.0
pandas_datareader : 0.10.0
adbc-driver-postgresql: None
adbc-driver-sqlite : None
bs4 : 4.12.3
bottleneck : None
dataframe-api-compat : None
fastparquet : None
fsspec : 2024.6.1
gcsfs : None
matplotlib : 3.9.1
numba : 0.60.0
numexpr : 2.10.0
odfpy : None
openpyxl : 3.1.4
pandas_gbq : None
pyarrow : 17.0.0
pyreadstat : None
python-calamine : None
pyxlsb : None
s3fs : None
scipy : 1.13.1
sqlalchemy : 2.0.31
tables : 3.9.2
tabulate : 0.9.0
xarray : None
xlrd : 2.0.1
zstandard : 0.23.0
tzdata : 2024.1
qtpy : None
pyqt5 : None

[sanrishi]

Hey! @MMCMA I think I found the culprit for the BQS anchoring issue. 🎯

I traced it down to the mod_dict logic in pandas/tseries/frequencies.py (around line 325). Basically, the current mapping is misinterpreting the quarter start months. For example, if we have a January date (month=1), the calculation 1 % 3 is getting mapped to 10 (October) by mod_dict, which is why we’re seeing those incorrect aliases.

Since rep_stamp is already a representative date from the actual sequence (e.g., it's already a January date), we don't need the complex mapping. I found that simply swapping out the dictionary lookup for self.rep_stamp.month directly solves it and correctly identifies the anchor month.

I’ve verified this locally, and it seems to clear up the issue. I’d be happy to contribute a PR for this.

[rhshadrach]

Thanks for the report.

@sanrishi

Since rep_stamp is already a representative date from the actual sequence (e.g., it's already a January date), we don't need the complex mapping. I found that simply swapping out the dictionary lookup for self.rep_stamp.month directly solves it and correctly identifies the anchor month.

I don't think this is desirable behavior. I believe we want the inferred frequency to be the same regardless if the first date is January or July.

Perhaps we should have special consideration for when nquarters is even, in which case we use the later month of the year (July in the OP example). In general:

(m-1) % 6 + 7

where m is the month number.

cc @jbrockmendel

[sanrishi]

@rhshadrach The logic int(nquarters) % 2 == 0 is actually too broad and ends up causing collisions for 4BQS and 6BQS. While it works for 2BQS (6 months), it incorrectly assumes that every even-quarter frequency has that same 6-month symmetry.

For 4BQS, January and July are distinct starting points that shouldn't be canonicalized together. But because 4 is even, the condition passes, and your code maps both month 1 and month 7 to July. This means we'd lose the January start entirely and incorrectly infer everything as 4BQS-JUL. We need a more specific condition here so we don't accidentally mash these different frequencies into the same bucket.

[rhshadrach]

it incorrectly assumes that every even-quarter frequency has that same 6-month symmetry.

I believe something like 6BQS-OCT is to have a frequency that is 6 quarters, start of the month, and hits October (when the data extends far enough). Can you give an example that is incorrect?

[sanrishi]

YES, there IS a problem with your approach @rhshadrach IF the condition is nquarters % 2 == 0.
Annual business data (every 12 months) starting in January

Dates: [2016-01-01, 2017-01-01, 2018-01-01, 2019-01-01, 2020-01-01]

Infer as BYS-JAN or 4BQS-JAN

With nquarters % 2 == 0 condition:

• nquarters = 4 (12 months = 4 quarters)
• 4 % 2 = 0 in that condition is TRUE
• rep_month = 1 (January)
• formula: (1-1) % 6 + 7 = 7 (July)
• 4BQS-JUL will WRONG!

4BQS-JAN and 4BQS-JUL are different frequencies that hit different months. January annual data should infer as JAN, not JUL.

[rhshadrach]

Infer as BYS-JAN or 4BQS-JAN

What do you mean or? pandas checks for yearly prior to quarterly, this is indeed inferred as yearly.

dates = pd.date_range('20160101', periods=5, freq='12BMS', unit='s')
index = pd.Index(dates)
print(index.inferred_freq)
# BYS-JAN

[sanrishi]

Oh my fault @rhshadrach Thanks for clarification!
That is the difference b/w experienced and and non experienced
so the correct approach should be (m-1) % 6 + 7 maps to later month
right?

[jbrockmendel]

I'm too busy doomscrolling to dig into this, but IIRC the month (in this case OCT) denotes the month in which the period ends, not starts. I agree this is confusing.

One way to check if the inferred_freq is "wrong" is

off = pd.tseries.frequencies.to_offset(dates.inferred_freq)
assert all(off.is_on_offset(x) for x in dates)  # passes

If the inferred_freq were wrong, this assertion would raise, which it does not.