[REF] Refactor Anomaly Detection Module into Submodules by Algorithm Family (#2694)

Kaustbh · web-flow · commit 28f2ffc191d5 · 2025-04-20T12:00:37.000+01:00
* Refactor Anomaly Detection Module into Submodules by Algorithm Family

* updated documentation and references

* implemented suggested changes

* minor changes

* added headers for remaining algorithm family

* removing tree-based header
diff --git a/aeon/anomaly_detection/__init__.py b/aeon/anomaly_detection/__init__.py
@@ -1,31 +1,7 @@
 """Time Series Anomaly Detection."""
 
 __all__ = [
-    "CBLOF",
-    "COPOD",
-    "DWT_MLEAD",
-    "IsolationForest",
-    "KMeansAD",
-    "LeftSTAMPi",
-    "LOF",
-    "MERLIN",
-    "OneClassSVM",
-    "ROCKAD",
-    "PyODAdapter",
-    "STOMP",
-    "STRAY",
+    "BaseAnomalyDetector",
 ]
 
-from aeon.anomaly_detection._cblof import CBLOF
-from aeon.anomaly_detection._copod import COPOD
-from aeon.anomaly_detection._dwt_mlead import DWT_MLEAD
-from aeon.anomaly_detection._iforest import IsolationForest
-from aeon.anomaly_detection._kmeans import KMeansAD
-from aeon.anomaly_detection._left_stampi import LeftSTAMPi
-from aeon.anomaly_detection._lof import LOF
-from aeon.anomaly_detection._merlin import MERLIN
-from aeon.anomaly_detection._one_class_svm import OneClassSVM
-from aeon.anomaly_detection._pyodadapter import PyODAdapter
-from aeon.anomaly_detection._rockad import ROCKAD
-from aeon.anomaly_detection._stomp import STOMP
-from aeon.anomaly_detection._stray import STRAY
+from aeon.anomaly_detection.base import BaseAnomalyDetector
diff --git a/aeon/anomaly_detection/distance_based/__init__.py b/aeon/anomaly_detection/distance_based/__init__.py
@@ -0,0 +1,19 @@
+"""Distance basedTime Series Anomaly Detection."""
+
+__all__ = [
+    "CBLOF",
+    "KMeansAD",
+    "LeftSTAMPi",
+    "LOF",
+    "MERLIN",
+    "OneClassSVM",
+    "STOMP",
+]
+
+from aeon.anomaly_detection.distance_based._cblof import CBLOF
+from aeon.anomaly_detection.distance_based._kmeans import KMeansAD
+from aeon.anomaly_detection.distance_based._left_stampi import LeftSTAMPi
+from aeon.anomaly_detection.distance_based._lof import LOF
+from aeon.anomaly_detection.distance_based._merlin import MERLIN
+from aeon.anomaly_detection.distance_based._one_class_svm import OneClassSVM
+from aeon.anomaly_detection.distance_based._stomp import STOMP
diff --git a/aeon/anomaly_detection/distance_based/_cblof.py b/aeon/anomaly_detection/distance_based/_cblof.py
@@ -7,7 +7,7 @@
 
 import numpy as np
 
-from aeon.anomaly_detection._pyodadapter import PyODAdapter
+from aeon.anomaly_detection.outlier_detection._pyodadapter import PyODAdapter
 from aeon.utils.validation._dependencies import _check_soft_dependencies
 
 
diff --git a/aeon/anomaly_detection/distance_based/_kmeans.py b/aeon/anomaly_detection/distance_based/_kmeans.py
@@ -65,7 +65,7 @@ class KMeansAD(BaseAnomalyDetector):
     Examples
     --------
     >>> import numpy as np
-    >>> from aeon.anomaly_detection import KMeansAD
+    >>> from aeon.anomaly_detection.distance_based import KMeansAD
     >>> X = np.array([1, 2, 3, 4, 1, 2, 3, 3, 2, 8, 9, 8, 1, 2, 3, 4], dtype=np.float64)
     >>> detector = KMeansAD(n_clusters=3, window_size=4, stride=1, random_state=0)
     >>> detector.fit_predict(X)
diff --git a/aeon/anomaly_detection/distance_based/_left_stampi.py b/aeon/anomaly_detection/distance_based/_left_stampi.py
@@ -44,7 +44,7 @@ class LeftSTAMPi(BaseAnomalyDetector):
     Internally,this is applying the incremental approach outlined below.
 
     >>> import numpy as np # doctest: +SKIP
-    >>> from aeon.anomaly_detection import LeftSTAMPi  # doctest: +SKIP
+    >>> from aeon.anomaly_detection.distance_based import LeftSTAMPi  # doctest: +SKIP
     >>> X = np.random.default_rng(42).random((10))  # doctest: +SKIP
     >>> detector = LeftSTAMPi(window_size=3, n_init_train=3)  # doctest: +SKIP
     >>> detector.fit_predict(X)  # doctest: +SKIP
diff --git a/aeon/anomaly_detection/distance_based/_lof.py b/aeon/anomaly_detection/distance_based/_lof.py
@@ -7,7 +7,7 @@
 
 import numpy as np
 
-from aeon.anomaly_detection._pyodadapter import PyODAdapter
+from aeon.anomaly_detection.outlier_detection._pyodadapter import PyODAdapter
 from aeon.utils.validation._dependencies import _check_soft_dependencies
 
 
diff --git a/aeon/anomaly_detection/distance_based/_merlin.py b/aeon/anomaly_detection/distance_based/_merlin.py
@@ -43,7 +43,7 @@ class MERLIN(BaseAnomalyDetector):
     Examples
     --------
     >>> import numpy as np
-    >>> from aeon.anomaly_detection import MERLIN
+    >>> from aeon.anomaly_detection.distance_based import MERLIN
     >>> X = np.array([1, 2, 3, 4, 1, 2, 3, 4, 2, 3, 4, 5, 1, 2, 3, 4])
     >>> detector = MERLIN(min_length=4, max_length=5)
     >>> detector.fit_predict(X)
diff --git a/aeon/anomaly_detection/distance_based/_one_class_svm.py b/aeon/anomaly_detection/distance_based/_one_class_svm.py
diff --git a/aeon/anomaly_detection/distance_based/_stomp.py b/aeon/anomaly_detection/distance_based/_stomp.py
@@ -38,7 +38,7 @@ class STOMP(BaseAnomalyDetector):
     Examples
     --------
     >>> import numpy as np
-    >>> from aeon.anomaly_detection import STOMP  # doctest: +SKIP
+    >>> from aeon.anomaly_detection.distance_based import STOMP  # doctest: +SKIP
     >>> X = np.random.default_rng(42).random((10, 2), dtype=np.float64)
     >>> detector = STOMP(X, window_size=2)  # doctest: +SKIP
     >>> detector.fit_predict(X, axis=0)  # doctest: +SKIP
diff --git a/aeon/anomaly_detection/distance_based/tests/__init__.py b/aeon/anomaly_detection/distance_based/tests/__init__.py
@@ -0,0 +1 @@
+"""Distance based test code."""
diff --git a/aeon/anomaly_detection/distance_based/tests/test_cblof.py b/aeon/anomaly_detection/distance_based/tests/test_cblof.py
@@ -3,7 +3,7 @@
 import numpy as np
 import pytest
 
-from aeon.anomaly_detection import CBLOF
+from aeon.anomaly_detection.distance_based import CBLOF
 from aeon.testing.data_generation import make_example_1d_numpy
 from aeon.utils.validation._dependencies import _check_soft_dependencies
 
diff --git a/aeon/anomaly_detection/distance_based/tests/test_kmeans.py b/aeon/anomaly_detection/distance_based/tests/test_kmeans.py
@@ -6,7 +6,7 @@
 import pytest
 from sklearn.utils import check_random_state
 
-from aeon.anomaly_detection import KMeansAD
+from aeon.anomaly_detection.distance_based import KMeansAD
 
 
 def test_kmeansad_univariate():
diff --git a/aeon/anomaly_detection/distance_based/tests/test_left_stampi.py b/aeon/anomaly_detection/distance_based/tests/test_left_stampi.py
@@ -8,7 +8,7 @@
 import numpy as np
 import pytest
 
-from aeon.anomaly_detection._left_stampi import LeftSTAMPi
+from aeon.anomaly_detection.distance_based._left_stampi import LeftSTAMPi
 from aeon.testing.data_generation import make_example_1d_numpy
 from aeon.utils.validation._dependencies import _check_soft_dependencies
 
diff --git a/aeon/anomaly_detection/distance_based/tests/test_lof.py b/aeon/anomaly_detection/distance_based/tests/test_lof.py
@@ -3,7 +3,7 @@
 import numpy as np
 import pytest
 
-from aeon.anomaly_detection import LOF
+from aeon.anomaly_detection.distance_based import LOF
 from aeon.testing.data_generation import make_example_1d_numpy
 from aeon.utils.validation._dependencies import _check_soft_dependencies
 
diff --git a/aeon/anomaly_detection/distance_based/tests/test_merlin.py b/aeon/anomaly_detection/distance_based/tests/test_merlin.py
@@ -4,7 +4,7 @@
 
 import numpy as np
 
-from aeon.anomaly_detection import MERLIN
+from aeon.anomaly_detection.distance_based import MERLIN
 
 TEST_DATA = np.array(
     [
diff --git a/aeon/anomaly_detection/distance_based/tests/test_one_class_svm.py b/aeon/anomaly_detection/distance_based/tests/test_one_class_svm.py
@@ -4,7 +4,7 @@
 import pytest
 from sklearn.utils import check_random_state
 
-from aeon.anomaly_detection import OneClassSVM
+from aeon.anomaly_detection.distance_based import OneClassSVM
 
 
 def test_one_class_svm_univariate():
diff --git a/aeon/anomaly_detection/distance_based/tests/test_stomp.py b/aeon/anomaly_detection/distance_based/tests/test_stomp.py
@@ -6,7 +6,7 @@
 import pytest
 from sklearn.utils import check_random_state
 
-from aeon.anomaly_detection import STOMP
+from aeon.anomaly_detection.distance_based import STOMP
 from aeon.utils.validation._dependencies import _check_soft_dependencies
 
 
diff --git a/aeon/anomaly_detection/distribution_based/__init__.py b/aeon/anomaly_detection/distribution_based/__init__.py
@@ -0,0 +1,9 @@
+"""Distribution based Time Series Anomaly Detection."""
+
+__all__ = [
+    "COPOD",
+    "DWT_MLEAD",
+]
+
+from aeon.anomaly_detection.distribution_based._copod import COPOD
+from aeon.anomaly_detection.distribution_based._dwt_mlead import DWT_MLEAD
diff --git a/aeon/anomaly_detection/distribution_based/_copod.py b/aeon/anomaly_detection/distribution_based/_copod.py
@@ -7,7 +7,7 @@
 
 import numpy as np
 
-from aeon.anomaly_detection._pyodadapter import PyODAdapter
+from aeon.anomaly_detection.outlier_detection._pyodadapter import PyODAdapter
 from aeon.utils.validation._dependencies import _check_soft_dependencies
 
 
diff --git a/aeon/anomaly_detection/distribution_based/_dwt_mlead.py b/aeon/anomaly_detection/distribution_based/_dwt_mlead.py
@@ -78,7 +78,7 @@ class DWT_MLEAD(BaseAnomalyDetector):
     Examples
     --------
     >>> import numpy as np
-    >>> from aeon.anomaly_detection import DWT_MLEAD
+    >>> from aeon.anomaly_detection.distribution_based import DWT_MLEAD
     >>> X = np.array([1, 2, 3, 4, 1, 2, 3, 3, 2, 8, 9, 8, 1, 2, 3, 4], dtype=np.float64)
     >>> detector = DWT_MLEAD(
     ...    start_level=1, quantile_boundary_type='percentile', quantile_epsilon=0.01
diff --git a/aeon/anomaly_detection/distribution_based/tests/__init__.py b/aeon/anomaly_detection/distribution_based/tests/__init__.py
@@ -0,0 +1 @@
+"""Distribution based test code."""
diff --git a/aeon/anomaly_detection/distribution_based/tests/test_copod.py b/aeon/anomaly_detection/distribution_based/tests/test_copod.py
@@ -3,7 +3,7 @@
 import numpy as np
 import pytest
 
-from aeon.anomaly_detection import COPOD
+from aeon.anomaly_detection.distribution_based import COPOD
 from aeon.testing.data_generation import make_example_1d_numpy
 from aeon.utils.validation._dependencies import _check_soft_dependencies
 
diff --git a/aeon/anomaly_detection/distribution_based/tests/test_dwt_mlead.py b/aeon/anomaly_detection/distribution_based/tests/test_dwt_mlead.py
@@ -6,7 +6,7 @@
 import pytest
 from sklearn.utils import check_random_state
 
-from aeon.anomaly_detection import DWT_MLEAD
+from aeon.anomaly_detection.distribution_based import DWT_MLEAD
 
 
 def test_dwt_mlead_output():
diff --git a/aeon/anomaly_detection/outlier_detection/__init__.py b/aeon/anomaly_detection/outlier_detection/__init__.py
@@ -0,0 +1,11 @@
+"""Time Series Outlier Detection."""
+
+__all__ = [
+    "IsolationForest",
+    "PyODAdapter",
+    "STRAY",
+]
+
+from aeon.anomaly_detection.outlier_detection._iforest import IsolationForest
+from aeon.anomaly_detection.outlier_detection._pyodadapter import PyODAdapter
+from aeon.anomaly_detection.outlier_detection._stray import STRAY
diff --git a/aeon/anomaly_detection/outlier_detection/_iforest.py b/aeon/anomaly_detection/outlier_detection/_iforest.py
@@ -7,7 +7,7 @@
 
 import numpy as np
 
-from aeon.anomaly_detection._pyodadapter import PyODAdapter
+from aeon.anomaly_detection.outlier_detection._pyodadapter import PyODAdapter
 from aeon.utils.validation._dependencies import _check_soft_dependencies
 
 
diff --git a/aeon/anomaly_detection/outlier_detection/_pyodadapter.py b/aeon/anomaly_detection/outlier_detection/_pyodadapter.py
@@ -59,7 +59,9 @@ class PyODAdapter(BaseAnomalyDetector):
     --------
     >>> import numpy as np
     >>> from pyod.models.lof import LOF  # doctest: +SKIP
-    >>> from aeon.anomaly_detection import PyODAdapter  # doctest: +SKIP
+    >>> from aeon.anomaly_detection.outlier_detection import (
+    ...     PyODAdapter
+    ... ) # doctest: +SKIP
     >>> X = np.random.default_rng(42).random((10, 2), dtype=np.float64)
     >>> detector = PyODAdapter(LOF(), window_size=2)  # doctest: +SKIP
     >>> detector.fit_predict(X, axis=0)  # doctest: +SKIP
diff --git a/aeon/anomaly_detection/outlier_detection/_stray.py b/aeon/anomaly_detection/outlier_detection/_stray.py
@@ -54,7 +54,7 @@ class STRAY(BaseAnomalyDetector):
 
     Examples
     --------
-    >>> from aeon.anomaly_detection import STRAY
+    >>> from aeon.anomaly_detection.outlier_detection import STRAY
     >>> from aeon.datasets import load_airline
     >>> import numpy as np
     >>> X = load_airline()
diff --git a/aeon/anomaly_detection/outlier_detection/tests/__init__.py b/aeon/anomaly_detection/outlier_detection/tests/__init__.py
@@ -0,0 +1 @@
+"""Outlier based test code."""
diff --git a/aeon/anomaly_detection/outlier_detection/tests/test_iforest.py b/aeon/anomaly_detection/outlier_detection/tests/test_iforest.py
@@ -4,7 +4,7 @@
 import pytest
 from sklearn.utils import check_random_state
 
-from aeon.anomaly_detection import IsolationForest
+from aeon.anomaly_detection.outlier_detection import IsolationForest
 from aeon.utils.validation._dependencies import _check_soft_dependencies
 
 
diff --git a/aeon/anomaly_detection/outlier_detection/tests/test_pyod_adapter.py b/aeon/anomaly_detection/outlier_detection/tests/test_pyod_adapter.py
@@ -6,7 +6,7 @@
 import pytest
 from sklearn.utils import check_random_state
 
-from aeon.anomaly_detection import PyODAdapter
+from aeon.anomaly_detection.outlier_detection import PyODAdapter
 from aeon.utils.validation._dependencies import _check_soft_dependencies
 
 
diff --git a/aeon/anomaly_detection/outlier_detection/tests/test_stray.py b/aeon/anomaly_detection/outlier_detection/tests/test_stray.py
@@ -5,7 +5,7 @@
 import numpy as np
 from sklearn.preprocessing import MinMaxScaler
 
-from aeon.anomaly_detection import STRAY
+from aeon.anomaly_detection.outlier_detection import STRAY
 
 
 def test_default_1D():
diff --git a/aeon/anomaly_detection/whole_series/__init__.py b/aeon/anomaly_detection/whole_series/__init__.py
@@ -0,0 +1,7 @@
+"""Whole Time Series Anomaly Detection."""
+
+__all__ = [
+    "ROCKAD",
+]
+
+from aeon.anomaly_detection.whole_series._rockad import ROCKAD
diff --git a/aeon/anomaly_detection/whole_series/_rockad.py b/aeon/anomaly_detection/whole_series/_rockad.py
diff --git a/aeon/anomaly_detection/whole_series/tests/__init__.py b/aeon/anomaly_detection/whole_series/tests/__init__.py
@@ -0,0 +1 @@
+"""Whole series anomaly detection tests."""
diff --git a/aeon/anomaly_detection/whole_series/tests/test_rockad.py b/aeon/anomaly_detection/whole_series/tests/test_rockad.py
@@ -4,7 +4,7 @@
 import pytest
 from sklearn.utils import check_random_state
 
-from aeon.anomaly_detection import ROCKAD
+from aeon.anomaly_detection.whole_series import ROCKAD
 
 
 def test_rockad_univariate():
diff --git a/docs/api_reference/anomaly_detection.rst b/docs/api_reference/anomaly_detection.rst
@@ -13,29 +13,79 @@ Each detector in this module specifies its supported input data format, output d
 format, and learning type as an overview table in its documentation. Some detectors
 support multiple learning types.
 
-Detectors
----------
+.. note::
 
-.. currentmodule:: aeon.anomaly_detection
+    Not all algorithm families are currently implemented. The documentation includes
+    placeholders for planned categories which will be supported in future.
+
+Distance-based
+--------------
+
+.. currentmodule:: aeon.anomaly_detection.distance_based
 
 .. autosummary::
     :toctree: auto_generated/
     :template: class.rst
 
     CBLOF
-    COPOD
-    DWT_MLEAD
-    IsolationForest
     KMeansAD
     LeftSTAMPi
     LOF
     MERLIN
     OneClassSVM
-    PyODAdapter
-    ROCKAD
     STOMP
+
+Distribution-based
+-----------------
+
+.. currentmodule:: aeon.anomaly_detection.distribution_based
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: class.rst
+
+    COPOD
+    DWT_MLEAD
+
+Encoding-based
+--------------
+
+The algorithms for this family are not implemented yet.
+
+Forecasting-based
+-----------------
+
+The algorithms for this family are not implemented yet.
+
+Outlier-Detection
+-----------------
+
+.. currentmodule:: aeon.anomaly_detection.outlier_detection
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: class.rst
+
+    IsolationForest
+    PyODAdapter
     STRAY
 
+Reconstruction-based
+--------------------
+
+The algorithms for this family are not implemented yet.
+
+Whole-Series
+------------
+
+.. currentmodule:: aeon.anomaly_detection.whole_series
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: class.rst
+
+    ROCKAD
+
 Base
 ----
 
diff --git a/docs/developer_guide/adding_typehints.md b/docs/developer_guide/adding_typehints.md
diff --git a/docs/getting_started.md b/docs/getting_started.md
diff --git a/examples/anomaly_detection/anomaly_detection.ipynb b/examples/anomaly_detection/anomaly_detection.ipynb
