Repository: aeon-toolkit/aeon
Pull request #1985 (2024-08-18 17:57:22)

[ENH] Recursive Median Sieve Transformer
#### Reference Issues/PRs

Implement Recursive Median Sieve filter asked in #1920.

#### What does this implement/fix? Explain your changes.

Add a new transformation, named `SIVSeriesTransformer` which use [SciPy median_filter](https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.median_filter.html)

#### Does your contribution introduce a new dependency? If yes, which one?

No, but we add another SciPy usage.

#### Any other comments?

Code is based on previous work `DFTSeriesTransformer`. I don't think I've forgotten anything, but there may still be references to the DFT as I started by copying _dft.py and test_dft.py.

This PR and #1984 may have conflict for documentation and init (easy to solve).

Name choice came from https://link.springer.com/chapter/10.1007/978-3-030-29859-3_5 (reference in linked issue) but can be changed to something else.

### PR checklist

##### For all contributions
- [x] I've added myself to the [list of contributors](https://github.com/aeon-toolkit/aeon/blob/main/.all-contributorsrc). Alternatively, you can use the [@all-contributors](https://allcontributors.org/docs/en/bot/usage) bot to do this for you.
- [x] The PR title starts with either [ENH], [MNT], [DOC], [BUG], [REF], [DEP] or [GOV] indicating whether the PR topic is related to enhancement, maintenance, documentation, bugs, refactoring, deprecation or governance.

##### For new estimators and functions
- [x] I've added the estimator to the online [API documentation](https://www.aeon-toolkit.org/en/latest/api_reference.html).
- [x] (OPTIONAL) I've added myself as a `__maintainer__` at the top of relevant files and want to be contacted regarding its maintenance. Unmaintained files may be removed. This is for the full file, and you should not add yourself if you are just making minor changes or do not want to help maintain its contents.



aeon-actions-bot[bot]: 
## Thank you for contributing to `aeon`

