processbehavior 0.2.0__py3-none-any.whl

processbehavior/signals/detector.py

@@ -0,0 +1,328 @@
+"""
+Main signal detection engine.
+
+Orchestrates rule detection and builds comprehensive results.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+from ..exceptions import ValidationError
+from .config import SignalConfig
+from .detectors import (
+    detect_avoiding_center,
+    detect_beyond_limits,
+    detect_oscillation,
+    detect_reduced_variation,
+    detect_run,
+    detect_trend,
+    detect_zone_a_2_of_3,
+    detect_zone_b_4_of_5,
+)
+from .result import SignalResult
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+
+class SignalDetector:
+    """
+    Main signal detection engine.
+
+    Applies Western Electric rules to control chart data and returns
+    comprehensive violation information.
+
+    Examples
+    --------
+    >>> detector = SignalDetector()
+    >>> signals = detector.detect(data, stats, config)
+    """
+
+    # Rule mapping
+    RULE_DETECTORS = {
+        'rule_1': detect_beyond_limits,
+        'rule_2': detect_zone_a_2_of_3,
+        'rule_3': detect_zone_b_4_of_5,
+        'rule_4': detect_run,
+        'rule_5': detect_trend,
+        'rule_6': detect_oscillation,
+        'rule_7': detect_reduced_variation,
+        'rule_8': detect_avoiding_center,
+    }
+
+    RULE_DESCRIPTIONS = {
+        'rule_1': 'Point beyond control limits',
+        'rule_2': '2 of 3 consecutive points in Zone A',
+        'rule_3': '4 of 5 consecutive points in Zone B or beyond',
+        'rule_4': '8+ consecutive points on same side of center',
+        'rule_5': '6+ consecutive points trending',
+        'rule_6': '14+ consecutive points alternating',
+        'rule_7': '15+ consecutive points in Zone C',
+        'rule_8': '8+ consecutive points avoiding Zone C',
+    }
+
+    def detect(
+        self,
+        data: pd.DataFrame,
+        stats: dict,
+        config: SignalConfig | None = None,
+        value_col: str = 'mean',
+        chart_name: str = 'Chart',
+        chart_type: str = 'Xbar',
+    ) -> SignalResult:
+        """
+        Detect signals in control chart data.
+
+        Parameters
+        ----------
+        data : DataFrame
+            Chart data with observations
+        stats : dict
+            Chart statistics (upl, lpl, center, etc.)
+        config : SignalConfig, optional
+            Detection configuration (uses defaults if None)
+        value_col : str, default 'mean'
+            Name of value column
+        chart_name : str, default 'Chart'
+            Name of chart for reporting
+        chart_type : str, default 'Xbar'
+            Chart type ('Xbar', 'S', 'X', 'mR') - determines applicable rules
+
+        Returns
+        -------
+        SignalResult
+            Comprehensive signal detection results
+
+        Examples
+        --------
+        >>> detector = SignalDetector()
+        >>> signals = detector.detect(chart_data, chart_stats, chart_type='X')
+        >>> print(signals.summary)
+        """
+        config = config or SignalConfig()
+
+        # Get applicable rules for this chart type
+        applicable_rules = config.get_rules_for_chart(chart_type)
+
+        # Log rule selection
+        if logger.isEnabledFor(logging.INFO):
+            all_rules = [f'rule_{i}' for i in range(1, 9)]
+            skipped_rules = [r for r in all_rules if r not in applicable_rules]
+            if skipped_rules:
+                logger.info(
+                    f"Chart '{chart_name}' (type: {chart_type}): "
+                    f'Applying rules {applicable_rules}. '
+                    f'Skipped {skipped_rules} (not applicable for {chart_type} charts)'
+                )
+            else:
+                logger.info(f"Chart '{chart_name}' (type: {chart_type}): Applying all rules {applicable_rules}")
+
+        # Validate inputs (empty data / missing stats only). Per-rule observation
+        # minimums are enforced below by skipping the rules that can't run — a small
+        # group still gets the rules it supports, rather than aborting the whole call.
+        self._validate_inputs(data, stats)
+
+        # Apply filtering
+        filtered_data = self._filter_data(data, config)
+
+        # Detect if limits vary
+        limits_vary = self._limits_vary(stats)
+
+        # Calculate zones (constant or per-row)
+        if limits_vary:
+            # Use per-row limits from data
+            zones = self._calculate_per_row_zones(filtered_data, stats, config)
+        else:
+            # Use constant limits from stats
+            center = stats['center']
+            sigma = (stats['upl'] - center) / 3
+            zones = config.zone_definition.get_boundaries(center, sigma)
+
+        # Detect violations for each applicable rule
+        all_violations = pd.DataFrame(index=filtered_data.index)
+        # Applicable rules skipped for too few observations (rule -> reason), so the
+        # result can report partial evaluation instead of raising.
+        rules_skipped: dict[str, str] = {}
+
+        for rule_name in applicable_rules:
+            if rule_name not in self.RULE_DETECTORS:
+                logger.warning(f'Unknown rule: {rule_name}, skipping')
+                continue
+
+            # Check minimum observations — skip (don't abort) rules the group is too small for.
+            min_obs = self._get_min_observations(rule_name)
+            if len(filtered_data) < min_obs:
+                logger.debug(
+                    f'Skipping {rule_name}: insufficient observations (need {min_obs}, have {len(filtered_data)})'
+                )
+                rules_skipped[rule_name] = f'needs {min_obs} observations, have {len(filtered_data)}'
+                continue
+
+            # Apply detector
+            detector = self.RULE_DETECTORS[rule_name]
+
+            try:
+                if rule_name in ['rule_2', 'rule_3', 'rule_7', 'rule_8']:
+                    # Zone-based rules
+                    violations = detector(filtered_data, stats, value_col, zones, limits_vary)
+                elif rule_name == 'rule_1':
+                    # Rule 1 can use per-row limits
+                    violations = detector(filtered_data, stats, value_col, limits_vary)
+                else:
+                    # Other rules (4, 5, 6) don't use zones
+                    violations = detector(filtered_data, stats, value_col)
+
+                all_violations[rule_name] = violations
+
+            except Exception as e:
+                logger.error(f'Error detecting {rule_name}: {e}')
+                all_violations[rule_name] = False
+
+        # Build result
+        return self._build_result(
+            data=filtered_data, violations=all_violations, stats=stats, value_col=value_col,
+            chart_name=chart_name, rules_skipped=rules_skipped,
+        )
+
+    def _validate_inputs(self, data: pd.DataFrame, stats: dict):
+        """Validate inputs and provide helpful errors.
+
+        Only genuinely-unrecoverable conditions raise here (empty data, missing
+        limit statistics). Too-few-observations is NOT an error — the caller skips
+        the rules that need more points and reports partial evaluation.
+        """
+        if data.empty:
+            raise ValidationError('Cannot detect signals on empty DataFrame')
+
+        required_stats = ['upl', 'lpl', 'center']
+        missing = [s for s in required_stats if s not in stats]
+        if missing:
+            raise ValidationError(f'Missing required statistics: {missing}\nAvailable: {list(stats.keys())}')
+
+    def _filter_data(self, data: pd.DataFrame, config: SignalConfig) -> pd.DataFrame:
+        """Apply filtering options."""
+        filtered = data.copy()
+
+        if config.ignore_first_n > 0:
+            filtered = filtered.iloc[config.ignore_first_n :]
+
+        if config.ignore_last_n > 0:
+            filtered = filtered.iloc[: -config.ignore_last_n]
+
+        return filtered
+
+    def _get_min_observations(self, rule_name: str) -> int:
+        """Get minimum observations for a rule."""
+        minimums = {
+            'rule_1': 1,
+            'rule_2': 3,
+            'rule_3': 5,
+            'rule_4': 8,
+            'rule_5': 6,
+            'rule_6': 14,
+            'rule_7': 15,
+            'rule_8': 8,
+        }
+        return minimums.get(rule_name, 1)
+
+    def _build_result(
+        self, data: pd.DataFrame, violations: pd.DataFrame, stats: dict, value_col: str, chart_name: str,
+        rules_skipped: dict[str, str] | None = None,
+    ) -> SignalResult:
+        """Build SignalResult from violation matrix."""
+        # Create violation records
+        records = []
+
+        # Check if limits vary
+        limits_vary = self._limits_vary(stats)
+
+        for idx in data.index:
+            for rule_name in violations.columns:
+                if violations.loc[idx, rule_name]:
+                    # Use per-row limits if they vary, else use stats
+                    if limits_vary and 'upl' in data.columns and 'lpl' in data.columns:
+                        ucl = data.loc[idx, 'upl']
+                        lcl = data.loc[idx, 'lpl']
+                    else:
+                        ucl = stats['upl']
+                        lcl = stats['lpl']
+
+                    records.append(
+                        {
+                            'obs_id': idx,
+                            'rule_name': rule_name,
+                            'rule_number': int(rule_name.split('_')[1]),
+                            'description': self.RULE_DESCRIPTIONS[rule_name],
+                            'value': data.loc[idx, value_col],
+                            'center': stats['center'],
+                            'upl': ucl,
+                            'lpl': lcl,
+                        }
+                    )
+
+        violation_df = pd.DataFrame(records) if records else pd.DataFrame()
+
+        return SignalResult(violations=violation_df, chart_name=chart_name, data=data, stats=stats,
+                            rules_skipped=rules_skipped)
+
+    def _limits_vary(self, stats: dict) -> bool:
+        """Check if control limits vary (per-row limits)."""
+        return bool(stats.get('limits_vary'))
+
+    def _calculate_per_row_zones(self, data: pd.DataFrame, stats: dict, config: SignalConfig) -> pd.DataFrame:
+        """
+        Calculate per-row zone boundaries for varying process limits.
+
+        When process limits vary per row (e.g., Xbar with varying n),
+        this calculates zone boundaries for each row based on that row's
+        specific upl/lpl values.
+
+        Parameters
+        ----------
+        data : DataFrame
+            Chart data with 'upl' and 'lpl' columns
+        stats : dict
+            Chart statistics with 'center' key
+        config : SignalConfig
+            Configuration with zone_definition
+
+        Returns
+        -------
+        DataFrame
+            Per-row zone boundaries with columns like 'A_upper_lower', 'A_upper_upper', etc.
+        """
+        if 'upl' not in data.columns or 'lpl' not in data.columns:
+            raise ValueError("Cannot calculate per-row zones: data missing 'upl' or 'lpl' columns")
+
+        center = stats['center']
+        zone_def = config.zone_definition
+
+        # Calculate sigma per row
+        sigma = (data['upl'] - center) / 3
+
+        # Calculate all zone boundaries per row
+        zones_df = pd.DataFrame(index=data.index)
+
+        # Upper zones
+        zones_df['A_upper_lower'] = center + zone_def.A[0] * sigma
+        zones_df['A_upper_upper'] = center + zone_def.A[1] * sigma
+        zones_df['B_upper_lower'] = center + zone_def.B[0] * sigma
+        zones_df['B_upper_upper'] = center + zone_def.B[1] * sigma
+        zones_df['C_upper_lower'] = center + zone_def.C[0] * sigma
+        zones_df['C_upper_upper'] = center + zone_def.C[1] * sigma
+
+        # Lower zones
+        zones_df['A_lower_lower'] = center - zone_def.A[1] * sigma
+        zones_df['A_lower_upper'] = center - zone_def.A[0] * sigma
+        zones_df['B_lower_lower'] = center - zone_def.B[1] * sigma
+        zones_df['B_lower_upper'] = center - zone_def.B[0] * sigma
+        zones_df['C_lower_lower'] = center - zone_def.C[1] * sigma
+        zones_df['C_lower_upper'] = center - zone_def.C[0] * sigma
+
+        return zones_df

processbehavior/signals/detectors.py

@@ -0,0 +1,368 @@
+"""
+Vectorized rule detection functions.
+
+All detectors use pandas/numpy for performance.
+Each detector returns a boolean Series indicating violations.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+
+def detect_beyond_limits(data: pd.DataFrame, stats: dict, value_col: str, limits_vary: bool = False) -> pd.Series:
+    """
+    Rule 1: Points beyond control limits.
+
+    Detects any point beyond ±3σ from centerline.
+
+    Parameters
+    ----------
+    data : DataFrame
+        Chart data with optional 'upl' and 'lpl' columns for varying limits
+    stats : dict
+        Chart statistics with 'upl' and 'lpl' keys
+    value_col : str
+        Name of value column
+    limits_vary : bool, default False
+        If True, use per-row 'upl' and 'lpl' from data columns
+
+    Returns
+    -------
+    Series of bool
+        True for violations
+    """
+    values = data[value_col]
+
+    # Use per-row limits if they vary, else use constant limits from stats
+    if limits_vary and 'upl' in data.columns and 'lpl' in data.columns:
+        ucl = data['upl']
+        lcl = data['lpl']
+    else:
+        ucl = stats['upl']
+        lcl = stats['lpl']
+
+    return (values > ucl) | (values < lcl)
+
+
+def detect_zone_a_2_of_3(
+    data: pd.DataFrame,
+    stats: dict,
+    value_col: str,
+    zones,  # dict or DataFrame
+    limits_vary: bool = False,
+) -> pd.Series:
+    """
+    Rule 2: 2 of 3 consecutive points in Zone A.
+
+    Detects when 2 out of 3 consecutive points fall in Zone A
+    (between 2σ and 3σ from centerline), same side.
+
+    Parameters
+    ----------
+    data : DataFrame
+        Chart data
+    stats : dict
+        Chart statistics
+    value_col : str
+        Name of value column
+    zones : dict or DataFrame
+        Zone boundaries (dict if constant, DataFrame if per-row)
+    limits_vary : bool, default False
+        If True, zones is a DataFrame with per-row boundaries
+
+    Returns
+    -------
+    Series of bool
+        True for violations
+    """
+    values = data[value_col]
+
+    # Determine which zone each point is in
+    if limits_vary:
+        # Per-row zones
+        in_upper_a = (values > zones['A_upper_lower']) & (values <= zones['A_upper_upper'])
+        in_lower_a = (values >= zones['A_lower_lower']) & (values < zones['A_lower_upper'])
+    else:
+        # Constant zones
+        in_upper_a = (values > zones['A_upper'][0]) & (values <= zones['A_upper'][1])
+        in_lower_a = (values >= zones['A_lower'][0]) & (values < zones['A_lower'][1])
+
+    # Rolling window count
+    upper_count = in_upper_a.astype(int).rolling(window=3, min_periods=3).sum()
+    lower_count = in_lower_a.astype(int).rolling(window=3, min_periods=3).sum()
+
+    # Flag if 2 or more in window
+    violations = (upper_count >= 2) | (lower_count >= 2)
+
+    return violations.fillna(False)
+
+
+def detect_zone_b_4_of_5(
+    data: pd.DataFrame,
+    stats: dict,
+    value_col: str,
+    zones,  # dict or DataFrame
+    limits_vary: bool = False,
+) -> pd.Series:
+    """
+    Rule 3: 4 of 5 consecutive points in Zone B or beyond.
+
+    Detects when 4 out of 5 consecutive points fall in Zone B or beyond
+    (beyond 1σ from centerline), same side.
+
+    Parameters
+    ----------
+    data : DataFrame
+        Chart data
+    stats : dict
+        Chart statistics
+    value_col : str
+        Name of value column
+    zones : dict or DataFrame
+        Zone boundaries (dict if constant, DataFrame if per-row)
+    limits_vary : bool, default False
+        If True, zones is a DataFrame with per-row boundaries
+
+    Returns
+    -------
+    Series of bool
+        True for violations
+    """
+    values = data[value_col]
+
+    # In Zone B or beyond (same side)
+    if limits_vary:
+        # Per-row zones
+        upper = values > zones['B_upper_lower']
+        lower = values < zones['B_lower_upper']
+    else:
+        # Constant zones
+        upper = values > zones['B_upper'][0]
+        lower = values < zones['B_lower'][1]
+
+    upper_count = upper.astype(int).rolling(window=5, min_periods=5).sum()
+    lower_count = lower.astype(int).rolling(window=5, min_periods=5).sum()
+
+    violations = (upper_count >= 4) | (lower_count >= 4)
+    return violations.fillna(False)
+
+
+def detect_run(data: pd.DataFrame, stats: dict, value_col: str, length: int = 8) -> pd.Series:
+    """
+    Rule 4: Run of points on same side of centerline.
+
+    Detects when 8 or more consecutive points fall on the same side
+    of the centerline.
+
+    Parameters
+    ----------
+    data : DataFrame
+        Chart data
+    stats : dict
+        Chart statistics with 'center' key
+    value_col : str
+        Name of value column
+    length : int, default 8
+        Number of consecutive points required
+
+    Returns
+    -------
+    Series of bool
+        True for violations
+    """
+    values = data[value_col]
+    center = stats.get('center', stats.get('Mean'))  # Try 'center' first, fallback to 'Mean'
+
+    # Above or below center
+    above = (values > center).astype(int)
+    below = (values < center).astype(int)
+
+    # Count consecutive
+    above_streak = above.rolling(window=length, min_periods=length).sum()
+    below_streak = below.rolling(window=length, min_periods=length).sum()
+
+    violations = (above_streak == length) | (below_streak == length)
+    return violations.fillna(False)
+
+
+def detect_trend(
+    data: pd.DataFrame, stats: dict, value_col: str, length: int = 6, direction: str = 'both'
+) -> pd.Series:
+    """
+    Rule 5: Trending sequence.
+
+    Detects when 6 or more consecutive points are steadily
+    increasing or decreasing.
+
+    Parameters
+    ----------
+    data : DataFrame
+        Chart data
+    stats : dict
+        Chart statistics (not used but kept for consistency)
+    value_col : str
+        Name of value column
+    length : int, default 6
+        Number of consecutive points required
+    direction : {'up', 'down', 'both'}, default 'both'
+        Which direction trends to detect
+
+    Returns
+    -------
+    Series of bool
+        True for violations
+    """
+    values = data[value_col]
+
+    # Calculate differences
+    diffs = values.diff()
+
+    up_trend = pd.Series(False, index=values.index)
+    down_trend = pd.Series(False, index=values.index)
+
+    if direction in ['up', 'both']:
+        increasing = (diffs > 0).astype(int).rolling(window=length, min_periods=length).sum()
+        up_trend = increasing == length
+
+    if direction in ['down', 'both']:
+        decreasing = (diffs < 0).astype(int).rolling(window=length, min_periods=length).sum()
+        down_trend = decreasing == length
+
+    violations = up_trend | down_trend
+    return violations.fillna(False)
+
+
+def detect_oscillation(data: pd.DataFrame, stats: dict, value_col: str, length: int = 14) -> pd.Series:
+    """
+    Rule 6: Alternating up-down pattern.
+
+    Detects when 14 or more consecutive points alternate up and down.
+
+    Parameters
+    ----------
+    data : DataFrame
+        Chart data
+    stats : dict
+        Chart statistics (not used but kept for consistency)
+    value_col : str
+        Name of value column
+    length : int, default 14
+        Number of consecutive points required
+
+    Returns
+    -------
+    Series of bool
+        True for violations
+    """
+    values = data[value_col]
+
+    # Detect direction changes
+    diffs = values.diff()
+    changes = (diffs * diffs.shift(1) < 0).astype(int)
+
+    # Count consecutive changes
+    change_count = changes.rolling(window=length - 1, min_periods=length - 1).sum()
+
+    violations = change_count == (length - 1)
+    return violations.fillna(False)
+
+
+def detect_reduced_variation(
+    data: pd.DataFrame,
+    stats: dict,
+    value_col: str,
+    zones,  # dict or DataFrame
+    limits_vary: bool = False,
+    length: int = 15,
+) -> pd.Series:
+    """
+    Rule 7: Points within Zone C (reduced variation).
+
+    Detects when 15 or more consecutive points fall within Zone C
+    (within ±1σ of centerline), indicating reduced variation.
+
+    Parameters
+    ----------
+    data : DataFrame
+        Chart data
+    stats : dict
+        Chart statistics
+    value_col : str
+        Name of value column
+    zones : dict or DataFrame
+        Zone boundaries (dict if constant, DataFrame if per-row)
+    limits_vary : bool, default False
+        If True, zones is a DataFrame with per-row boundaries
+    length : int, default 15
+        Number of consecutive points required
+
+    Returns
+    -------
+    Series of bool
+        True for violations
+    """
+    values = data[value_col]
+
+    # Within Zone C
+    if limits_vary:
+        # Per-row zones
+        in_zone_c = (values > zones['C_lower_lower']) & (values < zones['C_upper_upper'])
+    else:
+        # Constant zones
+        in_zone_c = (values > zones['C_lower'][0]) & (values < zones['C_upper'][1])
+
+    in_c_count = in_zone_c.astype(int).rolling(window=length, min_periods=length).sum()
+
+    violations = in_c_count == length
+    return violations.fillna(False)
+
+
+def detect_avoiding_center(
+    data: pd.DataFrame,
+    stats: dict,
+    value_col: str,
+    zones,  # dict or DataFrame
+    limits_vary: bool = False,
+    length: int = 8,
+) -> pd.Series:
+    """
+    Rule 8: Points avoiding Zone C.
+
+    Detects when 8 or more consecutive points fall outside Zone C
+    (beyond ±1σ from centerline).
+
+    Parameters
+    ----------
+    data : DataFrame
+        Chart data
+    stats : dict
+        Chart statistics
+    value_col : str
+        Name of value column
+    zones : dict or DataFrame
+        Zone boundaries (dict if constant, DataFrame if per-row)
+    limits_vary : bool, default False
+        If True, zones is a DataFrame with per-row boundaries
+    length : int, default 8
+        Number of consecutive points required
+
+    Returns
+    -------
+    Series of bool
+        True for violations
+    """
+    values = data[value_col]
+
+    # Outside Zone C
+    if limits_vary:
+        # Per-row zones
+        outside_c = (values <= zones['C_lower_lower']) | (values >= zones['C_upper_upper'])
+    else:
+        # Constant zones
+        outside_c = (values <= zones['C_lower'][0]) | (values >= zones['C_upper'][1])
+
+    outside_count = outside_c.astype(int).rolling(window=length, min_periods=length).sum()
+
+    violations = outside_count == length
+    return violations.fillna(False)