Merge pull request #255 from IFCA/feature-doc-api-detectors-examples

Add detectors examples in documentation API

Author: Jaime Céspedes Sisniega

frouros/detectors/concept_drift/streaming/change_detection/base.py

@@ -26,21 +26,19 @@ def _update(self, value: Union[int, float], **kwargs) -> None:
 
 
 class BaseCUSUMConfig(BaseChangeDetectionConfig):
-    """Class representing a CUSUM based configuration class."""
+    """Class representing a CUSUM based configuration class.
 
-    def __init__(
+    :param lambda_: lambda value, defaults to 50.0
+    :type lambda_: float
+    :param min_num_instances: minimum numbers of instances to start looking for changes, defaults to 30
+    :type min_num_instances: int
+    """  # noqa: E501  # pylint: disable=line-too-long
+
+    def __init__(  # noqa: D107
         self,
         lambda_: float = 50.0,
         min_num_instances: int = 30,
     ) -> None:
-        """Init method.
-
-        :param lambda_: lambda value
-        :type lambda_: float
-        :param min_num_instances: minimum numbers of instances
-        to start looking for changes
-        :type min_num_instances: int
-        """
         super().__init__(min_num_instances=min_num_instances)
         self.lambda_ = lambda_
 
@@ -139,25 +137,23 @@ def alpha(self, value: float) -> None:
 
 
 class BaseCUSUM(BaseChangeDetection):
-    """CUSUM based algorithm class."""
+    """CUSUM based algorithm class.
+
+    :param config: configuration parameters, defaults to None
+    :type config: Optional[BaseCUSUMConfig]
+    :param callbacks: callbacks, defaults to None
+    :type callbacks: Optional[Union[BaseCallbackStreaming, List[BaseCallbackStreaming]]]
+    """  # noqa: E501
 
     config_type = BaseCUSUMConfig
 
