Merge pull request #258 from IFCA/feature-doc-api-remaining-examples

Add remaining examples in documentation API

Author: Jaime Céspedes Sisniega

docs/source/api_reference/callbacks/streaming.md

@@ -1,5 +1,8 @@
 # Streaming
 
+The {mod}`frouros.callbacks.streaming` module contains streaming callbacks.
+
+
 ```{eval-rst}
 .. automodule:: frouros.callbacks.streaming
     :no-members:
@@ -12,6 +15,4 @@
     :template: class.md
 
     HistoryConceptDrift
-    mSPRT
-    WarningSamplesBuffer
 ```

frouros/callbacks/__init__.py

@@ -1,12 +1,10 @@
 """Callbacks init."""
 
 from .batch import PermutationTestDistanceBased, ResetStatisticalTest
-from .streaming import HistoryConceptDrift, mSPRT, WarningSamplesBuffer
+from .streaming import HistoryConceptDrift
 
 __all__ = [
     "HistoryConceptDrift",
-    "mSPRT",
     "PermutationTestDistanceBased",
     "ResetStatisticalTest",
-    "WarningSamplesBuffer",
 ]

frouros/callbacks/batch/permutation_test.py

@@ -10,25 +10,49 @@
 
 
 class PermutationTestDistanceBased(BaseCallbackBatch):
