[DEP] Deprecate znormalized in favor of znormalize in SAX

aeon/transformations/collection/dictionary_based/_sax.py

@@ -3,6 +3,8 @@
 __maintainer__ = []
 __all__ = ["SAX", "_invert_sax_symbols"]
 
+import warnings
+
 import numpy as np
 import scipy.stats
 from numba import get_num_threads, njit, prange, set_num_threads
@@ -42,10 +44,9 @@ class SAX(BaseCollectionTransformer):
         the parameters of the used distribution, if the used
         distribution is "Gaussian" and this parameter is None
         then the default setup is {"scale" : 1.0}
-    znormalized : bool, default = True,
-        Whether the input is already z-normalized. If False, each complete
-        series is normalized before PAA when ``window_size=None``. When
-        windowing is enabled, each extracted window is normalized independently
+    znormalize : bool, default = True,
+        Whether to z-normalize each series before PAA when ``window_size=None``.
+        When windowing is enabled, each extracted window is normalized independently
         before PAA, as required by the sliding-window SAX formulation.
     window_size : int, default = None,
         The size of the sliding window to use when transforming the time series,
@@ -57,6 +58,10 @@ class SAX(BaseCollectionTransformer):
         only used when the window_size parameter is not None.
     n_jobs : int, default = 1,
         The number of jobs to run in parallel for both `fit` and `transform`.
+    znormalized : bool, default="deprecated"
+        Old identifier for ``znormalize``.
+
+        Deprecated and will be removed in v1.7.0.
 
     Notes
     -----
@@ -85,17 +90,19 @@ class SAX(BaseCollectionTransformer):
         "algorithm_type": "dictionary",
     }
 
+    # TODO remove 'znormalized' in v1.7.0
     def __init__(
         self,
         n_segments: int = 8,
         alphabet_size: int = 4,
         alphabet: list = None,
         distribution: str = "Gaussian",
         distribution_params: dict = None,
-        znormalized: bool = True,
+        znormalize: bool = True,
         window_size: int = None,
         stride: int = 1,
         n_jobs: int = 1,
+        znormalized: bool = "deprecated",
     ):
         self.n_segments = n_segments
 
@@ -110,11 +117,21 @@ def __init__(
         self.distribution = distribution
         self.n_jobs = n_jobs
         self.distribution_params = distribution_params
-        self.znormalized = znormalized
-
         self.window_size = window_size
         self.stride = stride
 
+        self.znormalize = znormalize
+        self.znormalized = znormalized
+
+        if znormalized != "deprecated":
+            warnings.warn(
+                "The 'znormalized' parameter of SAX is deprecated and will be "
+                "removed in v1.7.0. Please use 'znormalize' instead.",
+                FutureWarning,
+                stacklevel=2,
+            )
+            self.znormalize = not znormalized
+
         if self.distribution == "Gaussian":
             self.distribution_params_ = (
                 dict(scale=1.0)
@@ -181,7 +198,7 @@ def _get_paa(self, X):
         X_paa : np.ndarray of shape = (n_cases, n_channels, n_segments)
             The output of the PAA transformation
         """
-        if not self.znormalized:
+        if self.znormalize:
             X = self._z_normalize(X)
 
         paa = PAA(n_segments=self.n_segments, n_jobs=self.n_jobs)
@@ -235,7 +252,7 @@ def _transform(self, X, y=None):
             self.window_size,
         )
 
-        if self.znormalized:
+        if not self.znormalize:
             X_windows_normalized = X_windows_3d
             self._window_means_ = None
             self._window_stds_ = None
@@ -333,12 +350,12 @@ def inverse_sax(
         window_means : np.ndarray, optional
             Per-window means with shape
             (n_cases, n_channels, n_windows, 1). Required to restore the
-            original scale when ``znormalized=False`` unless the statistics
+            original scale when ``znormalize=True`` unless the statistics
             were stored by the most recent call to ``transform``.
         window_stds : np.ndarray, optional
             Per-window standard deviations with shape
             (n_cases, n_channels, n_windows, 1). Required to restore the
-            original scale when ``znormalized=False`` unless the statistics
+            original scale when ``znormalize=True`` unless the statistics
             were stored by the most recent call to ``transform``.
 
         Returns
@@ -411,7 +428,7 @@ def inverse_sax(
                         "covered by the SAX windows"
                     )
 
-                if self.znormalized:
+                if not self.znormalize:
                     if window_means is None:
                         window_means = np.zeros(
                             (
@@ -442,7 +459,7 @@ def inverse_sax(
                         raise ValueError(
                             "window_means and window_stds are required to "
                             "denormalize windowed SAX output when "
-                            "znormalized=False"
+                            "znormalize=True"
                         )
 
                 window_means = np.asarray(
@@ -483,7 +500,7 @@ def inverse_sax(
                     breakpoints_mid=self.breakpoints_mid,
                     window_means=window_means,
                     window_stds=window_stds,
-                    denormalize=not self.znormalized,
+                    denormalize=self.znormalize,
                 )
 
             raise ValueError(