QuarterBegin wrong date

[postelrich]

Would expect this to point to one of (1, 4, 7, 10)...

#### Code Sample, a copy-pastable example if possible
import pandas as pd
pd.Timestamp.today() - pd.tseries.offsets.QuarterBegin()
>Timestamp('2016-09-01 15:29:06.556269')

#### Expected Output
Timestamp('2016-07-01 15:29:06.556269')

#### output of ``pd.show_versions()``
In [4]: pd.show_versions()

INSTALLED VERSIONS
------------------
commit: None
python: 3.5.2.final.0
python-bits: 64
OS: Darwin
OS-release: 15.6.0
machine: x86_64
processor: i386
byteorder: little
LC_ALL: None
LANG: en_US.UTF-8

pandas: 0.18.1
nose: None
pip: 8.1.2
setuptools: 25.1.6
Cython: None
numpy: 1.11.1
scipy: None
statsmodels: None
xarray: None
IPython: 5.1.0
sphinx: None
patsy: None
dateutil: 2.5.3
pytz: 2016.6.1
blosc: None
bottleneck: None
tables: 3.2.3.1
numexpr: 2.6.1
matplotlib: None
openpyxl: None
xlrd: None
xlwt: None
xlsxwriter: None
lxml: None
bs4: None
html5lib: None
httplib2: None
apiclient: None
sqlalchemy: 1.0.13
pymysql: None
psycopg2: 2.6.2 (dt dec pq3 ext lo64)
jinja2: 2.8
boto: None
pandas_datareader: None

[jreback]

see comments here
and from the doc-string

Zero presents a problem.  Should it roll forward or back?  We
arbitrarily have it rollforward:

date + BDay(0) == BDay.rollforward(date)

In [7]: t = pd.Timestamp.today()

In [8]: t
Out[8]: Timestamp('2016-09-19 15:39:10.453763')

In [9]: t + pd.tseries.offsets.QuarterBegin()
Out[9]: Timestamp('2016-12-01 15:39:10.453763')

In [10]: t + pd.tseries.offsets.QuarterBegin(0)
Out[10]: Timestamp('2016-12-01 15:39:10.453763')

In [14]: t + pd.tseries.offsets.QuarterBegin(1)
Out[14]: Timestamp('2016-12-01 15:39:10.453763')

In [11]: t - pd.tseries.offsets.QuarterBegin()
Out[11]: Timestamp('2016-09-01 15:39:10.453763')

In [12]: t - pd.tseries.offsets.QuarterBegin(0)
Out[12]: Timestamp('2016-12-01 15:39:10.453763')

In [13]: t - pd.tseries.offsets.QuarterBegin(1)
Out[13]: Timestamp('2016-09-01 15:39:10.453763')

[postelrich]

I don't see how that explains why QuarterBegin is rolling to months 9 and 12 instead of 7 and 10.

[TomAugspurger]

This comment is suggestive. That git blame is just from a reorganization, not the actual commit :/

[jreback]

actually this issue was raised before, see: #13644

[jreback]

cc @chris-b1

[jreback]

and better doc pointer here (though this is just for months, quarter is the same)

[chris-b1]

The default anchor month for QuarterBegin is 3 (6, 9, 12). It sounds like you want it anchored at 1, if so, use the startingMonth keyword arg. Docs could be better here.

qtr = pd.tseries.offsets.QuarterBegin(startingMonth=1)

pd.Timestamp.today() - qtr
Out[13]: Timestamp('2016-07-01 16:06:23.581744')

[postelrich]

@chris-b1 thanks for that.

I would think that should be the default behavior. I remember reading in a related issue that some countries financials start in March. But if January is the anchor month that the majority of users expect / think of when they hear quarterly, it should be that. The startingMonth=3 seems only relevant for some financial situations while startingMonth=1 seems like it would be the default everywhere else.

[chris-b1]

There is an open issue for that, #8435, and I agree startingMonth=1 is a more sensible default, but would need to deprecate before changing.

[jreback]

actually let's put in a deprecation for 0.20 as in #8435

though not sure exactly how to do that unless we always warn if no parameter is passed (but that might be annoying)

[postelrich]

@jreback don't think there is a way avoid being annoying and that's probably the point so people actually notice it and update their code. They can always filter the warning or turn off warnings altogether.

[jreback]

@postelrich the issue is back-compat. We can either warn everyone (whom does not specify a default), or NOT have back-compat, with potential for breaking code. Not everyone (well maybe most, dont' read the documentation), or take the time to test their code for changes. This can be a very subtle change that still works, but in a subtle way. We really really try to avoid these types of changes.

sure people can filter warnings, but they don't

[postelrich]

@jreback yea I see your point about backwards compatibility, not that I know much about the versioning for pandas, but this isn't even at a 1.0 yet. I would vote for changing it to what the expected behavior is to avoid future confusion.

At a minimum, the docs should be updated for the next release to clarify the default behavior and the optional arguments available to modify it.

[jreback]

@postelrich pandas goes out of its way to avoid breaking back-compat (at sometimes lots work). 1.0 has nothing to do with this.

[postelrich]

@jreback another potential issue but maybe should be a separate ticket.

pd.Timestamp('2016-01-01') - pd.tseries.offsets.QuarterBegin(startingMonth=1)

Timestamp('2015-10-01 00:00:00')

If you're already at the quarter begin, shouldn't it just return itself?

[chris-b1]

Those are the defined semantics - n=1 always rolls forward.
http://pandas.pydata.org/pandas-docs/stable/timeseries.html#anchored-offset-semantics