implement pyleo.Series.resample

[MarcoGorelli]

Here's a start on pyleo.Series.resample

This allows you to do

ts.resample('Y').mean()

instead of

ts.pandas_method(lambda x: x.resample('Y').mean())

, but also to use 'Ga' / 'Ka' / etc. (or at least, it will once pandas-dev/pandas#51024 is addressed)

[kcpevey]

Resolves: LinkedEarth/paleoPandas#12

[MarcoGorelli]

this was just to allow git log to work with Python functions

[MarcoGorelli]

this is so that the warning will point to the user's code, rather than to the line of code within pyleoclim which raises the warning

[CommonClimate]

Thanks. That is useful as this warning was cropping up constantly on my end due to my inadequate parsing of units (now fixed). I could make sense of it because I know the code, but this should help other users figure out what's happening on their end.

[CommonClimate]

Hi @MarcoGorelli , the tests exchanged on Slack look good:

I added a modification to the metadata to indicate that resampling had taken place. However, it would be good to add that to the log as well. You can look at Series.center() as an example of what the log does: indicate what transformation was applied and keep track of some relevant bits (not sure what this would be there; maybe the original index?)

Note that your docstring example was a tad terse for our users:
>>> ts.resample('ka').mean() # doctest: SKIP

I replaced with:

ts = pyleo.utils.load_dataset('nino3')
fig, ax = ts.plot()
ts.resample('5y').mean().plot(ax=ax)

Pandas question: I see that the method returns a SeriesResampler object, which I have never encountered. beyond mean(), what else might be done with it? I'm thinking our users will mostly want the data averaged over the new index (so, ts.resample(rule).mean() in the current code), but maybe I am missing something useful that could be done with that object.

Once that is all resolved, I am happy to merge and we can wait until pandas issue 51024 is addressed for the longer-term stuff.

PS: feel free to review this review!

[MarcoGorelli]

I think so - don't you have a way of building the docs locally? then you could check

[CommonClimate]

The checks have failed :
FAILED pyleoclim/tests/test_core_Series.py::TestResample::test_resample_simple[year] - AssertionError: assert {'time_unit': 'years CE', 'time_name': 'Time', 'value_unit': 'mb', 'value_name': 'SOI', 'label': 'Southern Oscillation Index (year resampling)', 'lat': None, 'lon': None, 'archiveType': None, 'importedFrom': None, 'log': ({0: 'clean_ts', 'applied': True, 'verbose': False}, {2: 'clean_ts', 'applied': True, 'verbose': False}, {3: 'clean_ts', 'applied': True, 'verbose': False})} == {'time_unit': 'years CE', 'time_name': 'Time', 'value_unit': 'mb', 'value_name': 'SOI', 'label': 'Southern Oscillation Index', 'lat': None, 'lon': None, 'archiveType': None, 'importedFrom': None, 'log': ({0: 'clean_ts', 'applied': True, 'verbose': False}, {2: 'clean_ts', 'applied': True, 'verbose': False}, {3: 'clean_ts', 'applied': True, 'verbose': False})}

Perhaps testing for the equality of the entire metadata dict is too much? It looks like "clean()" is applied 3 times here, and perhaps a 4th that is not taken into account in the test?

[CommonClimate]

re: docstrings, >>> is parsed by Sphinx as an formatting thing, but does not actually run the code (which is what we need it to do). See other docstrings for the ipython directives that will achieve that.

[MarcoGorelli]

I see that the method returns a SeriesResampler object, which I have never encountered

It's just how like if you have a pandas Series, and you just call resample, that's what you'll get:

In [1]: ser = pd.Series([1, 2, 3, 4, 5], index=pd.date_range('2000', periods=5))

In [2]: ser.resample('Y')
Out[2]: <pandas.core.resample.DatetimeIndexResampler object at 0x7fa4e50493d0>

Regarding what works with it - any aggregation that works on a pandas.Series.resample should work, see https://pandas.pydata.org/docs/user_guide/timeseries.html#resampling

e.g. .mean(), .std(), .mean(), etc

[CommonClimate]

Thanks for the explanation Marco. This checks all the boxes so I am going to merge.

I need to educate myself on resample() to make the best of it, and the link really helps. I wonder how this can help us for aligning Series objects within a MultipleSeries. We have a method under the latter class called common_time(), and I'd appreciate suggestion on how it could better use resample(). It sounds like we could use dispatching with our other methods (e.g. bin(), gkernel(), interp(), defined in tsutils.py) on those SeriesResampler objects, no? Happy to hear your suggestions for implementation, as you know Pandas' potential so much better than we do!