-    """Permutation test on distance based batch callback class."""
-
-    def __init__(
+    """Permutation test callback class that can be applied to :mod:`data_drift.batch.distance_based <frouros.detectors.data_drift.batch.distance_based>` detectors.
+
+    :param num_permutations: number of permutations to obtain the p-value
+    :type num_permutations: int
+    :param num_jobs: number of jobs, defaults to -1
+    :type num_jobs: int
+    :param verbose: verbose flag, defaults to False
+    :type verbose: bool
+    :param name: name value, defaults to None. If None, the name will be set to `PermutationTestDistanceBased`.
+    :type name: Optional[str]
+
+    :Note:
+    Callbacks logs are updated with the following variables:
+
+    - `observed_statistic`: observed statistic obtained from the distance-based detector. Same distance value returned by the `compare` method
+    - `permutation_statistic`: list of statistics obtained from the permutations
+    - `p_value`: p-value obtained from the permutation test
+
+    :Example:
+
+    >>> from frouros.callbacks import PermutationTestDistanceBased
+    >>> from frouros.detectors.data_drift import MMD
+    >>> import numpy as np
+    >>> np.random.seed(seed=31)
+    >>> X = np.random.multivariate_normal(mean=[1, 1], cov=[[2, 0], [0, 2]], size=100)
+    >>> Y = np.random.multivariate_normal(mean=[0, 0], cov=[[2, 1], [1, 2]], size=100)
+    >>> detector = MMD(callbacks=PermutationTestDistanceBased(num_permutations=1000, random_state=31))
+    >>> _ = detector.fit(X=X)
+    >>> distance, callbacks_log = detector.compare(X=Y)
+    >>> distance
+    DistanceResult(distance=0.05643613752975596)
+    >>> callbacks_log["PermutationTestDistanceBased"]["p_value"]
+    0.0
+    """  # noqa: E501  # pylint: disable=line-too-long
+
+    def __init__(  # noqa: D107
         self,
         num_permutations: int,
         num_jobs: int = -1,
-        name: Optional[str] = None,
         verbose: bool = False,
+        name: Optional[str] = None,
         **kwargs,
     ) -> None:
-        """Init method.
-
-        :param num_permutations: number of permutations
-        :type num_permutations: int
-        :param num_jobs: number of jobs
-        :type num_jobs: int
-        :param name: name to be use
-        :type name: Optional[str]
-        """
         super().__init__(name=name)
         self.num_permutations = num_permutations
         self.num_jobs = num_jobs

frouros/callbacks/batch/reset.py

@@ -7,16 +7,33 @@
 
 
 class ResetStatisticalTest(BaseCallbackBatch):
-    """Reset on statistical test batch callback class."""
+    """Reset callback class that can be applied to :mod:`data_drift.batch.statistical_test <frouros.detectors.data_drift.batch.statistical_test>` detectors.
 
-    def __init__(self, alpha: float, name: Optional[str] = None) -> None:
-        """Init method.
+    :param alpha: significance value
+    :type alpha: float
+    :param name: name value, defaults to None. If None, the name will be set to `ResetStatisticalTest`.
+    :type name: Optional[str]
 
-        :param alpha: significance value
-        :type alpha: float
-        :param name: name to be use
-        :type name: Optional[str]
-        """
+    :Example:
+
+    >>> from frouros.callbacks import ResetStatisticalTest
+    >>> from frouros.detectors.data_drift import KSTest
+    >>> 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 = KSTest(callbacks=ResetStatisticalTest(alpha=0.01))
+    >>> _ = detector.fit(X=X)
+    >>> detector.compare(X=Y)[0]
+    INFO:frouros:Drift detected. Resetting detector...
+    StatisticalResult(statistic=0.55, p_value=3.0406585087050305e-14)
+    """  # noqa: E501  # pylint: disable=line-too-long
+
+    def __init__(  # noqa: D107
+        self,
+        alpha: float,
+        name: Optional[str] = None,
+    ) -> None:
         super().__init__(name=name)
         self.alpha = alpha
 

frouros/callbacks/streaming/__init__.py

@@ -1,11 +1,7 @@
 """Streaming callbacks init."""
 
 from .history import HistoryConceptDrift
-from .msprt import mSPRT
-from .warning_samples import WarningSamplesBuffer
 
 __all__ = [
     "HistoryConceptDrift",
-    "mSPRT",
-    "WarningSamplesBuffer",
 ]

frouros/callbacks/streaming/history.py

@@ -7,14 +7,44 @@
 
 
 class HistoryConceptDrift(BaseCallbackStreaming):
-    """HistoryConceptDrift callback class."""
+    """HistoryConceptDrift callback class that can be applied to :mod:`concept_drift.streaming <frouros.detectors.concept_drift.streaming>` detectors.
 
-    def __init__(self, name: Optional[str] = None) -> None:
-        """Init method.
+    :param name: name value, defaults to None. If None, the name will be set to `HistoryConceptDrift`.
+    :type name: Optional[str]
 
-        :param name: name value
-        :type name: Optional[str]
-        """
+    :Note:
+    By default the following variables are stored:
+
+    - `value`: list of values received by the detector
+    - `drift`: list of drift flags
+    - `num_instances`: list of number of instances received by the detector
+    Each detector may store additional variables if they are defined in an `additional_vars` dictionary in the detectors `__init__` method.
+    The user can add additional variables by calling the :func:`add_additional_vars` method.
+
+    :Example:
+
+    >>> from frouros.callbacks import HistoryConceptDrift
+    >>> from frouros.detectors.concept_drift import ADWIN
+    >>> import numpy as np
+    >>> np.random.seed(seed=31)
+    >>> dist_a = np.random.normal(loc=0.2, scale=0.01, size=1000)
+    >>> dist_b = np.random.normal(loc=0.8, scale=0.04, size=1000)
+    >>> stream = np.concatenate((dist_a, dist_b))
+    >>> detector = ADWIN(callbacks=[HistoryConceptDrift(name="history")])
+    >>> for i, value in enumerate(stream):
+    ...     callbacks_log = detector.update(value=value)
+    ...     if detector.drift:
+    ...         print(f"Change detected at step {i}")
+    ...         break
+    Change detected at step 1055
+    >>> callbacks_log["history"]["drift"]
+    [False, False, ..., True]
+    """  # noqa: E501  # pylint: disable=line-too-long
+
+    def __init__(  # noqa: D107
+        self,
+        name: Optional[str] = None,
+    ) -> None:
         super().__init__(name=name)
         self.additional_vars: List[str] = []
         self.history: Dict[str, List[Any]] = {
@@ -24,7 +54,7 @@ def __init__(self, name: Optional[str] = None) -> None:
         }
 
     def add_additional_vars(self, vars_: List[str]) -> None:
-        """Add addtional variables to track.
+        """Add additional variables to track.
 
         :param vars_: list of variables
         :type vars_: List[str]