Add Kuiper's test data drift method

README.md

@@ -335,8 +335,8 @@ The currently implemented detectors are listed in the following table.
     <td style="text-align: center; border: 1px solid grey; padding: 8px;"><a href="https://doi.org/10.1007/978-3-540-75488-6_27">Nishida and Yamauchi (2007)</a></td>
   </tr>
   <tr>
-    <td rowspan="18" style="text-align: center; border: 1px solid grey; padding: 8px;">Data drift</td>
-    <td rowspan="16" style="text-align: center; border: 1px solid grey; padding: 8px;">Batch</td>
+    <td rowspan="19" style="text-align: center; border: 1px solid grey; padding: 8px;">Data drift</td>
+    <td rowspan="17" style="text-align: center; border: 1px solid grey; padding: 8px;">Batch</td>
     <td rowspan="9" style="text-align: center; border: 1px solid grey; padding: 8px;">Distance based</td>
     <td style="text-align: center; border: 1px solid grey; padding: 8px;">U</td>
     <td style="text-align: center; border: 1px solid grey; padding: 8px;">N</td>
@@ -392,7 +392,7 @@ The currently implemented detectors are listed in the following table.
     <td style="text-align: center; border: 1px solid grey; padding: 8px;"><a href="https://doi.org/10.1057/jors.2008.144">Wu and Olson (2010)</a></td>
   </tr>
   <tr>
-    <td rowspan="7" style="text-align: center; border: 1px solid grey; padding: 8px;">Statistical test</td>
+    <td rowspan="8" style="text-align: center; border: 1px solid grey; padding: 8px;">Statistical test</td>
     <td style="text-align: center; border: 1px solid grey; padding: 8px;">U</td>
     <td style="text-align: center; border: 1px solid grey; padding: 8px;">N</td>
     <td style="text-align: center; border: 1px solid grey; padding: 8px;">Anderson-Darling test</td>
@@ -421,6 +421,12 @@ The currently implemented detectors are listed in the following table.
     <td style="text-align: center; border: 1px solid grey; padding: 8px;">Kolmogorov-Smirnov test</td>
     <td style="text-align: center; border: 1px solid grey; padding: 8px;"><a href="https://doi.org/10.2307/2280095">Massey Jr (1951)</a></td>
   </tr>
+  <tr>
+    <td style="text-align: center; border: 1px solid grey; padding: 8px;">U</td>
+    <td style="text-align: center; border: 1px solid grey; padding: 8px;">N</td>
+    <td style="text-align: center; border: 1px solid grey; padding: 8px;">Kuiper's test</td>
+    <td style="text-align: center; border: 1px solid grey; padding: 8px;"><a href="https://doi.org/10.1016/S1385-7258(60)50006-0">Kuiper (1960)</a></td>
+  </tr>
   <tr>
     <td style="text-align: center; border: 1px solid grey; padding: 8px;">U</td>
     <td style="text-align: center; border: 1px solid grey; padding: 8px;">N</td>

docs/source/api_reference/detectors/data_drift/batch.md

@@ -53,6 +53,7 @@ The {mod}`frouros.detectors.data_drift.batch` module contains batch data drift d
     ChiSquareTest
     CVMTest
     KSTest