-    def __init__(
+    def __init__(  # noqa: D107
         self,
         config: Optional[BaseCUSUMConfig] = None,
         callbacks: Optional[
             Union[BaseCallbackStreaming, List[BaseCallbackStreaming]]
         ] = None,
     ) -> None:
-        """Init method.
-
-        :param config: configuration parameters
-        :type config: Optional[BaseCUSUMConfig]
-        :param callbacks: callbacks
-        :type callbacks: Optional[Union[BaseCallbackStreaming,
-        List[BaseCallbackStreaming]]]
-        """
         super().__init__(
             config=config,
             callbacks=callbacks,

frouros/detectors/concept_drift/streaming/change_detection/bocd.py

@@ -2,12 +2,13 @@
 
 import abc
 import copy
-from typing import Union, Optional
+from typing import List, Union, Optional
 
 import numpy as np  # type: ignore
 from scipy.special import logsumexp  # type: ignore
 from scipy.stats import norm  # type: ignore
 
+from frouros.callbacks.streaming.base import BaseCallbackStreaming
 from frouros.detectors.concept_drift.streaming.change_detection.base import (
     BaseChangeDetection,
     BaseChangeDetectionConfig,
@@ -41,7 +42,8 @@ def update(self, value: Union[int, float], **kwargs) -> None:
 class GaussianUnknownMean(BaseBOCDModel):
     """Gaussian unknown mean model.
 
-    (adapted from the implementation in https://github.com/gwgundersen/bocd)
+    :Note:
+     Adapted from the implementation in https://github.com/gwgundersen/bocd.
     """
 
     def __init__(
@@ -121,33 +123,32 @@ def var_params(self):
 class BOCDConfig(BaseChangeDetectionConfig):
     """BOCD (Bayesian Online Change Detection) [adams2007bayesian]_ configuration.
 
+    :param model: BOCD model, defaults to None. If None, :class:`frouros.detectors.concept_drift.streaming.change_detection.bocd.GaussianUnknownMean` is used.
+    :type model: Optional[BaseBOCDModel]
+    :param hazard: hazard value, defaults to 0.01
+    :type hazard: float
+    :param min_num_instances: minimum numbers of instances to start looking for changes, defaults to 30
+    :type min_num_instances: int
+
     :References:
 
     .. [adams2007bayesian] Adams, Ryan Prescott, and David JC MacKay.
         "Bayesian online changepoint detection."
         arXiv preprint arXiv:0710.3742 (2007).
-    """
+    """  # noqa: E501  pylint: disable=line-too-long
 
-    def __init__(
+    model_type = GaussianUnknownMean
+
+    def __init__(  # noqa: D107
         self,
-        model: BaseBOCDModel = GaussianUnknownMean,  # type: ignore
+        model: Optional[BaseBOCDModel] = None,  # type: ignore
         hazard: float = 0.01,
         min_num_instances: int = 30,
     ) -> None:
-        """Init method.
-
-        :param model: BOCD model
-        :type model: BaseBOCDModel
-        :param hazard: hazard value
-        :type hazard: float
-        :param min_num_instances: minimum numbers of instances
-        to start looking for changes
-        :type min_num_instances: int
-        """
         super().__init__(
             min_num_instances=min_num_instances,
         )
-        self.model = model
+        self.model = model  # type: ignore
         self.log_hazard = np.log(hazard)
         self.log_1_minus_hazard = np.log(1 - hazard)
 
@@ -168,35 +169,59 @@ def model(self, model: BaseBOCDModel) -> None:
         :type model: BaseBOCDModel
         :raises TypeError: if model is not an instance of BaseModel
         """
-        if not isinstance(model, BaseBOCDModel):
-            raise TypeError(
-                f"model must be an instance of BaseModel, not {type(model)}"
-            )
-        self._model = model
+        if model is not None:
+            if not isinstance(model, BaseBOCDModel):
+                raise TypeError(
+                    f"model must be an instance of BaseModel, not {type(model)}"
+                )
+            self._model = model
+        else:
+            self._model = self.model_type()
 
 
 class BOCD(BaseChangeDetection):
     """BOCD (Bayesian Online Change Detection) [adams2007bayesian]_ detector.
 
-     (adapted from the implementation in https://github.com/gwgundersen/bocd)
+    :param config: configuration object of the detector, defaults to None. If None, the default configuration of :class:`BOCDConfig` is used.
+    :type config: Optional[BOCDConfig]
+    :param callbacks: callbacks, defaults to None
+    :type callbacks: Optional[Union[BaseCallbackStreaming, List[BaseCallbackStreaming]]]
+
+    :Note:
+     Adapted from the implementation in https://github.com/gwgundersen/bocd.
 
     :References:
 
     .. [adams2007bayesian] Adams, Ryan Prescott, and David JC MacKay.
         "Bayesian online changepoint detection."
         arXiv preprint arXiv:0710.3742 (2007).
-    """
 
-    config_type = BOCDConfig  # type: ignore
+    :Example:
+
+    >>> from frouros.detectors.concept_drift import BOCD
+    >>> 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 = BOCD()
+    >>> for i, value in enumerate(stream):
+    ...     _ = detector.update(value=value)
+    ...     if detector.drift:
+    ...         print(f"Change detected at step {i}")
+    ...         break
+    Change detected at step 1031
+    """  # noqa: E501  # pylint: disable=line-too-long
 
-    def __init__(self, config: BOCDConfig, callbacks: list = None) -> None:
-        """Init method.
+    config_type = BOCDConfig  # type: ignore
 
-        :param config: configuration object of the detector
-        :type config: BOCDConfig
-        :param callbacks: list of callbacks, defaults to None
-        :type callbacks: list, optional
-        """
+    def __init__(  # noqa: D107
+        self,
+        config: Optional[BOCDConfig] = None,
+        callbacks: Optional[
+            Union[BaseCallbackStreaming, List[BaseCallbackStreaming]]
+        ] = None,
+    ) -> None:
         super().__init__(
             config=config,
             callbacks=callbacks,

frouros/detectors/concept_drift/streaming/change_detection/cusum.py

@@ -1,7 +1,10 @@
 """CUSUM module."""
 
+from typing import Optional, Union, List
+
 import numpy as np  # type: ignore
 
+from frouros.callbacks.streaming.base import BaseCallbackStreaming
 from frouros.detectors.concept_drift.streaming.change_detection.base import (
     BaseCUSUM,
     BaseCUSUMConfig,
@@ -12,29 +15,26 @@
 class CUSUMConfig(BaseCUSUMConfig, DeltaConfig):
     """CUSUM [page1954continuous]_ configuration.
 
+    :param delta: delta value, defaults to 0.005
+    :type delta: float
+    :param lambda_: delta value, defaults to 50.0
+    :type lambda_: float
+    :param min_num_instances: minimum numbers of instances to start looking for changes, defaults to 30
+    :type min_num_instances: int
+
     :References:
 
     .. [page1954continuous] Page, Ewan S.
         "Continuous inspection schemes."
         Biometrika 41.1/2 (1954): 100-115.
-    """
+    """  # noqa: E501  # pylint: disable=line-too-long
 
-    def __init__(
+    def __init__(  # noqa: D107
         self,
         delta: float = 0.005,
         lambda_: float = 50.0,
         min_num_instances: int = 30,
     ) -> None:
-        """Init method.
-
-        :param delta: delta value
-        :type delta: float
-        :param lambda_: delta value
-        :type lambda_: float
-        :param min_num_instances: minimum numbers of instances
-        to start looking for changes
-        :type min_num_instances: int
-        """
         BaseCUSUMConfig.__init__(
             self, lambda_=lambda_, min_num_instances=min_num_instances
         )
@@ -44,15 +44,48 @@ def __init__(
 class CUSUM(BaseCUSUM):
     """CUSUM [page1954continuous]_ detector.
 
+    :param config: configuration object of the detector, defaults to None. If None, the default configuration of :class:`CUSUMConfig` is used.
+    :type config: Optional[CUSUMConfig]
+    :param callbacks: callbacks, defaults to None
+    :type callbacks: Optional[Union[BaseCallbackStreaming, List[BaseCallbackStreaming]]]
+
     :References:
 
     .. [page1954continuous] Page, Ewan S.
         "Continuous inspection schemes."
         Biometrika 41.1/2 (1954): 100-115.
-    """
+
+    :Example:
+
+    >>> from frouros.detectors.concept_drift import CUSUM
+    >>> 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 = CUSUM()
+    >>> for i, value in enumerate(stream):
+    ...     _ = detector.update(value=value)
+    ...     if detector.drift:
+    ...         print(f"Change detected at step {i}")
+    ...         break
+    Change detected at step 1086
+    """  # noqa: E501  # pylint: disable=line-too-long
 
     config_type = CUSUMConfig  # type: ignore
 
+    def __init__(  # noqa: D107
+        self,
+        config: Optional[CUSUMConfig] = None,
+        callbacks: Optional[
+            Union[BaseCallbackStreaming, List[BaseCallbackStreaming]]
+        ] = None,
+    ) -> None:
+        super().__init__(
+            config=config,
+            callbacks=callbacks,
+        )
+
     def _update_sum(self, error_rate: float) -> None:
         self.sum_ = np.maximum(
             0,