DOC warn user about potential information loss in Resampler.interpolate

[kopytjuk]

In scientific and technical domain people deal with high-frequent or non-equidistant timeseries. Using resample("1s").interpolate() can have unwanted side effects which we should warn in the documentation:

import datetime as dt
import pandas as pd
import matplotlib.pyplot as plt

timesteps = [
    dt.datetime(2023, 3, 1, 7, 0, 0),
    dt.datetime(2023, 3, 1, 7, 0, 1),
    dt.datetime(2023, 3, 1, 7, 0, 2),
    dt.datetime(2023, 3, 1, 7, 0, 3),
    dt.datetime(2023, 3, 1, 7, 0, 4)
]
series = pd.Series(data=[1, -1, 2, 1, 3], index=timesteps)

resample_freq = "400ms"
series_resampler = series.resample(resample_freq)
series_resampled_linear = series_resampler.interpolate("linear")

which leads to the following:

For that example, information loss is expected.

Imho we should warn the user about this behavior. It seems to be known, to quote @jreback from here:

so the reason this happens is because the index is first reindexed to the new time buckets (upsampled) via reindexing, then interpolation happens.

• refers to Interpolate (upsample) non-equispaced timeseries into equispaced 18.0rc1 #12552, resample interpolate gives unexpected results in 0.18.1 #14297
• Tests added and passed if fixing a bug or adding a new feature
• All code checks passed.
• Added type annotations to new arguments/methods/functions.
• Added an entry in the latest doc/source/whatsnew/vX.X.X.rst file if fixing a bug or adding a new feature.

[mroeschke]

Thanks, looks like some of our docstring validations are failing

[kopytjuk]

@mroeschke here I removed the docstring concatenation (this is misleading, since the user probably has no NaNs in its data originally) and added links to documentation, so the user can inform her/himself about various methods

[kopytjuk]

@mroeschke let me know if something is missing/to be extended

[mroeschke]

Thanks @kopytjuk