DOC: hour/hours (and other plurals) based on dateutil.relativedelta

[jreback]

discovered in #5292

This seems odd to me, documented anywhere?

In [2]: t = pd.Timestamp('2014-06-10 8am')

In [3]: t + pd.DateOffset(hour=9)
Out[3]: Timestamp('2014-06-10 09:00:00', tz=None)

In [4]: t + pd.DateOffset(hours=9)
Out[4]: Timestamp('2014-06-10 17:00:00', tz=None)

note that

t + pd.offsets.Hour(9) == t + timedelta(hours=9)

so this definitly seems suspect

(also problematic for second/seconds and minute/minutes)

this is only an issue in DateOffset constructions.

[jreback]

cc @rockg
cc @cancan101
cc @adamgreenhall

[adamgreenhall]

I think this behavior is inherited from dateutil.relativedelta, which mentions it in passing in the documentation:

year, month, day, hour, minute, second, microsecond
    Absolute information.
years, months, weeks, days, hours, minutes, seconds, microseconds
    Relative information, may be negative.

I actually do use the singular form and don't find it to be a bug. My most common use case is getting the current business week, starting on Monday at 5am:
pd.Timestamp('now') + pd.DateOffset(weekday=0, hour=5)

[dsm054]

Blek. That's an awfully big behavioural difference to hang on the letter s.

[jreback]

I think a method call is appropriate here, this is essentially replace.

e.g.

t.replace(pd.DateOffset(weekday=0,hour=5)) or t.replace(pd.DateOffset(weekday=0,hours=5))

should IMHO do the same thing (and not be sensitive to hour/hours

then

t + pd.DateOffset(hour=5) == t + pd.DateOffset(hours=5) == t + timedelta(hours=5) == t + pd.offsets.Hour(5)

[jreback]

@cpcloud @jorisvandenbossche @jseabold

[rockg]

I agree that the difference is naming is subtle but it's obvious what is going on when somebody actually tries to use the singular versus plural constructs. I think both behaviors are necessary so I think one approach here is to leave it as is and provide more documentation as to what is actually going on. But I think we have two alternatives:

1. Given the issues that are being fixed in BUG: DateOffset weekday around DST produces unexpected results #5175/BUG: DateOffset weekday around DST produces unexpected results. fixes #5175 #5292 I would be in favor of deprecating the plural in favor of using the pandas offsets. What would be nice here is to have a MultiDateOffset that could combine many offsets: MultiDateOffset(Day(1), Hour(5), Minute(20)). We would need to deprecate the plural rather than just change the behavior and I think this avoids pitfalls when using relativedelta offsets when it comes to timezones.
2. Blacklist the singular offsets and force people to use replace. It looks like this is what relativedelta does in its code.

I'm personally in favor of (1) because it will fix issues people may or may not know they are having with applying offsets that straddle daylight savings changes.

[jreback]

Isn't this what you mean by MultiDateOffset?

In [4]: from pandas.tseries.frequencies import to_offset

In [5]: to_offset('1T 30s')
Out[5]: <90 * Seconds>

In [6]: to_offset('1D 1T 30s')
Out[6]: <86490 * Seconds>

[jreback]

moving this to 0.15.0 in order to make a deprecating change

[jreback]

going to defer this. Still not sure what to do about it.

[mroeschke]

Our internal logic on which keywords to dispatch to dateutil.relativedelta is fairly complex that it will be fairly difficult to deprecate this. I think it's best that we reference the dateutil documentation between the singular and plural form

https://dateutil.readthedocs.io/en/stable/relativedelta.html