validmind 2.5.25__py3-none-any.whl → 2.6.8__py3-none-any.whl

validmind/tests/data_validation/TimeSeriesLinePlot.py

@@ -5,10 +5,14 @@
 import pandas as pd
 import plotly.graph_objects as go
 
-from validmind.vm_models import Figure, Metric
+from validmind import tags, tasks
+from validmind.errors import SkipTestError
+from validmind.vm_models import VMDataset
 
 
-class TimeSeriesLinePlot(Metric):
+@tags("time_series_data", "visualization")
+@tasks("regression")
+def TimeSeriesLinePlot(dataset: VMDataset):
     """
     Generates and analyses time-series data through line plots revealing trends, patterns, anomalies over time.
 
@@ -51,49 +55,27 @@ class TimeSeriesLinePlot(Metric):
     - The metric has an inherent limitation in that it cannot extract deeper statistical insights from the time series
     data, which can limit its efficacy with complex data structures and phenomena.
     """
-
-    name = "time_series_line_plot"
-    required_inputs = ["dataset"]
-    tasks = ["regression"]
-    tags = ["time_series_data", "visualization"]
-
-    def run(self):
-        # Check if index is datetime
-        if not pd.api.types.is_datetime64_any_dtype(self.inputs.dataset.df.index):
-            raise ValueError("Index must be a datetime type")
-
-        columns = list(self.inputs.dataset.df.columns)
-        df = self.inputs.dataset.df
-
-        if not set(columns).issubset(set(df.columns)):
-            raise ValueError("Provided 'columns' must exist in the dataset")
-
-        figures = []
-        for col in columns:
-            # Creating the figure using Plotly
-            fig = go.Figure()
-
-            fig.add_trace(go.Scatter(x=df.index, y=df[col], mode="lines", name=col))
-
-            fig.update_layout(
-                title={
-                    "text": f"{col}",
-                    "y": 0.95,
-                    "x": 0.5,
-                    "xanchor": "center",
-                    "yanchor": "top",
-                },
-                font=dict(size=16),
-            )
-
-            figures.append(
-                Figure(
-                    for_object=self,
-                    key=f"{self.key}:{col}",
-                    figure=fig,
-                )
-            )
-
-        return self.cache_results(
-            figures=figures,
+    df = dataset.df
+
+    if not pd.api.types.is_datetime64_any_dtype(df.index):
+        raise SkipTestError("Index must be a datetime type")
+
+    figures = []
+
+    for col in dataset.feature_columns_numeric:
+        fig = go.Figure()
+        fig.add_trace(go.Scatter(x=df.index, y=df[col], mode="lines", name=col))
+        fig.update_layout(
+            title={
+                "text": col,
+                "y": 0.95,
+                "x": 0.5,
+                "xanchor": "center",
+                "yanchor": "top",
+            },
+            font=dict(size=16),
         )
+
+        figures.append(fig)
+
+    return tuple(figures)

validmind/tests/data_validation/TimeSeriesMissingValues.py

@@ -2,24 +2,18 @@
 # See the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
-from dataclasses import dataclass
-
 import pandas as pd
 import plotly.express as px
 import plotly.figure_factory as ff
 
-from validmind.vm_models import (
-    Figure,
-    ResultSummary,
-    ResultTable,
-    ResultTableMetadata,
-    ThresholdTest,
-    ThresholdTestResult,
-)
+from validmind import tags, tasks
+from validmind.errors import SkipTestError
+from validmind.vm_models import VMDataset
 
 
-@dataclass
-class TimeSeriesMissingValues(ThresholdTest):
+@tags("time_series_data")
+@tasks("regression")
+def TimeSeriesMissingValues(dataset: VMDataset, min_threshold: int = 1):
     """
     Validates time-series data quality by confirming the count of missing values is below a certain threshold.
 
@@ -37,17 +31,11 @@ class TimeSeriesMissingValues(ThresholdTest):
     dataset. An object for the test result is created stating whether the number of missing values is within the
     specified threshold. Additionally, the test calculates the percentage of missing values alongside the raw count.
 
-    To aid in data visualization, the test generates two plots - a bar plot and a heatmap - to better illustrate the
-    distribution and quantity of missing values per variable. The test results, including a count of missing values,
-    the percentage of missing values, and a pass/fail status, are returned in a results table.
-
     ### Signs of High Risk
 
     - The number of missing values in any column of the dataset surpasses the threshold, marking a failure and a
     high-risk scenario. The reasons could range from incomplete data collection, faulty sensors to data preprocessing
     errors.
-    - A continuous visual 'streak' in the heatmap may indicate a systematic error during data collection, pointing
-    towards another potential risk source.
 
     ### Strengths
 
@@ -55,7 +43,6 @@ class TimeSeriesMissingValues(ThresholdTest):
     - Applicable and customizable through the threshold parameter across different data sets.
     - Goes beyond raw numbers by calculating the percentage of missing values, offering a more relative understanding
     of data scarcity.
-    - Includes a robust visualization mechanism for easy and fast understanding of data quality.
 
     ### Limitations
 
@@ -66,124 +53,61 @@ class TimeSeriesMissingValues(ThresholdTest):
     overlook problematic data if set too loosely.
     - Solely focuses on the 'missingness' of the data and might fall short in addressing other aspects of data quality.
     """
+    df = dataset.df
+
+    if not pd.api.types.is_datetime64_any_dtype(df.index):
+        raise SkipTestError("Dataset must be provided with datetime index")
 
-    name = "time_series_missing_values"
-    required_inputs = ["dataset"]
-    default_params = {"min_threshold": 1}
-    tasks = ["regression"]
-    tags = ["time_series_data"]
+    missing = df.isna().sum()
 
-    def summary(self, results, all_passed):
-        results_table = [
+    if sum(missing.values) == 0:
+        # if theres no missing values, no need to plot anything
+        return [
+            {
+                "Column": col,
+                "Number of Missing Values": missing[col],
+                "Percentage of Missing Values (%)": 0,
+                "Pass/Fail": "Pass",
+            }
+            for col in missing.index
+        ], True
+
+    barplot = px.bar(
+        missing,
+        x=missing.index,
+        y=missing.values,
+        labels={"x": "", "y": "Missing Values"},
+        title="Total Number of Missing Values per Variable",
+        color=missing.values,
+        color_continuous_scale="Reds",
+    )
+
+    missing_mask = df.isnull()
+    z = missing_mask.T.astype(int).values
+    x = missing_mask.index.tolist()
+    y = missing_mask.columns.tolist()
+    heatmap = ff.create_annotated_heatmap(
+        z=z,
+        x=x,
+        y=y,
+        colorscale="Reds",
+        showscale=False,
+    )
+
+    # Update the layout after creation
+    heatmap.update_layout(title="Missing Values Heatmap")
+
+    return (
+        [
             {
-                "Column": result.column,
-                "Number of Missing Values": result.values["n_missing"],
-                "Percentage of Missing Values (%)": result.values["p_missing"] * 100,
-                "Pass/Fail": "Pass" if result.passed else "Fail",
+                "Column": col,
+                "Number of Missing Values": missing[col],
+                "Percentage of Missing Values (%)": missing[col] / df.shape[0] * 100,
+                "Pass/Fail": "Pass" if missing[col] < min_threshold else "Fail",
             }
-            for result in results
-        ]
-        return ResultSummary(
-            results=[
-                ResultTable(
-                    data=results_table,
-                    metadata=ResultTableMetadata(
-                        title="Missing Values Results for Dataset"
-                    ),
-                )
-            ]
-        )
-
-    def run(self):
-        df = self.inputs.dataset.df
-
-        # Check if the index of dataframe is datetime
-        is_datetime = pd.api.types.is_datetime64_any_dtype(df.index)
-        if not is_datetime:
-            raise ValueError("Dataset must be provided with datetime index")
-
-        # Validate threshold parameter
-        if "min_threshold" not in self.params:
-            raise ValueError("min_threshold must be provided in params")
-        min_threshold = self.params["min_threshold"]
-
-        rows = df.shape[0]
-        missing = df.isna().sum()
-        test_results = [
-            ThresholdTestResult(
-                column=col,
-                passed=missing[col] < min_threshold,
-                values={"n_missing": missing[col], "p_missing": missing[col] / rows},
-            )
             for col in missing.index
-        ]
-
-        fig_barplot = self._barplot(df)
-        fig_heatmap = self._heatmap(df)
-        test_figures = []
-        if fig_barplot is not None:
-            test_figures.append(
-                Figure(
-                    for_object=self,
-                    key=f"{self.name}:barplot",
-                    figure=fig_barplot,
-                    metadata={"type": "barplot"},
-                )
-            )
-            test_figures.append(
-                Figure(
-                    for_object=self,
-                    key=f"{self.name}:heatmap",
-                    figure=fig_heatmap,
-                    metadata={"type": "heatmap"},
-                )
-            )
-
-        return self.cache_results(
-            test_results,
-            passed=all([r.passed for r in test_results]),
-            # Don't pass figures until we figure out how to group metric-figures for multiple
-            # executions inside a single test run
-            # figures=test_figures,
-        )
-
-    def _barplot(self, df):
-        """
-        Generate a bar plot of missing values using Plotly.
-        """
-        missing_values = df.isnull().sum()
-        if sum(missing_values.values) != 0:
-            fig = px.bar(
-                missing_values,
-                x=missing_values.index,
-                y=missing_values.values,
-                labels={"x": "", "y": "Missing Values"},
-                title="Total Number of Missing Values per Variable",
-                color=missing_values.values,
-                color_continuous_scale="Reds",
-            )
-        else:
-            fig = None
-
-        return fig
-
-    def _heatmap(self, df):
-        """
-        Plots a heatmap to visualize missing values using Plotly.
-        """
-        # Create a boolean mask for missing values
-        missing_mask = df.isnull()
-        z = missing_mask.T.astype(int).values  # Convert boolean to int for heatmap
-
-        x = missing_mask.index.tolist()
-        y = missing_mask.columns.tolist()
-
-        if not x:
-            fig = ff.create_annotated_heatmap(
-                z=z, x=x, y=y, colorscale="Reds", showscale=False
-            )
-            fig.update_layout(title="Missing Values Heatmap")
-        else:
-            fig = None
-
-        return fig
+        ],
+        barplot,
+        heatmap,
+        all(missing[col] < min_threshold for col in missing.index),
+    )

validmind/tests/data_validation/TimeSeriesOutliers.py

@@ -2,23 +2,17 @@
 # See the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
-from dataclasses import dataclass
-
 import pandas as pd
 import plotly.graph_objects as go
 
-from validmind.vm_models import (
-    Figure,
-    ResultSummary,
-    ResultTable,
-    ResultTableMetadata,
-    ThresholdTest,
-    ThresholdTestResult,
-)
+from validmind import tags, tasks
+from validmind.errors import SkipTestError
+from validmind.vm_models import VMDataset
 
 
-@dataclass
-class TimeSeriesOutliers(ThresholdTest):
+@tags("time_series_data")
+@tasks("regression")
+def TimeSeriesOutliers(dataset: VMDataset, zscore_threshold: int = 3):
     """
     Identifies and visualizes outliers in time-series data using the z-score method.
 
@@ -62,174 +56,63 @@ class TimeSeriesOutliers(ThresholdTest):
     - It does not address possible ways to handle identified outliers in the data.
     - The requirement for a datetime index could limit its application.
     """
-
-    name = "time_series_outliers"
-    required_inputs = ["dataset"]
-    default_params = {"zscore_threshold": 3}
-    tasks = ["regression"]
-    tags = ["time_series_data"]
-
-    def summary(self, results, all_passed: bool):
-        """
-        Example output:
-        [
-            {
-                "values": {
-                    "Variable": [...],
-                    "z-score": [...],
-                    "Threshold": [3, 3, 3, 3, 3, 3],
-                    "Date": [...]
-                },
-                "test_name": "outliers",
-                "passed": false
-            }
-        ]
-        """
-
-        first_result = results[0]
-
-        variables = first_result.values["Variable"]
-        zScores = first_result.values["z-score"]
-        dates = first_result.values["Date"]
-        passFail = [
-            "Pass" if abs(z) < self.params["zscore_threshold"] else "Fail"
-            for z in zScores
-        ]
-
-        return ResultSummary(
-            results=[
-                ResultTable(
-                    # Sort by variable and then by date
-                    data=pd.DataFrame(
-                        {
-                            "Variable": variables,
-                            "Date": dates,
-                            "z-Score": zScores,
-                            "Pass/Fail": passFail,
-                        }
-                    ).sort_values(["Variable", "Date"]),
-                    metadata=ResultTableMetadata(
-                        title="Outliers Results with z-Score Test"
-                    ),
+    df = dataset.df
+
+    if not pd.api.types.is_datetime64_any_dtype(df.index):
+        raise SkipTestError("Dataset must be provided with datetime index")
+
+    df_numeric = df[dataset.feature_columns_numeric]
+    z_scores = pd.DataFrame(
+        data=df_numeric.apply(lambda x: (x - x.mean()) / x.std()),
+        index=df.index,
+        columns=dataset.feature_columns_numeric,
+    )
+
+    outlier_table = []
+    outliers = z_scores[(z_scores.abs() > zscore_threshold).any(axis=1)]
+
+    for idx, row in outliers.iterrows():
+        for col in dataset.feature_columns_numeric:
+            if abs(row[col]) > zscore_threshold:
+                outlier_table.append(
+                    {
+                        "Column": col,
+                        "Z-Score": row[col],
+                        "Threshold": zscore_threshold,
+                        "Date": idx.strftime("%Y-%m-%d"),
+                        "Pass/Fail": "Fail",
+                    }
                 )
-            ]
-        )
-
-    def run(self):
-        # Initialize the test_results list
-        test_results = []
-
-        # Check if the index of dataframe is datetime
-        is_datetime = pd.api.types.is_datetime64_any_dtype(self.inputs.dataset.df.index)
-        if not is_datetime:
-            raise ValueError("Dataset must be provided with datetime index")
 
-        # Validate threshold parameter
-        if "zscore_threshold" not in self.params:
-            raise ValueError("zscore_threshold must be provided in params")
-        zscore_threshold = self.params["zscore_threshold"]
+    outlier_df = pd.DataFrame(outlier_table)
+    figures = []
 
-        temp_df = self.inputs.dataset.df.copy()
-        # temp_df = temp_df.dropna()
+    for column in outlier_df["Column"].unique():
+        fig = go.Figure()
 
-        # Infer numeric columns
-        num_features_columns = temp_df.select_dtypes(
-            include=["number"]
-        ).columns.tolist()
-
-        outliers_table = self.identify_outliers(
-            temp_df[num_features_columns], zscore_threshold
+        fig.add_trace(
+            go.Scatter(x=df.index, y=df[column], mode="lines", name="Time Series")
         )
 
-        test_figures = self._plot_outliers(temp_df, outliers_table)
-        passed = outliers_table.empty
-
-        if not outliers_table.empty:
-            outliers_table["Date"] = outliers_table["Date"].astype(str)
-
-        test_results.append(
-            ThresholdTestResult(
-                test_name="outliers",
-                passed=passed,
-                values=outliers_table.to_dict(orient="list"),
+        column_outliers = outlier_df[outlier_df["Column"] == column]
+        fig.add_trace(
+            go.Scatter(
+                x=pd.to_datetime(column_outliers["Date"]),
+                y=df.loc[pd.to_datetime(column_outliers["Date"]), column],
+                mode="markers",
+                marker=dict(color="red", size=10),
+                name="Outliers",
             )
         )
 
-        return self.cache_results(test_results, passed=passed, figures=test_figures)
-
-    def z_score_with_na(self, df):
-        return df.apply(
-            lambda x: (x - x.mean()) / x.std() if x.dtype.kind in "biufc" else x
+        fig.update_layout(
+            title=f"Outliers for {column}", xaxis_title="Date", yaxis_title=column
         )
 
-    def identify_outliers(self, df, threshold):
-        """
-        Identifies and returns outliers in a pandas DataFrame using the z-score method.
-        Args:
-        df (pandas.DataFrame): A pandas DataFrame containing the data to be analyzed.
-        threshold (float): The absolute value of the z-score above which a value is considered an outlier.
-        Returns:
-        pandas.DataFrame: A DataFrame containing the variables, z-scores, threshold, and dates of the identified outliers.
-        """
-        z_scores = pd.DataFrame(
-            self.z_score_with_na(df), index=df.index, columns=df.columns
-        )
-
-        outliers = z_scores[(z_scores.abs() > threshold).any(axis=1)]
-        outlier_table = []
-        for idx, row in outliers.iterrows():
-            for col in df.columns:
-                if abs(row[col]) > threshold:
-                    outlier_table.append(
-                        {
-                            "Variable": col,
-                            "z-score": row[col],
-                            "Threshold": threshold,
-                            "Date": idx,
-                        }
-                    )
-        return pd.DataFrame(outlier_table)
-
-    def _plot_outliers(self, df, outliers_table):
-        """
-        Plots time series with identified outliers.
-        Args:
-            df (pandas.DataFrame): Input data with time series.
-            outliers_table (pandas.DataFrame): DataFrame with identified outliers.
-        Returns:
-            list: A list of Figure objects with subplots for each variable.
-        """
-        figures = []
-
-        for col in df.columns:
-            fig = go.Figure()
-
-            fig.add_trace(go.Scatter(x=df.index, y=df[col], mode="lines", name=col))
-
-            if not outliers_table.empty:
-                variable_outliers = outliers_table[outliers_table["Variable"] == col]
-                fig.add_trace(
-                    go.Scatter(
-                        x=variable_outliers["Date"],
-                        y=df.loc[variable_outliers["Date"], col],
-                        mode="markers",
-                        marker=dict(color="red", size=10),
-                        name="Outlier",
-                    )
-                )
-
-            fig.update_layout(
-                title=f"Outliers for {col}",
-                xaxis_title="Date",
-                yaxis_title=col,
-            )
-
-            figures.append(
-                Figure(
-                    for_object=self,
-                    key=f"{self.name}:{col}_{self.inputs.dataset.input_id}",
-                    figure=fig,
-                )
-            )
+        figures.append(fig)
 
-        return figures
+    return (
+        outlier_df.sort_values(["Column", "Date"]),
+        figures,
+        len(outlier_df) == 0,
+    )