docs: fixes and updates

Author: iraedeus

pysatl_cpd/analysis/labeled_data.py

@@ -101,8 +101,27 @@ def __str__(self) -> str:
 
     @property
     def raw_data(self) -> Collection[T]:
+        """
+        Return the raw observation data.
+
+        Returns
+        -------
+        Collection[T]
+            The sequential observations forming the time series.
+        """
         return self.__raw_data
 
     @property
     def change_points(self) -> Sequence[int]:
+        """
+        Return the known change point indices.
+
+        Each index indicates the first observation after a regime change,
+        i.e., a change occurs between observations at index ``i-1`` and ``i``.
+
+        Returns
+        -------
+        Sequence[int]
+            Indices of change points in the data.
+        """
         return self.__change_points

pysatl_cpd/core/data_providers/idata_provider.py

@@ -32,6 +32,9 @@ class DataProvider[T](ABC):
         The type of a single observation yielded by the provider.
         For univariate data, T is typically a scalar numeric type.
         For multivariate data, T is typically a one-dimensional array.
+    name : str or None, optional
+        Optional human-readable identifier for the data provider.
+        If None, defaults to the class name. Default is None.
     """
 
     def __init__(self, name: str | None) -> None:
@@ -63,5 +66,14 @@ def __len__(self) -> int:
 
     @property
     def name(self) -> str:
-        """Return the name of the DataProvider"""
+        """
+        Return the name of the data provider.
+
+        If no name was provided at initialization, returns the class name.
+
+        Returns
+        -------
+        str
+            Human-readable identifier for this data provider.
+        """
         return self._name

pysatl_cpd/core/data_providers/numpy_data_provider.py

@@ -31,6 +31,9 @@ class NDArrayUnivariateProvider(DataProvider[NumPyNumber]):
     data : NumericArray
         A one-dimensional array of univariate observations. The array must contain
         numeric values and have exactly one dimension.
+    name : str or None, optional
+        Optional human-readable identifier for the data provider.
+        If None, defaults to the class name. Default is None.
 
     Raises
     ------
@@ -106,6 +109,9 @@ class NDArrayMultivariateProvider(DataProvider[UnivariateNumericArray]):
     data : NumericArray
         An array with ``ndim == 2``. The first axis indexes observations over time,
         while the second axis represents multivariate components.
+    name : str or None, optional
+        Optional human-readable identifier for the data provider.
+        If None, defaults to the class name. Default is None.
 
     Raises
     ------

pysatl_cpd/core/detection_trace.py

@@ -34,7 +34,6 @@ class DetectionTrace:
 
     Examples
     --------
-    >>> from pysatl_cpd.data_providers import NDArrayUnivariateProvider
     >>> trace = DetectionTrace(detected_change_points=[2, 4])
     >>> trace.detected_changes
     [2, 4]

pysatl_cpd/core/online/online_cpd_solver.py

@@ -30,12 +30,6 @@ class OnlineCpdSolver:
 
     Parameters
     ----------
-    algorithm : OnlineAlgorithm[DataT, ConfugrationT, StateT]
-        The online change-point detection algorithm to apply.
-    threshold : float, optional
-        Detection threshold for the change-point function. A change point is
-        declared when the statistic exceeds this value.
-        If `nan`, the algorithm will not generate any signals. Default is ``nan``.
     skip_period : int, optional
         Number of steps to skip (suppress detections) after each declared
         change point. Must be non-negative. Default is ``0``.
@@ -62,18 +56,6 @@ def __init__(
         max_runlength: int | None = None,
         collect_states: bool = True,
     ) -> None:
-        """
-        Initialize the online change-point detection solver.
-
-        Parameters
-        ----------
-        skip_period : int, optional
-            Number of steps to skip after each declared change point.
-        max_runlength : int or None, optional
-            Maximum run length before forcing a change point.
-        collect_states : bool, optional
-            Whether to collect algorithm state snapshots.
-        """
         # Validate skip_period is non-negative
         if skip_period < 0:
             raise ValueError(f"skip_period must be non-negative, got {skip_period}")
@@ -102,12 +84,15 @@ def run[DataT, ConfugrationT: OnlineAlgorithmConfiguration, StateT: OnlineAlgori
 
         Parameters
         ----------
-        algorithm : OnlineAlgorithm[T]
+        algorithm : OnlineAlgorithm[DataT, ConfugrationT, StateT]
             The online change-point detection algorithm to apply.
         data_provider : DataProvider[DataT]
             An iterable source of observations.
         threshold : float, optional
-            Detection threshold for the change-point function.
+            Detection threshold for the change-point function. A change point
+            is declared when the statistic exceeds this value.
+            If ``nan``, the algorithm will not generate any signals.
+            Default is ``nan``.
 
         Yields
         ------
@@ -182,7 +167,7 @@ def _is_signal_change_point(self, detection_func: Number, threshold: float) -> b
         ----------
         detection_func : Number
             Current detection statistic value.
-        threshold : floatl
+        threshold : float
             Detection threshold for the change-point function.
 
         Returns

pysatl_cpd/core/online/online_detection_trace.py

@@ -70,17 +70,18 @@ class OnlineDetectionStepResult[StateT: OnlineAlgorithmState]:
     ----------
     step_num : int, default=0
         Zero-based index of the processed observation.
-    is_change_point : bool, default=False
-        Whether a changepoint was detected at this step.
-    is_force_change_point : bool, default=False
+    is_forced_change_point : bool, default=False
         Whether a changepoint was forced due to maximum runlength constraint.
+    is_signal_change_point : bool, default=False
+        Whether a changepoint was detected by the algorithm's detection
+        function exceeding the threshold.
     is_in_skip_period : bool, default=False
         Whether this step occurred during a post-detection skip period.
     detection_function : Number, default=nan
         The value of the detection statistic computed for this observation.
     processing_time : Number, default=nan
         Wall-clock time in seconds spent processing this step.
-    algorithm_state : StateT | None, default=None
+    algorithm_state : StateT or None, default=None
         Snapshot of algorithm internal state after processing this step.
     """
 
@@ -94,6 +95,18 @@ class OnlineDetectionStepResult[StateT: OnlineAlgorithmState]:
 
     @property
     def is_change_point(self) -> bool:
+        """
+        Whether a changepoint was detected at this step.
+
+        A changepoint is considered detected if it was either forced
+        (due to maximum runlength) or signaled (detection function
+        exceeded threshold).
+
+        Returns
+        -------
+        bool
+            True if a forced or signal changepoint occurred, False otherwise.
+        """
         return self.is_forced_change_point or self.is_signal_change_point
 
 
@@ -126,11 +139,11 @@ class OnlineDetectionTrace[StateT: OnlineAlgorithmState](DetectionTrace):
         Indices of beginning and ending of segments where algorithm was
         learning data distribution before change point. Default is empty list.
     forced_change_points : list[int], optional
-        Indices where changepoints were forced due to maximum runlength.
-        Default is empty list.
-    forced_change_points : list[int], optional
-        Indices where changepoints were forced due algorithm detection function
-        overcoming threshold. Default is empty list.
+        Indices where changepoints were forced due to maximum runlength
+        constraint. Default is empty list.
+    signal_change_points : list[int], optional
+        Indices where changepoints were detected due to the algorithm's
+        detection function exceeding the threshold. Default is empty list.
     """
 
     threshold: Number | None = None