DEPR: remove freq attribute of Timestamp?

[jreback]

xref #15141 (comment)

In theory these should be completely fungible. If so, we should remove the freq attribute
of Timestamps and instead return Periods in those instances.

In [2]: t = Timestamp('2010-01-03 00:00:00', freq='W-SUN')

In [3]: t
Out[3]: Timestamp('2010-01-03 00:00:00', freq='W-SUN')

In [4]: t.to_period()
Out[4]: Period('2009-12-28/2010-01-03', 'W-SUN')

In [5]: t.to_period().to_timestamp(how='start')
Out[5]: Timestamp('2009-12-28 00:00:00')

In [6]: t.to_period().to_timestamp(how='end')
Out[6]: Timestamp('2010-01-03 00:00:00')

[jreback]

cc @jimbasquiat
@sinhrks
@MaximilianR

[jorisvandenbossche]

Is this something we actually want? (if it was possible)
Because to be concrete, a situation where timestamps with freq are created is in resample. Would you want to change the return value of resample to have a PeriodIndex instead of DatetimeIndex? That would be a big change.
Or would you just want to change when you access a scalar value and get a Timestamp object, to change this in a Period object if the timestamp has a freq ? But then you would be getting Periods out of a DatetimeIndex with freq, which seems not very consistent.

[jreback]

regular

In [20]: pd.date_range('20130101',periods=3)
Out[20]: DatetimeIndex(['2013-01-01', '2013-01-02', '2013-01-03'], dtype='datetime64[ns]', freq='D')

In [21]: pd.date_range('20130101',periods=3)[2]
Out[21]: Timestamp('2013-01-03 00:00:00', freq='D')

irregular

In [28]: pd.DatetimeIndex([pd.Timestamp('20130101'), pd.Timestamp('20130103'), pd.Timestamp('20130102')])
Out[28]: DatetimeIndex(['2013-01-01', '2013-01-03', '2013-01-02'], dtype='datetime64[ns]', freq=None)

In [29]: pd.DatetimeIndex([pd.Timestamp('20130101'), pd.Timestamp('20130103'), pd.Timestamp('20130102')])[1]
Out[29]: Timestamp('2013-01-03 00:00:00')

So I'll hazard a guess here. I think the reason that we retain the freq attribute is to annotate that we came from a regular frequency (but are representing a timestamp, and not a duration). I don't think it is actually used aywhere.

If this is the case, then we should simply remove this; a single timestamp doesn't have a notion of a freq, and if you have multiple timestamps then you have a DTI (which may or may not have a regular freq).

I don't think this changes resampling at all (and the decisions of whether to return a PeriodIndex are othogonal here).

There may have been another reason, IOW, if you have a Timestamp with a freq, then constructing a NEW DTI doesn't require a freq in theory (though this is not actually implemented).

[jreback]

cc @wesm if you can shed any light

[max-sixty]

Agree with @jreback last comment.

Stepping back on the concepts at work here:

Frequency for Timestamps are just a helpful label - they don't change the actual value. i.e. I have a temperature reading every day at 7am for 2016: if we have the Timestamp values, 'every day' is just a helpful label / comment, there is no additional information there (and it makes no sense to have that for a single timestamp, then it's just 'a temperature at 7am once')

Frequency for Periods is core to its value - it's the length of the interval - i.e. each day in December 2016 I wrote x lines of code: I measure the output between midnight one day and midnight the next day. Because we generally use contiguous indexes, it also is used as the frequency of those intervals. (It could be theoretically be possible to have a PeriodIndex which is Monday every week, for example)

[jbrockmendel]

Is removing the Timestamp.freq attribute even viable at this point? It would make life easier, but seems like a non-trivial break.

[jbrockmendel]

This seems pretty non-actionable at the moment. Might be viable on a 2.0 wishlist? If such a thing existed, there are a handful of tslibs items I'd like to put on it.

[jorisvandenbossche]

Why would it actually be a wish list item?

As described above by others, freq on a Timestamp is a informative label at most, but doesn't change the value. I agree with that.
But does it complicate the implementation a lot? I mean, is there a good reason to get rid of it? (I am not that familiar with that part of the code base, so it certainly can be it would be nice to get rid of)

I changed the title as I don't think this has still something to do with Periods?

[jimbasquiat]

I think simply mentionning the existence of Timestamp with freq value in the doc would be enough. It was just confusing for me when i stumbled upon it, but when explained it's just fine and perfectly harmless.

…

On 10 Dec 2017 13:17, "Joris Van den Bossche" ***@***.***> wrote: Why would it actually be a wish list item? As described above by others, freq on a Timestamp is a *informative label* at most, but doesn't change the value. I agree with that. But does it complicate the implementation a lot? I mean, is there a good reason to get rid of it? (I am not that familiar with that part of the code base, so it certainly can be it would be nice to get rid of) I changed the title as I don't think this has still something to do with Periods? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#15146 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AS26JkEmk1IU8QRFSmDnhwcqB7_ukS0Rks5s-9oGgaJpZM4Llu1a> .

[jbrockmendel]

Why would it actually be a wish list item?

The priority is in the range of "well, if we were doing it from scratch, I'd want to do it differently". I figure it's not actionable now, but might be appropriate for 2.0.

But does it complicate the implementation a lot? I mean, is there a good reason to get rid of it? (I am not that familiar with that part of the code base, so it certainly can be it would be nice to get rid of)

In a few small ways. is_(year|month|quarter)_(start|end) have special paths depending on freq. __hash__ and __eq__ ignore freq. It isn't recognized by any of the special constructors now, today, ... or replace. pd.DatetimeIndex([ts]) doesn't check for ts.freq.

None of these are big deals, but are sufficiently sub-optimal that I can offer the OP moral support.

freq on a Timestamp is a informative label at most, but doesn't change the value.

The only behavior that is affected is __add__ and __sub__, where adding/subtracting integers is defined if freq is not None. In that sense it behaves a lot like Period.

[jbrockmendel]

Now that we have deprecated Timestamp +/- integer ops, this might be worth revisiting.

[jbrockmendel]

If the policy is that anything we want removed in 1.0 needs to be deprecated in 0.24.0, then I think we should do this now. xref #24060

[cokelid]

Does this have implications for the future of freq in pandas.DatetimeIndex?

[jbrockmendel]

Does this have implications for the future of freq in pandas.DatetimeIndex?

No.

[rwijtvliet]

Is this the place to mention use cases where the freq attribute of a single timestamp is used? And where periods can currently not replace them? Or should I open a new issue instead?

[jreback]

@rwijtvliet you can open an issue but this has already been depreciated