+    KuiperTest
     MannWhitneyUTest
     WelchTTest
 ```

frouros/detectors/data_drift/__init__.py

@@ -13,6 +13,7 @@
     JS,
     KL,
     KSTest,
+    KuiperTest,
     PSI,
     MannWhitneyUTest,
     MMD,
@@ -34,6 +35,7 @@
     "JS",
     "KL",
     "KSTest",
+    "KuiperTest",
     "PSI",
     "MannWhitneyUTest",
     "MMDStreaming",

frouros/detectors/data_drift/batch/__init__.py

@@ -17,6 +17,7 @@
     ChiSquareTest,
     CVMTest,
     KSTest,
+    KuiperTest,
     MannWhitneyUTest,
     WelchTTest,
 )
@@ -34,6 +35,7 @@
     "JS",
     "KL",
     "KSTest",
+    "KuiperTest",
     "PSI",
     "MannWhitneyUTest",
     "MMD",

frouros/detectors/data_drift/batch/statistical_test/__init__.py

@@ -5,6 +5,7 @@
 from .chisquare import ChiSquareTest
 from .cvm import CVMTest
 from .ks import KSTest
+from .kuiper_test import KuiperTest
 from .mann_whitney_u import MannWhitneyUTest
 from .welch_t_test import WelchTTest
 
@@ -14,6 +15,7 @@
     "ChiSquareTest",
     "CVMTest",
     "KSTest",
+    "KuiperTest",
     "MannWhitneyUTest",
     "WelchTTest",
 ]

frouros/detectors/data_drift/batch/statistical_test/kuiper_test.py

@@ -0,0 +1,164 @@
+"""Kuiper's test module."""
+
+from typing import Optional, Union
+
+import numpy as np  # type: ignore
+from scipy.special import comb, factorial  # type: ignore
+from scipy.stats import ks_2samp  # type: ignore
+
+from frouros.callbacks.batch.base import BaseCallbackBatch
+from frouros.detectors.data_drift.base import NumericalData, UnivariateData
+from frouros.detectors.data_drift.batch.statistical_test.base import (
+    BaseStatisticalTest,
+    StatisticalResult,
+)
+
+
+class KuiperTest(BaseStatisticalTest):
+    """Kuiper's test [kuiper1960tests]_ detector.
+
+    :param callbacks: callbacks, defaults to None
+    :type callbacks: Optional[Union[BaseCallbackBatch, list[BaseCallbackBatch]]]
+
+    :References:
+
+    .. [kuiper1960tests] Kuiper, Nicolaas H.
+        "Tests concerning random points on a circle."
+        Nederl. Akad. Wetensch. Proc. Ser. A. Vol. 63. No. 1. 1960.
+
+    :Example:
+
+    >>> from frouros.detectors.data_drift import KuiperTest
+    >>> import numpy as np
+    >>> np.random.seed(seed=31)
+    >>> X = np.random.normal(loc=0, scale=1, size=100)
+    >>> Y = np.random.normal(loc=1, scale=1, size=100)
+    >>> detector = KuiperTest()
+    >>> _ = detector.fit(X=X)
+    >>> detector.compare(X=Y)[0]
+    StatisticalResult(statistic=0.55, p_value=5.065664859580971e-13)
+    """  # noqa: E501  # pylint: disable=line-too-long
+
+    def __init__(  # noqa: D107
+        self,
+        callbacks: Optional[Union[BaseCallbackBatch, list[BaseCallbackBatch]]] = None,
+    ) -> None:
+        super().__init__(
+            data_type=NumericalData(),
+            statistical_type=UnivariateData(),
+            callbacks=callbacks,
+        )
+
+    @staticmethod
+    def _statistical_test(
+        X_ref: np.ndarray,  # noqa: N803
+        X: np.ndarray,
+        **kwargs,
+    ) -> StatisticalResult:
+        statistic, p_value = KuiperTest._kuiper(
+            X=X_ref,
+            Y=X,
+            **kwargs,
+        )
+        test = StatisticalResult(
+            statistic=statistic,
+            p_value=p_value,
+        )
+        return test
+
+    @staticmethod
+    def _false_positive_probability(
+        D: float,  # noqa: N803
+        N: float,
+    ) -> float:
+        """
+        Compute the false positive probability for the Kuiper's test.
+
+        NOTE: This function is a modified version of the
+        `kuiper_false_positive_probability` function from the
+        `astropy.stats` <https://docs.astropy.org/en/stable/api/astropy.stats.kuiper_false_positive_probability.html#astropy.stats.kuiper_false_positive_probability> package.  # noqa: E501
+
+        :param D: Kuiper's statistic
+        :param D: float
+        :param N: effective size of the sample
+        :type N: float
+        :return: false positive probability
+        :rtype: float
+        """
+        if D < 2.0 / N:
+            return 1.0 - factorial(N) * (D - 1.0 / N) ** (N - 1)
+
+        if D < 3.0 / N:
+            k = -(N * D - 1.0) / 2.0
+            r = np.sqrt(k**2 - (N * D - 2.0) ** 2 / 2.0)
+            a, b = -k + r, -k - r
+            return 1 - (
+                factorial(N - 1)
+                * (b ** (N - 1) * (1 - a) - a ** (N - 1) * (1 - b))
+                / N ** (N - 2)
+                / (b - a)
+            )
+
+        if (D > 0.5 and N % 2 == 0) or (D > (N - 1.0) / (2.0 * N) and N % 2 == 1):
+            # NOTE: the upper limit of this sum is taken from Stephens 1965
+            t = np.arange(np.floor(N * (1 - D)) + 1)
+            y = D + t / N
+            Tt = y ** (t - 3) * (  # noqa: N806
+                y**3 * N
+                - y**2 * t * (3 - 2 / N)
+                + y * t * (t - 1) * (3 - 2 / N) / N
+                - t * (t - 1) * (t - 2) / N**2
+            )
+            term1 = comb(N, t)
+            term2 = (1 - D - t / N) ** (N - t - 1)
+            # term1 is formally finite, but is approximated by numpy as np.inf for
+            # large values, so we set them to zero manually when they would be
+            # multiplied by zero anyway
+            term1[(term1 == np.inf) & (term2 == 0)] = 0.0
+            return (Tt * term1 * term2).sum()
+
+        z = D * np.sqrt(N)
+        # When m*z>18.82 (sqrt(-log(finfo(double))/2)), exp(-2m**2z**2)
+        # underflows.  Cutting off just before avoids triggering a (pointless)
+        # underflow warning if `under="warn"`.
+        ms = np.arange(1, 18.82 / z)
+        S1 = (  # noqa: N806
+            2 * (4 * ms**2 * z**2 - 1) * np.exp(-2 * ms**2 * z**2)
+        ).sum()
+        S2 = (  # noqa: N806
+            ms**2 * (4 * ms**2 * z**2 - 3) * np.exp(-2 * ms**2 * z**2)
+        ).sum()
+        return S1 - 8 * D / 3 * S2
+
+    @staticmethod
+    def _kuiper(
+        X: np.ndarray,  # noqa: N803
+        Y: np.ndarray,
+    ) -> tuple[float, float]:
+        """Kuiper's test.
+
+        :param X: reference data
+        :type X: numpy.ndarray
+        :param Y: test data
+        :type Y: numpy.ndarray
+        :return: Kuiper's statistic and p-value
+        :rtype: tuple[float, float]
+        """
+        X = np.sort(X)  # noqa: N806
+        Y = np.sort(Y)  # noqa: N806
+        X_size = len(X)  # noqa: N806
+        Y_size = len(Y)  # noqa: N806
+
+        statistic = ks_2samp(
+            data1=X,
+            data2=Y,
+            alternative="two-sided",
+        ).statistic
+        sample_effective_size = X_size * Y_size / float(X_size + Y_size)
+
+        p_value = KuiperTest._false_positive_probability(
+            D=statistic,
+            N=sample_effective_size,
+        )
+
+        return statistic, p_value

frouros/tests/integration/test_callback.py

@@ -37,6 +37,7 @@
     JS,
     KL,
     KSTest,
+    KuiperTest,
     MannWhitneyUTest,
     MMD,
     PSI,
@@ -143,6 +144,7 @@ def test_batch_permutation_test_conservative(
         BWSTest,
         CVMTest,
         KSTest,
+        KuiperTest,
         MannWhitneyUTest,
         WelchTTest,
     ],

frouros/tests/integration/test_data_drift.py

@@ -12,6 +12,7 @@
     ChiSquareTest,
     CVMTest,
     KSTest,
+    KuiperTest,
     MannWhitneyUTest,
     WelchTTest,
 )
@@ -179,6 +180,7 @@ def test_batch_distance_bins_based_univariate_same_distribution(
         ),
         (CVMTest(), 3776.09848103, 5.38105056e-07, {}),
         (KSTest(), 0.99576271, 0.0, {}),
+        (KuiperTest(), 0.99576271, 0.0, {}),
         (MannWhitneyUTest(), 6912.0, 0.0, {}),
         (WelchTTest(), -287.92032554, 0.0, {}),
     ],

tox.ini

@@ -86,7 +86,7 @@ skip_install = {[base]skip_install}
 deps =
     pylint>=3.0.3,<3.1.0
 commands =
-    pylint {[base]package} --good-names=b,d,df,e,f,h,i,j,m,n,p,w,x,y,z,r,X,en,js,kl,XY_chunks_combinations,X_chunks,X_chunks_combinations,X_concat,X_counter,X_extra,X_fold_test,X_fold_train,X_hist,X_merge,X_new_context,X_new_ref,X_num_samples,X_queue,X_sorted,X_percents,X_permuted,X_permuted_num_samples,X_permuted_,X_permuted_concat,X_permuted_ref_,X_permuted_ref_num_samples,X_preprocessed,X_ref,X_ref_hist,X_ref_counter,X_ref_percents,X_ref_rvs,X_ref_rv_histogram,X_rvs,X_rv_histogram,X_ref,_X_ref,X_ref_num_samples,X_ref_univariate,X_ref_multivariate,X_sample,X_samples,X_test,X_test_univariate,X_test_multivariate,X_train,y,Y,Y_chunks,Y_chunks_copy,Y_chunks_combinations,Y_hist,Y_percents,Y_num_samples,_X_num_samples --disable=too-many-instance-attributes,consider-using-with,too-few-public-methods --ignore-comments=yes --ignore-docstrings=yes --ignore-imports=yes --max-args=7 --min-similarity-lines=13 --extension-pkg-whitelist=scipy.special
+    pylint {[base]package} --good-names=b,d,df,e,f,h,i,j,m,n,p,w,x,y,z,r,D,N,X,en,js,kl,S1,S2,Tt,XY_chunks_combinations,X_chunks,X_chunks_combinations,X_concat,X_counter,X_extra,X_fold_test,X_fold_train,X_hist,X_merge,X_new_context,X_new_ref,X_num_samples,X_queue,X_sorted,X_percents,X_permuted,X_permuted_num_samples,X_permuted_,X_permuted_concat,X_permuted_ref_,X_permuted_ref_num_samples,X_preprocessed,X_ref,X_ref_hist,X_ref_counter,X_ref_percents,X_ref_rvs,X_ref_rv_histogram,X_rvs,X_rv_histogram,X_ref,_X_ref,X_ref_num_samples,X_ref_univariate,X_ref_multivariate,X_sample,X_samples,X_test,X_test_univariate,X_test_multivariate,X_train,y,Y,Y_chunks,Y_chunks_copy,Y_chunks_combinations,Y_hist,Y_percents,Y_num_samples,_X_num_samples,X_size,Y_size --disable=too-many-instance-attributes,consider-using-with,too-few-public-methods --ignore-comments=yes --ignore-docstrings=yes --ignore-imports=yes --max-args=7 --min-similarity-lines=13 --extension-pkg-whitelist=scipy.special
 
 [testenv:linters]
 skip_install = {[base]skip_install}