truthound 1.0.8__py3-none-any.whl

truthound/validators/ml_feature/scale.py

@@ -0,0 +1,264 @@
+"""Feature scale validators.
+
+This module provides validators for analyzing feature scale
+consistency in ML pipelines.
+"""
+
+from enum import Enum
+from typing import Any
+
+import polars as pl
+import numpy as np
+
+from truthound.types import Severity
+from truthound.validators.base import ValidationIssue
+from truthound.validators.registry import register_validator
+from truthound.validators.ml_feature.base import MLFeatureValidator, FeatureStats
+
+
+class ScaleType(str, Enum):
+    """Feature scale types."""
+
+    STANDARD = "standard"  # Mean ~0, std ~1
+    MINMAX = "minmax"  # Range [0, 1]
+    ROBUST = "robust"  # Median-centered, IQR-scaled
+    RAW = "raw"  # Unscaled
+    UNKNOWN = "unknown"
+
+
+@register_validator
+class FeatureScaleValidator(MLFeatureValidator):
+    """Validates feature scale consistency.
+
+    Checks for:
+    - Scale inconsistency across features
+    - Features with vastly different magnitudes
+    - Features needing normalization
+    - Expected scale violations
+
+    Example:
+        validator = FeatureScaleValidator(
+            expected_scale=ScaleType.STANDARD,
+            max_scale_ratio=100.0,
+        )
+    """
+
+    name = "feature_scale"
+
+    def __init__(
+        self,
+        columns: list[str] | None = None,
+        expected_scale: ScaleType | str | None = None,
+        max_scale_ratio: float = 100.0,
+        max_magnitude: float = 1e6,
+        check_standard_scale: bool = False,
+        std_tolerance: float = 0.5,
+        mean_tolerance: float = 0.5,
+        **kwargs: Any,
+    ):
+        """Initialize scale validator.
+
+        Args:
+            columns: Specific columns to validate
+            expected_scale: Expected scale type for all features
+            max_scale_ratio: Maximum ratio between feature scales
+            max_magnitude: Maximum allowed magnitude for any feature
+            check_standard_scale: Whether to check for standard scaling
+            std_tolerance: Tolerance for std deviation from 1
+            mean_tolerance: Tolerance for mean deviation from 0
+            **kwargs: Additional config
+        """
+        super().__init__(columns=columns, **kwargs)
+
+        if isinstance(expected_scale, str):
+            self.expected_scale = ScaleType(expected_scale)
+        else:
+            self.expected_scale = expected_scale
+
+        self.max_scale_ratio = max_scale_ratio
+        self.max_magnitude = max_magnitude
+        self.check_standard_scale = check_standard_scale
+        self.std_tolerance = std_tolerance
+        self.mean_tolerance = mean_tolerance
+
+    def _detect_scale_type(self, stats: FeatureStats) -> ScaleType:
+        """Detect the scale type of a feature.
+
+        Args:
+            stats: Feature statistics
+
+        Returns:
+            Detected scale type
+        """
+        if stats.mean is None or stats.std is None:
+            return ScaleType.UNKNOWN
+
+        # Check for standard scaling (mean ~0, std ~1)
+        if abs(stats.mean) < 0.5 and 0.5 <= stats.std <= 1.5:
+            return ScaleType.STANDARD
+
+        # Check for minmax scaling (range ~[0,1])
+        if stats.min_value is not None and stats.max_value is not None:
+            if (
+                abs(stats.min_value) < 0.1
+                and abs(stats.max_value - 1.0) < 0.1
+            ):
+                return ScaleType.MINMAX
+
+        return ScaleType.RAW
+
+    def validate_features(
+        self, df: pl.DataFrame, columns: list[str]
+    ) -> list[ValidationIssue]:
+        """Validate feature scale consistency.
+
+        Args:
+            df: Input DataFrame
+            columns: List of feature columns
+
+        Returns:
+            List of validation issues
+        """
+        issues: list[ValidationIssue] = []
+
+        if len(columns) == 0:
+            return issues
+
+        # Compute stats for all features
+        feature_stats: list[FeatureStats] = []
+        for col in columns:
+            stats = self._compute_feature_stats(df, col)
+            feature_stats.append(stats)
+
+        # Check for scale inconsistency
+        scales = []
+        for stats in feature_stats:
+            if stats.scale is not None and stats.scale > 0:
+                scales.append((stats.name, stats.scale))
+
+        if len(scales) > 1:
+            max_scale = max(s[1] for s in scales)
+            min_scale = min(s[1] for s in scales)
+
+            if min_scale > 0:
+                scale_ratio = max_scale / min_scale
+                if scale_ratio > self.max_scale_ratio:
+                    largest = max(scales, key=lambda x: x[1])
+                    smallest = min(scales, key=lambda x: x[1])
+                    issues.append(
+                        ValidationIssue(
+                            column="multiple",
+                            issue_type="scale_inconsistency",
+                            count=len(columns),
+                            severity=Severity.MEDIUM,
+                            details=(
+                                f"Feature scales vary by {scale_ratio:.1f}x. "
+                                f"Largest: {largest[0]} (scale={largest[1]:.2f}), "
+                                f"Smallest: {smallest[0]} (scale={smallest[1]:.2f}). "
+                                f"Consider normalizing features."
+                            ),
+                            expected=f"Scale ratio <= {self.max_scale_ratio}",
+                        )
+                    )
+
+        # Check for extreme magnitudes
+        extreme_features = []
+        for stats in feature_stats:
+            if stats.max_value is not None and abs(stats.max_value) > self.max_magnitude:
+                extreme_features.append((stats.name, stats.max_value))
+            elif stats.min_value is not None and abs(stats.min_value) > self.max_magnitude:
+                extreme_features.append((stats.name, stats.min_value))
+
+        if extreme_features:
+            details = [f"{name}: {val:.2e}" for name, val in extreme_features[:5]]
+            issues.append(
+                ValidationIssue(
+                    column="multiple",
+                    issue_type="extreme_magnitude",
+                    count=len(extreme_features),
+                    severity=Severity.MEDIUM,
+                    details=(
+                        f"Found {len(extreme_features)} features with extreme magnitudes. "
+                        f"Features: {', '.join(details)}"
+                    ),
+                    expected=f"Magnitude <= {self.max_magnitude:.2e}",
+                )
+            )
+
+        # Check expected scale violations
+        if self.expected_scale:
+            violations = []
+            for stats in feature_stats:
+                detected = self._detect_scale_type(stats)
+                if detected != self.expected_scale and detected != ScaleType.UNKNOWN:
+                    violations.append((stats.name, detected.value))
+
+            if violations:
+                details = [f"{name} ({scale})" for name, scale in violations[:5]]
+                issues.append(
+                    ValidationIssue(
+                        column="multiple",
+                        issue_type="unexpected_scale_type",
+                        count=len(violations),
+                        severity=Severity.LOW,
+                        details=(
+                            f"Found {len(violations)} features not matching expected "
+                            f"scale type '{self.expected_scale.value}'. "
+                            f"Features: {', '.join(details)}"
+                        ),
+                        expected=f"Scale type: {self.expected_scale.value}",
+                    )
+                )
+
+        # Check for standard scaling if requested
+        if self.check_standard_scale:
+            not_standard = []
+            for stats in feature_stats:
+                if stats.mean is None or stats.std is None:
+                    continue
+
+                mean_off = abs(stats.mean) > self.mean_tolerance
+                std_off = abs(stats.std - 1.0) > self.std_tolerance
+
+                if mean_off or std_off:
+                    not_standard.append(
+                        (stats.name, stats.mean, stats.std)
+                    )
+
+            if not_standard:
+                details = [
+                    f"{name} (mean={mean:.2f}, std={std:.2f})"
+                    for name, mean, std in not_standard[:5]
+                ]
+                issues.append(
+                    ValidationIssue(
+                        column="multiple",
+                        issue_type="not_standard_scaled",
+                        count=len(not_standard),
+                        severity=Severity.LOW,
+                        details=(
+                            f"Found {len(not_standard)} features not standard scaled. "
+                            f"Features: {', '.join(details)}"
+                        ),
+                        expected=f"Mean ~0 (±{self.mean_tolerance}), Std ~1 (±{self.std_tolerance})",
+                    )
+                )
+
+        return issues
+
+    def validate(self, lf: pl.LazyFrame) -> list[ValidationIssue]:
+        """Validate the LazyFrame.
+
+        Args:
+            lf: Input LazyFrame
+
+        Returns:
+            List of validation issues
+        """
+        df = lf.collect()
+        columns = self._get_feature_columns(df)
+
+        if not columns:
+            return []
+
+        return self.validate_features(df, columns)

