implement pyleo.Series.resample

.gitattributes

@@ -1 +1,2 @@
 environment.yml merge=ours
+*.py diff=python

pyleoclim/core/series.py

@@ -8,6 +8,7 @@
 """
 
 import operator
+import re
 
 from ..utils import tsutils, plotting, tsmodel, tsbase, mapping, lipdutils, jsonutils
 from ..utils import wavelet as waveutils
@@ -3951,3 +3952,76 @@ def map(self, projection='Orthographic', proj_default=True,
                               scatter_kwargs=scatter_kwargs, legend=legend,
                               lgd_kwargs=lgd_kwargs, savefig_settings=savefig_settings)
         return res
+
+    def resample(self, rule, **kwargs):
+        """
+        Run analogue to pandas.Series.resample.
+
+        Parameters
+        ----------
+        rule
+            The offset string or object representing target conversion.
+            Can also accept pyleoclim units, such as 'Ka' (1000 years),
+            'Ma' (1 million years), and 'Ga' (1 billion years).
+        kwargs
+            Any other arguments which will be passed to pandas.Series.resample.
+
+        Returns
+        -------
+        SeriesResampler
+            Resampler object, not meant to be used to directly. Instead,
+            an aggregation should be called on it, see examples below.
+
+        Examples
+        --------
+        >>> ts.resample('Ka').mean()  # doctest: +SKIP
+        """
+        search = re.search(r'(\d*)([a-zA-Z]+)', rule)
+        if search is None:
+            raise ValueError(f"Invalid rule provided, got: {rule}")
+        multiplier = search.group(1)
+        if multiplier == '':
+            multiplier = 1
+        else:
+            multiplier = int(multiplier)
+        unit = search.group(2)
+        if unit.lower() in tsutils.MATCH_A:
+            pass
+        elif unit.lower() in tsutils.MATCH_KA:
+            multiplier *= 1_000
+        elif unit.lower() in tsutils.MATCH_MA:
+            multiplier *= 1_000_000
+        elif unit.lower() in tsutils.MATCH_GA:
+            multiplier *= 1_000_000_000
+        else:
+            raise ValueError(f'Invalid unit provided, got: {unit}')
+        ser = self.to_pandas()
+        return SeriesResampler(f'{multiplier}Y', ser, self.metadata, kwargs)
+
+
+class SeriesResampler:
+    """
+    This is only meant to be used internally, and is not meant to 
+    be public-facing or to be used directly by users.
+
+    If users call
+
+        ts.resample('1Y').mean()
+
+    then they will get back a pyleoclim.Series, and `SeriesResampler`
+    will only be used in an intermediate step. Think of it as an
+    implementation detail.
+    """
+    def __init__(self, rule, series, metadata, kwargs):
+        self.rule = rule
+        self.series = series
+        self.metadata = metadata
+        self.kwargs = kwargs
+
+    def __getattr__(self, attr):
+        attr = getattr(self.series.resample(self.rule, **self.kwargs), attr)
+        def func(*args, **kwargs):
+            series = attr(*args, **kwargs)
+            from_pandas = Series.from_pandas(series, metadata=self.metadata)
+            return from_pandas
+        return func

pyleoclim/tests/conftest.py

@@ -16,4 +16,18 @@ def dataframe():
     """Pandas dataframe with a non-datetime index and random values"""
     length = 5
     df = pd.DataFrame(np.ones(length))
-    return df
+    return df
+
+@pytest.fixture
+def metadata():
+    return {'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},)
+    }

pyleoclim/tests/test_core_Series.py

@@ -1019,3 +1019,35 @@ def test_sort_t1(self):
         ts = pyleo.Series(t,v)
         ts.sort()
         assert np.all(np.diff(ts.time) >= 0)
+
+
+class TestResample:
+    @pytest.mark.parametrize('rule', pyleo.utils.tsutils.MATCH_A)
+    def test_resample_simple(self, rule, dataframe_dt, metadata):
+        # note: resample with large ranges is still not supported,
+        # so for now we're only testing 'years' as the rule
+        # https://github.com/pandas-dev/pandas/issues/51024
+        ser = dataframe_dt.loc[:, 0]
+        with pytest.warns(UserWarning, match='Time unit years CE not recognized. Defaulting to years CE'):
+            ts = pyleo.Series.from_pandas(ser, metadata)
+            result =ts.resample(rule).mean()
+            result_ser = result.to_pandas()
+        expected_values = np.array([0., 1., 2., 3., 4.])
+        expected_idx = pd.DatetimeIndex(['2018-12-30 23:59:59', '2019-12-30 23:59:59',
+               '2020-12-30 23:59:59', '2021-12-30 23:59:59',
+               '2022-12-30 23:59:59'], name='datetime').as_unit('s')
+        expected_ser = pd.Series(expected_values, expected_idx, name='SOI')
+        expected_metadata = {'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})}
+        pd.testing.assert_series_equal(result_ser, expected_ser)
+        assert result.metadata == expected_metadata
+
+    def test_resample_invalid(self, dataframe_dt, metadata):
+        # note: resample with large ranges is still not supported,
+        # so for now we're only testing 'years' as the rule
+        ser = dataframe_dt.loc[:, 0]
+        with pytest.warns(UserWarning, match='Time unit years CE not recognized. Defaulting to years CE'):
+            ts = pyleo.Series.from_pandas(ser, metadata)
+        with pytest.raises(ValueError, match='Invalid unit provided, got: foo'):
+            ts.resample('foo')
+        with pytest.raises(ValueError, match='Invalid rule provided, got: 412'):
+            ts.resample('412')

pyleoclim/utils/tsutils.py

@@ -76,7 +76,7 @@ def time_unit_to_datum_exp_dir(time_unit, time_name=None):
         exponent = 9
         direction = 'retrograde'
     else:
-        warnings.warn(f'Time unit {time_unit} not recognized. Defaulting to years CE')
+        warnings.warn(f'Time unit {time_unit} not recognized. Defaulting to years CE', stacklevel=4)
 
     # deal with statements about datum/direction
     tu = time_unit.lower().strip('.') # make lowercase + strip stops, so "B.P." --> "bp"