ENH/API: Decide what to return Period - Period subtraction

[sinhrks]

Code Sample, a copy-pastable example if possible

Split from #13071. Currently it returns int and loses freq info.

pd.Period('2011-03', freq='M') - pd.Period('2011-01', freq='M') 
#2

Expected Output

Current ideas are:

1. Return Timedelta adding support of Monthly freq.
2. Return Perioddelta newly created.
3. Return DateOffset.

output of pd.show_versions()

on current master.

CC: @jreback @MaximilianR

[shoyer]

I don't think we want to add other units like months to Timedelta without a full overhauling of time units.

I also don't think we want to add a new PeriodDelta type.

So I guess that leaves returns DateOffsets. Are there any differences of Periods that could not be represented with DateOffsets? The other reasonable choice is to simply raise a TypeError.

[jreback]

I don't think we want to add other units like months to Timedelta without a full overhauling of time units.

I am not sure this will work, but what is the issue here

[jorisvandenbossche]

I don't think we want to add other units like months to Timedelta without a full overhauling of time units.

I am not sure this will work, but what is the issue here

A month has not a well defined length, so does not fit in the current concept of Timedelta's.

@sinhrks Do you want to do this for 0.19? (changing to DateOffset, if possible) Or push to next release?

[dhirschfeld]

I'm not sure I understand what the problem is here - I like the fact that it returns an int. You know what the implied freq is anyway so I don't see much of an issue with losing the freq info.

In [8]: p0 = pd.Period('2011-01', freq='M')
   ...: p1 = pd.Period('2011-03', freq='M')

In [9]: dt = p1 - p0

In [10]: assert p1 == p0 + dt

I suppose there's a type-safety argument to be made in that you could prevent a PeriodDelta('2M') from being added to a PeriodIndex of a different frequency, but I just don't see that ever really happening in practice and whatever benefit that brings has to be weighted against the increased api size and maintenance burden.

FWIW the old scikits.timeseries simply returned ints for the difference and that worked well in practice... for me at least.

[dhirschfeld]

It would also be nice if you could subtract PeriodIndexes and get an array of ints:

In [14]: periods = pd.period_range('01-Jan-2017', '01-Jan-2020', freq='Q')

In [15]: periods - periods
Traceback (most recent call last):

  File "<ipython-input-15-5a6917b72e26>", line 1, in <module>
    periods - periods

  File "C:\Python\lib\site-packages\pandas\tseries\base.py", line 658, in __sub__
    typ2=type(other).__name__))

TypeError: cannot subtract PeriodIndex and PeriodIndex

[jreback]

@dhirschfeld as indicated above, returning an array (or scalar) of DateOffsets is the only solution here. Integers are the result of the implementation leaking thru here.