Merge pull request #134 from amosproj/docstrings_vis_ad

updated docstrings for ad visualization

Author: Perimora

src/sdk/python/rtdip_sdk/pipelines/visualization/matplotlib/anomaly_detection.py

@@ -75,17 +75,17 @@ def __init__(
         """
         Initialize the AnomalyDetectionPlot component.
 
-        Args:
-            ts_data: PySpark DataFrame with 'timestamp' and 'value' columns
-            ad_data: PySpark DataFrame with 'timestamp' and 'value' columns
-            sensor_id: Optional sensor identifier
-            title: Optional custom title
-            figsize: Figure size tuple
-            linewidth: Line width for the time series
-            anomaly_marker_size: Size of anomaly markers
-            anomaly_color: Color for anomaly points
-            ts_color: Color for time series line
-            ax: Optional existing matplotlib axis to plot on
+        Parameters:
+            ts_data (SparkDataFrame): PySpark DataFrame with 'timestamp' and 'value' columns.
+            ad_data (SparkDataFrame): PySpark DataFrame with 'timestamp' and 'value' columns.
+            sensor_id (str, optional): Sensor identifier used in the plot title.
+            title (str, optional): Custom plot title. If not provided, a default title is used.
+            figsize (tuple, optional): Figure size as (width, height). Defaults to (18, 6).
+            linewidth (float, optional): Line width for time series. Defaults to 1.6.
+            anomaly_marker_size (int, optional): Marker size for anomalies. Defaults to 70.
+            anomaly_color (str, optional): Color for anomaly markers. Defaults to "red".
+            ts_color (str, optional): Color for time series line. Defaults to "steelblue".
+            ax (matplotlib.axes.Axes, optional): Existing matplotlib axis to plot on.
         """
         super().__init__()
 
@@ -106,7 +106,13 @@ def __init__(
         self._validate_data()
 
     def _validate_data(self) -> None:
-        """Validate that required columns exist in DataFrames."""
+        """
+        Validate input data format and data types.
+
+        Ensures that both `ts_data` and `ad_data` contain the required columns
+        {'timestamp', 'value'}. Automatically converts timestamp columns to
+        datetime and value columns to numeric types when necessary.
+        """
         required_cols = {"timestamp", "value"}
 
         if not required_cols.issubset(self.ts_data.columns):
@@ -146,11 +152,12 @@ def plot(self, ax: Optional[Axes] = None) -> Figure | SubFigure:
         """
         Generate the anomaly detection visualization.
 
-        Args:
-            ax: Optional matplotlib axis to plot on. If None, creates new figure.
+        Parameters:
+            ax (matplotlib.axes.Axes, optional): Existing matplotlib axis to plot on.
+                If None, a new figure and axis are created.
 
         Returns:
-            matplotlib.figure.Figure: The generated figure
+            Figure | SubFigure: The generated matplotlib figure containing the plot.
         """
         # Use provided ax or instance ax
         use_ax = ax if ax is not None else self.ax
@@ -214,13 +221,13 @@ def save(
         """
         Save the visualization to file.
 
-        Args:
-            filepath (Union[str, Path]): Output file path
-            dpi (int): Dots per inch. Defaults to 150
-            **kwargs (Any): Additional arguments passed to savefig
+        Parameters:
+            filepath (Union[str, Path]): Output file path.
+            dpi (int, optional): Dots per inch for the saved figure. Defaults to 150.
+            **kwargs (Any): Additional keyword arguments passed to `matplotlib.pyplot.savefig`.
 
         Returns:
-            Path: The path to the saved file
+            Path: Path to the saved figure file.
         """
 
         assert self._fig is not None, "Plot the figure before saving."

src/sdk/python/rtdip_sdk/pipelines/visualization/plotly/anomaly_detection.py

@@ -27,9 +27,9 @@ class AnomalyDetectionPlotInteractive(PlotlyVisualizationInterface):
     Plot time series data with detected anomalies highlighted using Plotly.
 
     This component is functionally equivalent to the Matplotlib-based
-    AnomalyDetectionPlot. It visualizes the full time series as a line and
-    overlays detected anomalies as markers. Hover tooltips on anomaly markers
-    explicitly show timestamp and value.
+    AnomalyDetectionPlot. It visualizes the full time series as an interactive
+    line chart and overlays detected anomalies as markers. Hover tooltips on
+    anomaly markers display timestamp and value information.
     """
 
     def __init__(
@@ -42,6 +42,20 @@ def __init__(
         anomaly_color: str = "red",
         anomaly_marker_size: int = 8,
     ) -> None:
+        """
+        Initialize the AnomalyDetectionPlotInteractive component.
+
+        Parameters:
+            ts_data (SparkDataFrame): PySpark DataFrame with 'timestamp' and 'value' columns
+                containing the full time series data.
+            ad_data (SparkDataFrame, optional): PySpark DataFrame with 'timestamp' and 'value'
+                columns containing detected anomalies.
+            sensor_id (str, optional): Sensor identifier used in the plot title.
+            title (str, optional): Custom plot title. If not provided, a default title is used.
+            ts_color (str, optional): Color for the time series line. Defaults to "steelblue".
+            anomaly_color (str, optional): Color for anomaly markers. Defaults to "red".
+            anomaly_marker_size (int, optional): Marker size for anomaly points. Defaults to 8.
+        """
         super().__init__()
 
         # Convert Spark DataFrames to Pandas
@@ -58,7 +72,13 @@ def __init__(
         self._validate_data()
 
     def _validate_data(self) -> None:
-        """Validate required columns and enforce correct dtypes."""
+        """
+        Validate input data format and data types.
+
+        Ensures that both `ts_data` and `ad_data` contain the required columns
+        {'timestamp', 'value'}. Automatically converts timestamp columns to
+        datetime and value columns to numeric types when necessary.
+        """
 
         required_cols = {"timestamp", "value"}
 
@@ -88,9 +108,8 @@ def plot(self) -> go.Figure:
         Generate the Plotly anomaly detection visualization.
 
         Returns:
-            plotly.graph_objects.Figure
+            plotly.graph_objects.Figure: The generated interactive Plotly figure.
         """
-
         ts_sorted = self.ts_data.sort_values("timestamp")
 
         fig = go.Figure()
@@ -155,14 +174,15 @@ def save(
         Save the Plotly visualization to file.
 
         If the file suffix is `.html`, the figure is saved as an interactive HTML
-        file. Otherwise, a static image is written (requires kaleido).
+        file. Otherwise, a static image is written (requires the `kaleido` backend).
 
-        Args:
-            filepath (Union[str, Path]): Output file path
-            **kwargs (Any): Additional arguments passed to write_html or write_image
+        Parameters:
+            filepath (Union[str, Path]): Output file path.
+            **kwargs (Any): Additional keyword arguments passed to `write_html`
+                or `write_image`.
 
         Returns:
-            Path: The path to the saved file
+            Path: Path to the saved visualization file.
         """
         assert self._fig is not None, "Plot the figure before saving."