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)