truthound/validators/multi_column/__init__.py

@@ -0,0 +1,89 @@
+"""Multi-column compound validators.
+
+This module provides 18 validators for checking relationships across multiple columns:
+
+Arithmetic Validators:
+- ColumnSumValidator: Validate sum of columns
+- ColumnProductValidator: Validate product of columns
+- ColumnDifferenceValidator: Validate difference between columns
+- ColumnRatioValidator: Validate ratio between columns
+- ColumnPercentageValidator: Validate percentage calculation
+
+Comparison Validators:
+- ColumnComparisonValidator: Compare two columns (>, <, ==, etc.)
+- ColumnChainComparisonValidator: Chain comparisons (a < b < c)
+- ColumnMaxValidator: Validate max of columns
+- ColumnMinValidator: Validate min of columns
+- ColumnMeanValidator: Validate mean of columns
+
+Consistency Validators:
+- ColumnConsistencyValidator: Rule-based consistency checks
+- ColumnMutualExclusivityValidator: Only one column can have value
+- ColumnCoexistenceValidator: Columns must all be filled or all empty
+- ColumnDependencyValidator: Conditional column requirements
+- ColumnImplicationValidator: If A then B logic
+
+Statistical Validators:
+- ColumnCorrelationValidator: Check correlation between columns
+- ColumnCovarianceValidator: Check covariance between columns
+- MultiColumnVarianceValidator: Check variance across columns
+"""
+
+from truthound.validators.multi_column.base import (
+    MultiColumnValidator,
+    ColumnArithmeticValidator,
+)
+from truthound.validators.multi_column.arithmetic import (
+    ColumnSumValidator,
+    ColumnProductValidator,
+    ColumnDifferenceValidator,
+    ColumnRatioValidator,
+    ColumnPercentageValidator,
+)
+from truthound.validators.multi_column.comparison import (
+    ColumnComparisonValidator,
+    ColumnChainComparisonValidator,
+    ColumnMaxValidator,
+    ColumnMinValidator,
+    ColumnMeanValidator,
+)
+from truthound.validators.multi_column.consistency import (
+    ColumnConsistencyValidator,
+    ColumnMutualExclusivityValidator,
+    ColumnCoexistenceValidator,
+    ColumnDependencyValidator,
+    ColumnImplicationValidator,
+)
+from truthound.validators.multi_column.statistical import (
+    ColumnCorrelationValidator,
+    ColumnCovarianceValidator,
+    MultiColumnVarianceValidator,
+)
+
+__all__ = [
+    # Base classes
+    "MultiColumnValidator",
+    "ColumnArithmeticValidator",
+    # Arithmetic
+    "ColumnSumValidator",
+    "ColumnProductValidator",
+    "ColumnDifferenceValidator",
+    "ColumnRatioValidator",
+    "ColumnPercentageValidator",
+    # Comparison
+    "ColumnComparisonValidator",
+    "ColumnChainComparisonValidator",
+    "ColumnMaxValidator",
+    "ColumnMinValidator",
+    "ColumnMeanValidator",
+    # Consistency
+    "ColumnConsistencyValidator",
+    "ColumnMutualExclusivityValidator",
+    "ColumnCoexistenceValidator",
+    "ColumnDependencyValidator",
+    "ColumnImplicationValidator",
+    # Statistical
+    "ColumnCorrelationValidator",
+    "ColumnCovarianceValidator",
+    "MultiColumnVarianceValidator",
+]

