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

validmind/tests/data_validation/EngleGrangerCoint.py

@@ -5,10 +5,14 @@
 import pandas as pd
 from statsmodels.tsa.stattools import coint
 
-from validmind.vm_models import Metric, ResultSummary, ResultTable, ResultTableMetadata
+from validmind import tags, tasks
+from validmind.errors import SkipTestError
+from validmind.vm_models import VMDataset
 
 
-class EngleGrangerCoint(Metric):
+@tags("time_series_data", "statistical_test", "forecasting")
+@tasks("regression")
+def EngleGrangerCoint(dataset: VMDataset, threshold: float = 0.05):
     """
     Assesses the degree of co-movement between pairs of time series data using the Engle-Granger cointegration test.
 
@@ -48,80 +52,54 @@ class EngleGrangerCoint(Metric):
     - May not perform well for small sample sizes due to lack of statistical power and should be supplemented with
     other predictive indicators for a more robust model evaluation.
     """
+    df = dataset.df
 
-    type = "dataset"
-    name = "engle_granger_coint"
-    required_inputs = ["dataset"]
-    default_params = {"threshold": 0.05}
-    tasks = ["regression"]
-    tags = ["time_series_data", "statistical_test", "forecasting"]
-
-    def run(self):
-        threshold = self.params["threshold"]
-        df = self.inputs.dataset.df.dropna()
-
-        # Create an empty DataFrame to store the results
-        summary_cointegration = pd.DataFrame()
-
-        columns = df.columns
-        num_vars = len(columns)
-
-        for i in range(num_vars):
-            for j in range(i + 1, num_vars):
-                var1 = columns[i]
-                var2 = columns[j]
-
-                # Perform the Engle-Granger cointegration test
-                _, p_value, _ = coint(df[var1], df[var2])
-
-                # Determine the decision based on the p-value and the significance level
-                decision = (
-                    "Cointegrated" if p_value <= threshold else "Not cointegrated"
-                )
-                pass_fail = "Pass" if p_value <= threshold else "Fail"
-
-                # Append the result of each test directly into the DataFrame
-                summary_cointegration = pd.concat(
-                    [
-                        summary_cointegration,
-                        pd.DataFrame(
-                            [
-                                {
-                                    "Variable 1": var1,
-                                    "Variable 2": var2,
-                                    "Test": "Engle-Granger",
-                                    "p-value": p_value,
-                                    "Threshold": threshold,
-                                    "Pass/Fail": pass_fail,
-                                    "Decision": decision,
-                                }
-                            ]
-                        ),
-                    ],
-                    ignore_index=True,
-                )
-
-        return self.cache_results(
-            {
-                "cointegration_analysis": summary_cointegration.to_dict(
-                    orient="records"
-                ),
-            }
+    # Validate that the index is datetime
+    if not isinstance(df.index, (pd.DatetimeIndex, pd.PeriodIndex)):
+        raise SkipTestError(
+            "Dataset index must be a datetime or period index for cointegration analysis."
         )
 
-    def summary(self, metric_value):
-        """
-        Build one table for summarizing the cointegration results
-        """
-        summary_cointegration = metric_value["cointegration_analysis"]
-
-        return ResultSummary(
-            results=[
-                ResultTable(
-                    data=summary_cointegration,
-                    metadata=ResultTableMetadata(
-                        title="Cointegration Analysis Results"
+    df = dataset.df.dropna()
+
+    summary_cointegration = pd.DataFrame()
+
+    columns = df.columns
+    num_vars = len(columns)
+
+    for i in range(num_vars):
+        for j in range(i + 1, num_vars):
+            var1 = columns[i]
+            var2 = columns[j]
+
+            # Perform the Engle-Granger cointegration test
+            _, p_value, _ = coint(df[var1], df[var2])
+
+            # Determine the decision based on the p-value and the significance level
+            decision = "Cointegrated" if p_value <= threshold else "Not cointegrated"
+            pass_fail = "Pass" if p_value <= threshold else "Fail"
+
+            # Append the result of each test directly into the DataFrame
+            summary_cointegration = pd.concat(
+                [
+                    summary_cointegration,
+                    pd.DataFrame(
+                        [
+                            {
+                                "Variable 1": var1,
+                                "Variable 2": var2,
+                                "Test": "Engle-Granger",
+                                "p-value": p_value,
+                                "Threshold": threshold,
+                                "Pass/Fail": pass_fail,
+                                "Decision": decision,
+                            }
+                        ]
                     ),
-                ),
-            ]
-        )
+                ],
+                ignore_index=True,
+            )
+
+    return {
+        "Cointegration Analysis Results": summary_cointegration,
+    }

validmind/tests/data_validation/HighCardinality.py

@@ -2,23 +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
-from typing import List
-
-from ydata_profiling.config import Settings
-from ydata_profiling.model.typeset import ProfilingTypeSet
-
-from validmind.vm_models import (
-    ResultSummary,
-    ResultTable,
-    ResultTableMetadata,
-    ThresholdTest,
-    ThresholdTestResult,
-)
-
-
-@dataclass
-class HighCardinality(ThresholdTest):
+from validmind import tags, tasks
+from validmind.vm_models import VMDataset
+
+
+@tags("tabular_data", "data_quality", "categorical_data")
+@tasks("classification", "regression")
+def HighCardinality(
+    dataset: VMDataset,
+    num_threshold: int = 100,
+    percent_threshold: float = 0.1,
+    threshold_type: str = "percent",
+):
     """
     Assesses the number of unique values in categorical columns to detect high cardinality and potential overfitting.
 
@@ -56,72 +51,29 @@ class HighCardinality(ThresholdTest):
     - The threshold (both number and percent) used for the test is static and may not be optimal for diverse datasets
     and varied applications. Further mechanisms to adjust and refine this threshold could enhance its effectiveness.
     """
+    df = dataset.df
 
-    name = "cardinality"
-    required_inputs = ["dataset"]
-    default_params = {
-        "num_threshold": 100,
-        "percent_threshold": 0.1,
-        "threshold_type": "percent",  # or "num"
-    }
-    tasks = ["classification", "regression"]
-    tags = ["tabular_data", "data_quality", "categorical_data"]
-
-    def summary(self, results: List[ThresholdTestResult], all_passed: bool):
-        """
-        The high cardinality test returns results like these:
-        [{"values": {"n_distinct": 0, "p_distinct": 0.0}, "column": "Exited", "passed": true}]
-        """
-        results_table = [
-            {
-                "Column": result.column,
-                "Number of Distinct Values": result.values["n_distinct"],
-                "Percentage of Distinct Values (%)": result.values["p_distinct"] * 100,
-                "Pass/Fail": "Pass" if result.passed else "Fail",
-            }
-            for result in results
-        ]
-        return ResultSummary(
-            results=[
-                ResultTable(
-                    data=results_table,
-                    metadata=ResultTableMetadata(
-                        title="High Cardinality Results for Dataset"
-                    ),
-                )
-            ]
-        )
+    if threshold_type == "percent":
+        num_threshold = int(percent_threshold * df.shape[0])
 
-    def run(self):
-        typeset = ProfilingTypeSet(Settings())
-        dataset_types = typeset.infer_type(self.inputs.dataset.df)
+    table = []
+    all_passed = True
 
-        results = []
-        rows = self.inputs.dataset.df.shape[0]
+    for col in dataset.feature_columns_categorical:
+        n_distinct = df[col].nunique()
+        p_distinct = n_distinct / df.shape[0]
+        passed = n_distinct < num_threshold
 
-        num_threshold = self.params["num_threshold"]
-        if self.params["threshold_type"] == "percent":
-            num_threshold = int(self.params["percent_threshold"] * rows)
-
-        for col in self.inputs.dataset.df.columns:
-            # Only calculate high cardinality for categorical columns
-            if str(dataset_types[col]) != "Categorical":
-                continue
-
-            n_distinct = self.inputs.dataset.df[col].nunique()
-            p_distinct = n_distinct / rows
-
-            passed = n_distinct < num_threshold
+        table.append(
+            {
+                "Column": col,
+                "Number of Distinct Values": n_distinct,
+                "Percentage of Distinct Values (%)": p_distinct * 100,
+                "Pass/Fail": "Pass" if passed else "Fail",
+            }
+        )
 
-            results.append(
-                ThresholdTestResult(
-                    column=col,
-                    passed=passed,
-                    values={
-                        "n_distinct": n_distinct,
-                        "p_distinct": p_distinct,
-                    },
-                )
-            )
+        if not passed:
+            all_passed = False
 
-        return self.cache_results(results, passed=all([r.passed for r in results]))
+    return table, all_passed

validmind/tests/data_validation/HighPearsonCorrelation.py

@@ -2,23 +2,15 @@
 # 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
-from typing import List
+from validmind import tags, tasks
+from validmind.vm_models import VMDataset
 
-import numpy as np
-import pandas as pd
 
-from validmind.vm_models import (
-    ResultSummary,
-    ResultTable,
-    ResultTableMetadata,
-    ThresholdTest,
-    ThresholdTestResult,
-)
-
-
-@dataclass
-class HighPearsonCorrelation(ThresholdTest):
+@tags("tabular_data", "data_quality", "correlation")
+@tasks("classification", "regression")
+def HighPearsonCorrelation(
+    dataset: VMDataset, max_threshold: float = 0.3, top_n_correlations: int = 10
+):
     """
     Identifies highly correlated feature pairs in a dataset suggesting feature redundancy or multicollinearity.
 
@@ -33,8 +25,9 @@ class HighPearsonCorrelation(ThresholdTest):
 
     The test works by generating pairwise Pearson correlations for all features in the dataset, then sorting and
     eliminating duplicate and self-correlations. It assigns a Pass or Fail based on whether the absolute value of the
-    correlation coefficient surpasses a pre-set threshold (defaulted at 0.3). It lastly returns the top ten strongest
-    correlations regardless of passing or failing status.
+    correlation coefficient surpasses a pre-set threshold (defaulted at 0.3). It lastly returns the top n strongest
+    correlations regardless of passing or failing status (where n is 10 by default but can be configured by passing the
+    `top_n_correlations` parameter).
 
     ### Signs of High Risk
 
@@ -57,86 +50,25 @@ class HighPearsonCorrelation(ThresholdTest):
     - Sensitive to outliers where a few outliers could notably affect the correlation coefficient.
     - Limited to identifying redundancy only within feature pairs; may fail to spot more complex relationships among
     three or more variables.
-    - The top 10 result filter might not fully capture the richness of the data; an option to configure the number of
-    retained results could be helpful.
     """
-
-    name = "pearson_correlation"
-    required_inputs = ["dataset"]
-    default_params = {"max_threshold": 0.3}
-    tasks = ["classification", "regression"]
-    tags = ["tabular_data", "data_quality", "correlation"]
-
-    def summary(self, results: List[ThresholdTestResult], all_passed: bool):
-        """The high pearson correlation test returns results like these:
-        [
-            {
-                "values": {
-                    "correlations": [
-                        {"column": "NumOfProducts", "correlation": -0.3044645622389459}
-                    ]
-                },
-                "column": "Balance",
-                "passed": false,
-            }
-        ]
-        """
-        results_table = [
-            {
-                "Columns": f'({result.column}, {result.values["correlations"][0]["column"]})',
-                "Coefficient": result.values["correlations"][0]["correlation"],
-                "Pass/Fail": "Pass" if result.passed else "Fail",
-            }
-            for result in results
-        ]
-        return ResultSummary(
-            results=[
-                ResultTable(
-                    data=results_table,
-                    metadata=ResultTableMetadata(
-                        title="High Pearson Correlation Results for Dataset"
-                    ),
-                )
-            ]
-        )
-
-    def run(self):
-        corr = self.inputs.dataset.df.corr(numeric_only=True)
-
-        # Create a table of correlation coefficients and column pairs
-        corr_table = corr.unstack().sort_values(
-            kind="quicksort", key=abs, ascending=False
-        )
-        corr_df = pd.DataFrame(corr_table).reset_index()
-        corr_df.columns = ["Column1", "Column2", "Coefficient"]
-
-        # Remove duplicate correlations and self-correlations
-        corr_df = corr_df.loc[corr_df["Column1"] < corr_df["Column2"]]
-
-        # Assign Pass/Fail based on correlation coefficient
-        corr_df["Pass/Fail"] = np.where(
-            corr_df["Coefficient"].abs() <= self.params["max_threshold"], "Pass", "Fail"
-        )
-
-        # Only keep the top 10 correlations. TODO: configurable
-        corr_df = corr_df.head(10)
-
-        passed = corr_df["Pass/Fail"].eq("Pass").all()
-
-        results = [
-            ThresholdTestResult(
-                column=col1,
-                values={
-                    "correlations": [
-                        {
-                            "column": col2,
-                            "correlation": coeff,
-                        }
-                    ]
-                },
-                passed=pass_fail == "Pass",
+    # Get correlation matrix for numeric columns
+    corr = dataset.df.corr(numeric_only=True)
+
+    # Create table of correlation coefficients and column pairs
+    pairs = []
+    for i in range(len(corr.columns)):
+        for j in range(i + 1, len(corr.columns)):
+            coeff = corr.iloc[i, j]
+            pairs.append(
+                {
+                    "Columns": f"({corr.columns[i]}, {corr.columns[j]})",
+                    "Coefficient": coeff,
+                    "Pass/Fail": "Pass" if abs(coeff) <= max_threshold else "Fail",
+                }
             )
-            for _, (col1, col2, coeff, pass_fail) in corr_df.iterrows()
-        ]
 
-        return self.cache_results(results, passed=passed)
+    # Sort by absolute coefficient and get top N
+    pairs.sort(key=lambda x: abs(x["Coefficient"]), reverse=True)
+    pairs = pairs[:top_n_correlations]
+
+    return pairs, all(p["Pass/Fail"] == "Pass" for p in pairs)

validmind/tests/data_validation/IQROutliersBarPlot.py

@@ -2,15 +2,27 @@
 # 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 plotly.graph_objects as go
 
-from validmind.vm_models import Figure, Metric
+from validmind import tags, tasks
+from validmind.vm_models import VMDataset
+
+
+def compute_outliers(series, threshold):
+    Q1 = series.quantile(0.25)
+    Q3 = series.quantile(0.75)
+    IQR = Q3 - Q1
+    lower_bound = Q1 - threshold * IQR
+    upper_bound = Q3 + threshold * IQR
+
+    return series[(series < lower_bound) | (series > upper_bound)]
 
 
-@dataclass
-class IQROutliersBarPlot(Metric):
+@tags("tabular_data", "visualization", "numerical_data")
+@tasks("classification", "regression")
+def IQROutliersBarPlot(
+    dataset: VMDataset, threshold: float = 1.5, fig_width: int = 800
+):
     """
     Visualizes outlier distribution across percentiles in numerical data using the Interquartile Range (IQR) method.
 
@@ -54,99 +66,56 @@ class IQROutliersBarPlot(Metric):
     ### Limitations
 
     - Its application is limited to numerical variables and does not extend to categorical ones.
-    - Relies on a predefined threshold (default being 1.5) for outlier identification, which may not be suitable for
-    all cases.
     - Only reveals the presence and distribution of outliers and does not provide insights into how these outliers
     might affect the model's predictive performance.
     - The assumption that data is unimodal and symmetric may not always hold true. In cases with non-normal
     distributions, the results can be misleading.
     """
-
-    name = "iqr_outliers_bar_plot"
-    required_inputs = ["dataset"]
-    default_params = {"threshold": 1.5, "fig_width": 800}
-    tasks = ["classification", "regression"]
-    tags = ["tabular_data", "visualization", "numerical_data"]
-
-    def run(self):
-        df = self.inputs.dataset.df
-
-        # Select numerical features
-        features = self.inputs.dataset.feature_columns_numeric
-
-        # Select non-binary features
-        features = [
-            feature
-            for feature in features
-            if len(self.inputs.dataset.df[feature].unique()) > 2
+    df = dataset.df
+
+    figures = []
+
+    for col in dataset.feature_columns_numeric:
+        # Skip binary features
+        if len(df[col].unique()) <= 2:
+            continue
+
+        outliers = compute_outliers(df[col], threshold)
+        if outliers.empty:
+            continue
+
+        Q1_count = outliers[
+            (outliers >= 0) & (outliers < outliers.quantile(0.25))
+        ].count()
+        Q2_count = outliers[
+            (outliers >= outliers.quantile(0.25)) & (outliers < outliers.median())
+        ].count()
+        Q3_count = outliers[
+            (outliers >= outliers.median()) & (outliers < outliers.quantile(0.75))
+        ].count()
+        Q4_count = outliers[
+            (outliers >= outliers.quantile(0.75)) & (outliers <= outliers.max())
+        ].count()
+
+        bar_data = [Q1_count, Q2_count, Q3_count, Q4_count]
+        percentile_labels = [
+            "0-25",
+            "25-50",
+            "50-75",
+            "75-100",
         ]
 
-        threshold = self.params["threshold"]
-        fig_width = self.params["fig_width"]
-
-        df = df[features]
-
-        return self.detect_and_visualize_outliers(df, threshold, fig_width)
-
-    @staticmethod
-    def compute_outliers(series, threshold=1.5):
-        Q1 = series.quantile(0.25)
-        Q3 = series.quantile(0.75)
-        IQR = Q3 - Q1
-        lower_bound = Q1 - threshold * IQR
-        upper_bound = Q3 + threshold * IQR
-        return series[(series < lower_bound) | (series > upper_bound)]
-
-    def detect_and_visualize_outliers(self, df, threshold, fig_width):
-        num_cols = df.columns.tolist()
-        figures = []
-
-        for col in num_cols:
-            # Compute outliers
-            outliers = self.compute_outliers(df[col], threshold)
-
-            if outliers.empty:
-                continue  # Skip plotting if there are no outliers
-
-            Q1_count = outliers[
-                (outliers >= 0) & (outliers < outliers.quantile(0.25))
-            ].count()
-            Q2_count = outliers[
-                (outliers >= outliers.quantile(0.25)) & (outliers < outliers.median())
-            ].count()
-            Q3_count = outliers[
-                (outliers >= outliers.median()) & (outliers < outliers.quantile(0.75))
-            ].count()
-            Q4_count = outliers[
-                (outliers >= outliers.quantile(0.75)) & (outliers <= outliers.max())
-            ].count()
-
-            # Prepare data for bar plot
-            bar_data = [Q1_count, Q2_count, Q3_count, Q4_count]
-            percentile_labels = [
-                "0-25",
-                "25-50",
-                "50-75",
-                "75-100",
-            ]
-
-            # Create a bar plot
-            fig = go.Figure(
-                data=[go.Bar(x=percentile_labels, y=bar_data, marker_color="skyblue")]
-            )
-
-            # Set layout properties
-            fig.update_layout(
-                title_text=col,
-                width=fig_width,
-                height=400,
-                plot_bgcolor="white",
-                xaxis_title="Percentile",
-                yaxis_title="Outlier Count",
-            )
-
-            # Create a Figure object and append to figures list
-            figure = Figure(for_object=self, key=f"{self.key}:{col}", figure=fig)
-            figures.append(figure)
-
-        return self.cache_results(figures=figures)
+        fig = go.Figure(
+            data=[go.Bar(x=percentile_labels, y=bar_data, marker_color="skyblue")]
+        )
+        fig.update_layout(
+            title_text=col,
+            width=fig_width,
+            height=400,
+            plot_bgcolor="white",
+            xaxis_title="Percentile",
+            yaxis_title="Outlier Count",
+        )
+        figures.append(fig)
+
+    return tuple(figures)