The 'kind' keyword in resample lets you pretend you have a PeriodIndex instead of a DatetimeIndex, and vice-versa. Users who need the other one can just convert using to_(period|timestamp) before calling resample.
xref #55895
Comment From: avibrazil
I'm not sure this can be deprecated with the arguments provided.
It seems to me you are assuming the starting dataframe has a monotonic index, like one timestamp per month.
What if the starting dataframe has a ragged index, like many random timestamps during each month which are completely different for every month and then I want to resample to MonthEnd? I think I can't convert a ragged input with to_period() before resample. I'm precisely using resample() here to convert a ragged input (with random timestamps) into a periodic timeseries. I see resample(kind='period') as the way to make the conversion you want people to do before using resample.
Here is an example dataframe with ragged timestamps that I want to convert to a monotonic period index with resample:
i=pandas.DatetimeIndex(['2023-02-13 20:29:59.734000+00:00',
'2023-02-16 15:30:00.765000+00:00',
'2023-03-02 14:32:00.990000+00:00',
'2023-03-21 19:49:59.705000+00:00',
'2023-03-31 04:00:00.476000+00:00',
'2023-04-18 13:01:00+00:00',
'2023-05-11 19:13:00.455000+00:00',
'2023-05-17 17:44:59.577000+00:00',
'2023-05-31 23:30:00.562000+00:00',
'2023-06-09 12:41:59.915000+00:00',
'2023-06-21 10:36:00.319000+00:00',
'2023-07-05 18:01:49+00:00',
'2023-07-07 21:48:13+00:00',
'2023-07-13 01:14:33+00:00',
'2023-08-08 08:02:56+00:00',
'2023-08-22 07:41:23+00:00',
'2023-09-12 17:16:48+00:00',
'2023-09-15 06:50:31+00:00',
'2023-09-21 21:19:05+00:00',
'2023-09-25 17:09:19+00:00',
'2023-09-25 17:13:00+00:00',
'2023-10-19 13:45:44+00:00',
'2023-10-24 23:22:35+00:00',
'2023-11-08 16:58:00+00:00',
'2023-11-10 01:18:24+00:00',
'2023-11-14 20:28:23+00:00',
'2023-11-16 16:18:00+00:00',
'2023-11-21 01:47:16+00:00',
'2023-11-24 01:53:01+00:00',
'2023-11-25 03:25:13+00:00',
'2023-11-30 23:11:16+00:00',
'2023-12-05 12:03:42+00:00',
'2023-12-14 00:50:55+00:00',
'2023-12-19 14:32:41+00:00',
'2023-12-26 13:43:27+00:00',
'2023-12-29 06:27:49+00:00',
'2024-01-02 16:57:00.395000+00:00',
'2024-01-04 23:24:25+00:00',
'2024-01-16 01:00:00.905000+00:00',
'2024-01-23 19:39:25+00:00',
'2024-01-24 10:55:44+00:00',
'2024-01-24 23:06:07+00:00',
'2024-01-30 18:47:10+00:00',
'2024-02-06 09:30:00.566000+00:00',
'2024-02-07 13:30:00+00:00',
'2024-02-09 03:02:04+00:00',
'2024-02-22 00:13:11+00:00',
'2024-02-26 17:44:22+00:00',
'2024-02-27 23:47:36+00:00',
'2024-03-06 02:20:07+00:00'],
dtype='datetime64[ns, UTC]', name='time', freq=None)
df=pandas.DataFrame(index=i,data=dict(any=range(50)))
df.resample(rule='ME', kind='period').agg('last')
Since input is ragged, I can't convert it with df.index=df.index.to_period('M') first.
To get same result without kind, I'll first get an aggregated dataframe with monotonic timestamps and only then do a .to_period(), notting that I need to use different rules between these funcions. resample() uses ME and YE while to_period() uses M and Y, not sure why.
To have resample() do this for me seems more natural since that is the place where time is being manipulated.
Please do not deprecate the kind parameter. It is useful and required.
Comment From: jorisvandenbossche
@avibrazil apologies for the very slow response, but thanks for the feedback on this deprecation.
Looking at your example, it is indeed not possible (or directly straightforward) to convert the datetimes to a PeriodIndex before resampling, but I think you can do it afterwards? (if you want the result to have a PeriodIndex) From quickly trying it, that seems to give the same result;
# original result with the now deprecated option
>>> df.resample(rule='ME', kind='period').agg('last')
FutureWarning: The 'kind' keyword in DataFrame.resample is deprecated and will be removed in a future version. Explicitly cast the index to the desired type instead
any
time
2023-02 1
2023-03 4
2023-04 5
2023-05 8
2023-06 10
2023-07 13
2023-08 15
2023-09 20
2023-10 22
2023-11 30
2023-12 35
2024-01 42
2024-02 48
2024-03 49
# the same but without specifying `kind="period"` -> same values but different index
>>> df.resample(rule='ME').agg('last')
any
time
2023-02-28 00:00:00+00:00 1
2023-03-31 00:00:00+00:00 4
2023-04-30 00:00:00+00:00 5
2023-05-31 00:00:00+00:00 8
2023-06-30 00:00:00+00:00 10
2023-07-31 00:00:00+00:00 13
2023-08-31 00:00:00+00:00 15
2023-09-30 00:00:00+00:00 20
2023-10-31 00:00:00+00:00 22
2023-11-30 00:00:00+00:00 30
2023-12-31 00:00:00+00:00 35
2024-01-31 00:00:00+00:00 42
2024-02-29 00:00:00+00:00 48
2024-03-31 00:00:00+00:00 49
# converting that result to have a PeriodIndex
>>> df.resample(rule='ME').agg('last').to_period()
UserWarning: Converting to PeriodArray/Index representation will drop timezone information.
any
time
2023-02 1
2023-03 4
2023-04 5
2023-05 8
2023-06 10
2023-07 13
2023-08 15
2023-09 20
2023-10 22
2023-11 30
2023-12 35
2024-01 42
2024-02 48
2024-03 49