truthound/validators/multi_column/arithmetic.py

@@ -0,0 +1,284 @@
+"""Multi-column arithmetic validators.
+
+Validators for checking arithmetic relationships between columns.
+"""
+
+from typing import Any
+
+import polars as pl
+
+from truthound.validators.multi_column.base import ColumnArithmeticValidator
+from truthound.validators.registry import register_validator
+
+
+@register_validator
+class ColumnSumValidator(ColumnArithmeticValidator):
+    """Validates that the sum of columns equals expected value or column.
+
+    Example:
+        # Sum of parts equals total
+        validator = ColumnSumValidator(
+            columns=["part_a", "part_b", "part_c"],
+            result_column="total",
+        )
+
+        # Sum equals constant
+        validator = ColumnSumValidator(
+            columns=["q1", "q2", "q3", "q4"],
+            expected_value=100,
+        )
+
+        # Sum within range
+        validator = ColumnSumValidator(
+            columns=["score_1", "score_2"],
+            min_value=0,
+            max_value=200,
+        )
+    """
+
+    name = "column_sum"
+    category = "multi_column"
+
+    def get_computed_expression(self) -> pl.Expr:
+        """Return sum of columns."""
+        result = pl.col(self.columns[0])
+        for col in self.columns[1:]:
+            result = result + pl.col(col)
+        return result
+
+    def _get_issue_type(self) -> str:
+        return "column_sum_mismatch"
+
+    def _get_expected(self) -> str:
+        if self.result_column:
+            return f"sum({', '.join(self.columns)}) = {self.result_column}"
+        elif self.expected_value is not None:
+            return f"sum({', '.join(self.columns)}) = {self.expected_value}"
+        else:
+            bounds = []
+            if self.min_value is not None:
+                bounds.append(f">= {self.min_value}")
+            if self.max_value is not None:
+                bounds.append(f"<= {self.max_value}")
+            return f"sum({', '.join(self.columns)}) {' and '.join(bounds)}"
+
+
+@register_validator
+class ColumnProductValidator(ColumnArithmeticValidator):
+    """Validates that the product of columns equals expected value or column.
+
+    Example:
+        # Quantity * price = total
+        validator = ColumnProductValidator(
+            columns=["quantity", "unit_price"],
+            result_column="total_price",
+        )
+
+        # With tolerance for floating point
+        validator = ColumnProductValidator(
+            columns=["rate", "hours"],
+            result_column="earnings",
+            tolerance=0.01,
+        )
+    """
+
+    name = "column_product"
+    category = "multi_column"
+
+    def get_computed_expression(self) -> pl.Expr:
+        """Return product of columns."""
+        result = pl.col(self.columns[0])
+        for col in self.columns[1:]:
+            result = result * pl.col(col)
+        return result
+
+    def _get_issue_type(self) -> str:
+        return "column_product_mismatch"
+
+    def _get_expected(self) -> str:
+        if self.result_column:
+            return f"{' * '.join(self.columns)} = {self.result_column}"
+        elif self.expected_value is not None:
+            return f"{' * '.join(self.columns)} = {self.expected_value}"
+        else:
+            bounds = []
+            if self.min_value is not None:
+                bounds.append(f">= {self.min_value}")
+            if self.max_value is not None:
+                bounds.append(f"<= {self.max_value}")
+            return f"{' * '.join(self.columns)} {' and '.join(bounds)}"
+
+
+@register_validator
+class ColumnDifferenceValidator(ColumnArithmeticValidator):
+    """Validates that the difference between columns meets criteria.
+
+    Example:
+        # End date - start date should be positive
+        validator = ColumnDifferenceValidator(
+            columns=["end_value", "start_value"],
+            min_value=0,
+        )
+
+        # Difference equals another column
+        validator = ColumnDifferenceValidator(
+            columns=["gross", "tax"],
+            result_column="net",
+        )
+    """
+
+    name = "column_difference"
+    category = "multi_column"
+
+    def get_computed_expression(self) -> pl.Expr:
+        """Return difference of columns (first - rest)."""
+        result = pl.col(self.columns[0])
+        for col in self.columns[1:]:
+            result = result - pl.col(col)
+        return result
+
+    def _get_issue_type(self) -> str:
+        return "column_difference_mismatch"
+
+    def _get_expected(self) -> str:
+        diff_expr = f"{self.columns[0]} - " + " - ".join(self.columns[1:])
+        if self.result_column:
+            return f"({diff_expr}) = {self.result_column}"
+        elif self.expected_value is not None:
+            return f"({diff_expr}) = {self.expected_value}"
+        else:
+            bounds = []
+            if self.min_value is not None:
+                bounds.append(f">= {self.min_value}")
+            if self.max_value is not None:
+                bounds.append(f"<= {self.max_value}")
+            return f"({diff_expr}) {' and '.join(bounds)}"
+
+
+@register_validator
+class ColumnRatioValidator(ColumnArithmeticValidator):
+    """Validates that the ratio between columns meets criteria.
+
+    Example:
+        # Profit margin check
+        validator = ColumnRatioValidator(
+            columns=["profit", "revenue"],
+            min_value=0.1,  # At least 10% margin
+            max_value=0.5,  # At most 50% margin
+        )
+
+        # Ratio equals expected column
+        validator = ColumnRatioValidator(
+            columns=["numerator", "denominator"],
+            result_column="ratio",
+            tolerance=0.001,
+        )
+    """
+
+    name = "column_ratio"
+    category = "multi_column"
+
+    def __init__(
+        self,
+        columns: list[str],
+        handle_zero_division: str = "skip",
+        **kwargs: Any,
+    ):
+        """Initialize ratio validator.
+
+        Args:
+            columns: [numerator, denominator] columns
+            handle_zero_division: How to handle zero denominator: "skip", "fail", "allow"
+            **kwargs: Additional config
+        """
+        if len(columns) != 2:
+            raise ValueError("ColumnRatioValidator requires exactly 2 columns [numerator, denominator]")
+        super().__init__(columns=columns, **kwargs)
+        self.handle_zero_division = handle_zero_division
+
+    def get_computed_expression(self) -> pl.Expr:
+        """Return ratio of columns."""
+        return pl.col(self.columns[0]) / pl.col(self.columns[1])
+
+    def get_validation_expression(self) -> pl.Expr:
+        """Return validation expression handling zero division."""
+        denominator = pl.col(self.columns[1])
+
+        if self.handle_zero_division == "skip":
+            # Skip rows where denominator is zero (treat as valid)
+            zero_check = denominator == 0
+            arithmetic_check = super().get_validation_expression()
+            return zero_check | arithmetic_check
+        elif self.handle_zero_division == "fail":
+            # Fail if denominator is zero
+            zero_check = denominator != 0
+            arithmetic_check = super().get_validation_expression()
+            return zero_check & arithmetic_check
+        else:  # allow
+            return super().get_validation_expression()
+
+    def _get_issue_type(self) -> str:
+        return "column_ratio_mismatch"
+
+    def _get_expected(self) -> str:
+        ratio_expr = f"{self.columns[0]} / {self.columns[1]}"
+        if self.result_column:
+            return f"({ratio_expr}) = {self.result_column}"
+        elif self.expected_value is not None:
+            return f"({ratio_expr}) = {self.expected_value}"
+        else:
+            bounds = []
+            if self.min_value is not None:
+                bounds.append(f">= {self.min_value}")
+            if self.max_value is not None:
+                bounds.append(f"<= {self.max_value}")
+            return f"({ratio_expr}) {' and '.join(bounds)}"
+
+
+@register_validator
+class ColumnPercentageValidator(ColumnArithmeticValidator):
+    """Validates that column represents valid percentage of total.
+
+    Example:
+        # Part should be percentage of total
+        validator = ColumnPercentageValidator(
+            columns=["part", "total"],
+            min_value=0,
+            max_value=100,
+        )
+    """
+
+    name = "column_percentage"
+    category = "multi_column"
+
+    def __init__(
+        self,
+        columns: list[str],
+        **kwargs: Any,
+    ):
+        if len(columns) != 2:
+            raise ValueError("ColumnPercentageValidator requires exactly 2 columns [part, total]")
+        super().__init__(columns=columns, **kwargs)
+
+    def get_computed_expression(self) -> pl.Expr:
+        """Return percentage (part/total * 100)."""
+        return (pl.col(self.columns[0]) / pl.col(self.columns[1])) * 100
+
+    def get_validation_expression(self) -> pl.Expr:
+        """Handle zero division."""
+        total = pl.col(self.columns[1])
+        zero_check = total == 0
+        arithmetic_check = super().get_validation_expression()
+        return zero_check | arithmetic_check
+
+    def _get_issue_type(self) -> str:
+        return "column_percentage_mismatch"
+
+    def _get_expected(self) -> str:
+        pct_expr = f"({self.columns[0]} / {self.columns[1]}) * 100"
+        bounds = []
+        if self.min_value is not None:
+            bounds.append(f">= {self.min_value}%")
+        if self.max_value is not None:
+            bounds.append(f"<= {self.max_value}%")
+        return f"{pct_expr} {' and '.join(bounds)}" if bounds else pct_expr