I did not find any labels to add based on the title. Please add the [ENH], [MNT], [BUG], [DOC], [REF], [DEP] and/or [GOV] tags to your pull requests titles. For now you can add the labels manually.
I have added the following labels to this PR based on the changes made: **[ $\\color{#41A8F6}{\\textsf{transformations}}$ ]**. Feel free to change these if they do not properly represent the PR.

The [Checks](https://github.com/aeon-toolkit/aeon/pull/1985/checks) tab will show the status of our automated tests. You can click on individual test runs in the tab or "Details" in the panel below to see more information if there is a failure.

If our `pre-commit` code quality check fails, any trivial fixes will automatically be pushed to your PR unless it is a draft.

Don't hesitate to ask questions on the `aeon` [Slack](https://join.slack.com/t/aeon-toolkit/shared_invite/zt-22vwvut29-HDpCu~7VBUozyfL_8j3dLA) channel if you have any.

### PR CI actions

These checkboxes will add labels to enable/disable CI functionality for this PR. This may not take effect immediately, and a new commit may be required to run the new configuration.

- [ ] Run `pre-commit` checks for all files
- [ ] Run all `pytest` tests and configurations
- [ ] Run all notebook example tests
- [ ] Run numba-disabled `codecov` tests
- [ ] Stop automatic `pre-commit` fixes (always disabled for drafts)
- [ ] Push an empty commit to re-run CI checks
    
Cyril-Meyer: Here is a visualization of x12r vs fit_transform(x12r) with the tests parameters.

![SIV_1](https://github.com/user-attachments/assets/b0935ac9-7fff-460e-8ef1-6448667b41b3)
![SIV_2](https://github.com/user-attachments/assets/353485e9-e9cd-4f6e-9e6f-92f6b4d5e6da)
![SIV_3](https://github.com/user-attachments/assets/85f2a1fb-da21-494b-8abe-c8fc21ff9a22)
![SIV_5](https://github.com/user-attachments/assets/f0ce6166-e45d-4350-9566-6a6ce882c260)
![SIV_7](https://github.com/user-attachments/assets/6f1a160e-356a-4937-8183-9777da631aec)
![SIV_10](https://github.com/user-attachments/assets/65486798-f56f-447c-a928-fa6441fe5080)
![SIV_11](https://github.com/user-attachments/assets/f3fa8741-b1a1-4f7c-94ce-8fe8698eae77)
![SIV_ 2, 3](https://github.com/user-attachments/assets/5fc21b71-c27a-4d38-8403-09e8f7ff3fa5)
![SIV_ 3, 5](https://github.com/user-attachments/assets/0e93bc15-cfb7-4e52-a611-466828aa9063)
![SIV_ 3, 5, 7](https://github.com/user-attachments/assets/cb52506e-eba9-46f1-a66b-143925a4fec1)
![SIV_ 3, 5, 7, 11](https://github.com/user-attachments/assets/94c3cb18-3d52-45ae-8c89-8a0dd364753d)

Cyril-Meyer: I. Using list [3, 5, 7] as default instead of "3" is better as its just a median filter if not using list of parameters.

-----

II. Some tests failed ([example](https://github.com/aeon-toolkit/aeon/actions/runs/10442638302/job/28915156413?pr=1985#step:7:266))

Error is due to the `__init__` method that convert int parameter into list of the single int.
But this make problem with `test_set_params_sklearn` which "check that set_params works correctly, mirrors sklearn check_set_params."

Commit 91af2041d49eb05f8d32cb13e3b4d632fdd8514c try to fix this and implement I.
`window_length=None` for default parameter is used because of error if using mutable data for args default.
```
aeon/transformations/series/_siv.py:57:38: B006 Do not use mutable data structures for argument defaults.  They are created during function definition time. All calls to the function reuse this one instance of that data structure, persisting changes between them.
```

-----

III. First fix does not work, so proposed a84f10cf0a9065146426b8a447905055f43a3650
The only solution to me about for now is to move the `window_length` conversion into `_transform`.
Feedbacks are very welcome as I'm not sure this solution is clean enough.

TonyBagnall: minor conflict to resolve @Cyril-Meyer 
Cyril-Meyer: > minor conflict to resolve @Cyril-Meyer

I resolved it directly on GitHub so we need to check that doc is good for both SG and SIV as the commit looks a little strange.
Cyril-Meyer: `FAILED aeon/similarity_search/distance_profiles/tests/test_naive_distance.py::test_naive_distance_unequal_length[euclidean-float64] - ReferenceError: underlying object has vanished
`
I don't really know how it is related, but test failed...
TonyBagnall: ah no, thats not related

Patch:
diff --git a/aeon/transformations/series/__init__.py b/aeon/transformations/series/__init__.py
index cf2ba2bd..2ee1c0c8 100644
--- a/aeon/transformations/series/__init__.py
+++ b/aeon/transformations/series/__init__.py
@@ -17,6 +17,7 @@ __all__ = [
     "BoxCoxTransformer",
     "Dobin",
     "ScaledLogitSeriesTransformer",
+    "SIVSeriesTransformer",
     "PCASeriesTransformer",
 ]
 
@@ -36,5 +37,6 @@ from aeon.transformations.series._pca import PCASeriesTransformer
 from aeon.transformations.series._pla import PLASeriesTransformer
 from aeon.transformations.series._scaled_logit import ScaledLogitSeriesTransformer
 from aeon.transformations.series._sg import SGSeriesTransformer
+from aeon.transformations.series._siv import SIVSeriesTransformer
 from aeon.transformations.series._theta import ThetaTransformer
 from aeon.transformations.series.base import BaseSeriesTransformer
diff --git a/aeon/transformations/series/_moving_average.py b/aeon/transformations/series/_moving_average.py
new file mode 100644
index 00000000..7e999394
--- /dev/null
+++ b/aeon/transformations/series/_moving_average.py
@@ -0,0 +1,78 @@
+"""Moving average transformation."""
+
+__maintainer__ = ["Datadote"]
+__all__ = ["MovingAverageSeriesTransformer"]
+
+import numpy as np
+
+from aeon.transformations.series.base import BaseSeriesTransformer
+
+
+class MovingAverageSeriesTransformer(BaseSeriesTransformer):
+    """Calculate the moving average of an array of numbers.
+
+    Slides a window across the input array, and returns the averages for each window.
+    This implementation precomputes a cumulative sum, and then performs subtraction.
+
+    Parameters
+    ----------
+    window_size: int, default=5
+        Number of values to average for each window
+
+    References
+    ----------
+    Large, J., Southam, P., Bagnall, A. (2019).
+        Can Automated Smoothing Significantly Improve Benchmark Time Series
+        Classification Algorithms?. In: Pérez García, H., Sánchez González,
+        L., CastejónLimas, M., Quintián Pardo, H., Corchado Rodríguez, E. (eds) Hybrid
+        Artificial Intelligent Systems. HAIS 2019. Lecture Notes in Computer Science(),
+        vol 11734. Springer, Cham. https://doi.org/10.1007/978-3-030-29859-3_5
+        https://arxiv.org/abs/1811.00894
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from aeon.transformations.series._moving_average import \
+        MovingAverageSeriesTransformer
+    >>> X = np.array([-3, -2, -1,  0,  1,  2,  3])
+    >>> transformer = MovingAverageSeriesTransformer(2)
+    >>> Xt = transformer.fit_transform(X)
+    >>> print(Xt)
+    [[-2.5 -1.5 -0.5  0.5  1.5  2.5]]
+    """
+
+    _tags = {
+        "capability:multivariate": True,
+        "X_inner_type": "np.ndarray",
+        "fit_is_empty": True,
+    }
+
+    def __init__(self, window_size: int = 5) -> None:
+        super().__init__(axis=0)
+        if window_size <= 0:
+            raise ValueError(f"window_size must be > 0, got {window_size}")
+        self.window_size = window_size
+
+    def _transform(self, X, y=None):
+        """Transform X and return a transformed version.
+
+        private _transform containing core logic, called from transform
+
+        Parameters
+        ----------
+        X : np.ndarray
+            Data to be transformed
+        y : ignored argument for interface compatibility
+            Additional data, e.g., labels for transformation
+
+        Returns
+        -------
+        Xt: 2D np.ndarray
+            transformed version of X
+        """
+        csum = np.cumsum(X, axis=0)
+        csum[self.window_size :, :] = (
+            csum[self.window_size :, :] - csum[: -self.window_size, :]
+        )
+        Xt = csum[self.window_size - 1 :, :] / self.window_size
+        return Xt
diff --git a/aeon/transformations/series/_siv.py b/aeon/transformations/series/_siv.py
new file mode 100644
index 00000000..ac511ae0
--- /dev/null
+++ b/aeon/transformations/series/_siv.py
@@ -0,0 +1,86 @@
+"""Recursive Median Sieve filter transformation."""
+
+__maintainer__ = ["Cyril-Meyer"]
+__all__ = ["SIVSeriesTransformer"]
+
+
+import numpy as np
+from scipy.ndimage import median_filter
+
+from aeon.transformations.series.base import BaseSeriesTransformer
+
+
+class SIVSeriesTransformer(BaseSeriesTransformer):
+    """Filter a times series using Recursive Median Sieve (SIV).
+
+    Parameters
+    ----------
+    window_length : list of int or int, default=[3, 5, 7]
+        The filter windows lenths (recommended increasing value).
+
+    Notes
+    -----
+    Use scipy.ndimage.median_filter instead of scipy.signal.medfilt :
+    The more general function scipy.ndimage.median_filter has a more efficient
+    implementation of a median filter and therefore runs much faster.
+    https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.medfilt.html
+
+    References
+    ----------
+    .. [1] Bangham J. A. (1988).
+       Data-sieving hydrophobicity plots.
+       Analytical biochemistry, 174(1), 142–145.
+       https://doi.org/10.1016/0003-2697(88)90528-3
+    .. [2] Yli-Harja, O., Koivisto, P., Bangham, J. A., Cawley, G.,
+       Harvey, R., & Shmulevich, I. (2001).
+       Simplified implementation of the recursive median sieve.
+       Signal Process., 81(7), 1565–1570.
+       https://doi.org/10.1016/S0165-1684(01)00054-8
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from aeon.transformations.series._siv import SIVSeriesTransformer
+    >>> X = np.random.random((2, 100)) # Random series length 100
+    >>> siv = SIVSeriesTransformer()
+    >>> X_ = siv.fit_transform(X)
+    >>> X_.shape
+    (2, 100)
+    """
+
+    _tags = {
+        "capability:multivariate": True,
+        "X_inner_type": "np.ndarray",
+        "fit_is_empty": True,
+    }
+
+    def __init__(self, window_length=None):
+        self.window_length = window_length
+        super().__init__(axis=1)
+
+    def _transform(self, X, y=None):
+        """Transform X and return a transformed version.
+
+        Parameters
+        ----------
+        X : np.ndarray
+            time series in shape (n_channels, n_timepoints)
+        y : ignored argument for interface compatibility
+
+        Returns
+        -------
+        transformed version of X
+        """
+        if self.window_length is None:
+            self.window_length = [3, 5, 7]
+        if not isinstance(self.window_length, list):
+            self.window_length = [self.window_length]
+
+        # Compute SIV
+        X_ = X
+
+        for window_length in self.window_length:
+            footprint = np.ones((1, window_length))
+            X_ = median_filter(X_, footprint=footprint)
+
+        return X_
diff --git a/docs/api_reference/transformations.rst b/docs/api_reference/transformations.rst
index 58be8632..d56e9c6a 100644
--- a/docs/api_reference/transformations.rst
+++ b/docs/api_reference/transformations.rst
@@ -202,6 +202,14 @@ Filtering and denoising
 
     SGSeriesTransformer
 
+.. currentmodule:: aeon.transformations.series._siv
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: class.rst
+
+    SIVSeriesTransformer
+
 Slope
 ~~~~~~~~~~~~~~~~~~~~~~
 


Test patch:
diff --git a/aeon/transformations/series/tests/test_moving_average.py b/aeon/transformations/series/tests/test_moving_average.py
new file mode 100644
index 00000000..bfbf3a71
--- /dev/null
+++ b/aeon/transformations/series/tests/test_moving_average.py
@@ -0,0 +1,38 @@
+"""Tests for MovingAverageTransformer."""
+
+__maintainer__ = ["Datadote"]
+
+import numpy as np
+import pytest
+
+from aeon.transformations.series._moving_average import MovingAverageSeriesTransformer
+
+TEST_DATA = [np.array([-3, -2, -1, 0, 1, 2, 3]), np.array([[-3, -2, -1, 0, 1, 2, 3]])]
+EXPECTED_RESULTS = [
+    np.array([[-2.5, -1.5, -0.5, 0.5, 1.5, 2.5]]),
+    np.array([[-2.5, -1.5, -0.5, 0.5, 1.5, 2.5]]),
+]
+
+
+def test_window_size_greater_than_zero():
+    """Test window sizes > 0."""
+    ma = MovingAverageSeriesTransformer(window_size=1)
+    xt = ma.fit_transform(TEST_DATA[0])
+    np.testing.assert_array_almost_equal(xt, xt, decimal=2)
+
+    ma = MovingAverageSeriesTransformer(window_size=2)
+    for i in range(len(TEST_DATA)):
+        xt = ma.fit_transform(TEST_DATA[i])
+        np.testing.assert_array_almost_equal(xt, EXPECTED_RESULTS[i], decimal=2)
+
+
+def test_window_size_equal_zero():
+    """Test window size == 0."""
+    with pytest.raises(ValueError):
+        MovingAverageSeriesTransformer(window_size=0)
+
+
+def test_window_size_less_than_zero():
+    """Test window sizes < 0."""
+    with pytest.raises(ValueError):
+        MovingAverageSeriesTransformer(window_size=-1)
diff --git a/aeon/transformations/series/tests/test_siv.py b/aeon/transformations/series/tests/test_siv.py
new file mode 100644
index 00000000..c8042e9c
--- /dev/null
+++ b/aeon/transformations/series/tests/test_siv.py
@@ -0,0 +1,48 @@
+"""Tests for SIV transformation."""
+
+__maintainer__ = []
+
+import numpy as np
+import pytest
+
+
+@pytest.mark.parametrize(
+    "window_length", [1, 2, 3, 5, 7, 10, 11, [2, 3], [3, 5], [3, 5, 7], [3, 5, 7, 11]]
+)
+def test_siv(window_length):
+    """Test the functionality of SIV transformation."""
+    n_samples = 100
+    t = np.linspace(0, 10, n_samples)
+    x1 = (
+        0.5 * np.sin(2 * np.pi * 1 * t)
+        + 0.2 * np.sin(2 * np.pi * 5 * t)
+        + 0.1 * np.sin(2 * np.pi * 10 * t)
+    )
+    x2 = (
+        0.4 * np.sin(2 * np.pi * 1.5 * t)
+        + 0.3 * np.sin(2 * np.pi * 4 * t)
+        + 0.1 * np.sin(2 * np.pi * 8 * t)
+    )
+    x12 = np.array([x1, x2])
+    x12r = x12 + np.random.random((2, n_samples)) * 0.25
+
+    from aeon.transformations.series._siv import SIVSeriesTransformer
+
+    siv = SIVSeriesTransformer(window_length=window_length)
+    x_1 = siv.fit_transform(x1)
+    x_2 = siv.fit_transform(x2)
+    x_12 = siv.fit_transform(x12)
+    x_12_r = siv.fit_transform(x12r)
+
+    """
+    # Visualize smoothing
+    import matplotlib.pyplot as plt
+    plt.plot(x12r[0])
+    plt.plot(x_12_r[0])
+    plt.savefig(fname=f'SIV_{window_length}.png')
+    plt.clf()
+    """
+
+    np.testing.assert_almost_equal(x_1[0], x_12[0], decimal=4)
+    np.testing.assert_almost_equal(x_2[0], x_12[1], decimal=4)
+    assert x_12.shape == x_12_r.shape