ts-shape 0.0.0__py3-none-any.whl

ts_shape/context/__init__.py

@@ -0,0 +1,9 @@
+"""Context
+
+Utilities for enriching DataFrames with contextual information and mappings.
+
+Classes:
+- ValueMapper: Map categorical codes to readable values from external files.
+  - map_values: Merge and replace a target column using a CSV/JSON mapping table.
+  - _load_mapping_table: Load a mapping table from CSV or JSON.
+"""

ts_shape/context/value_mapping.py

@@ -0,0 +1,89 @@
+import pandas as pd  # type: ignore
+from typing import Union
+from ts_shape.utils.base import Base
+
+class ValueMapper(Base):
+    """
+    A class to map values from specified columns of a DataFrame using a mapping table (CSV or JSON file),
+    inheriting from the Base class.
+    """
+    
+    def __init__(
+        self, 
+        dataframe: pd.DataFrame, 
+        mapping_file: str, 
+        map_column: str, 
+        mapping_key_column: str, 
+        mapping_value_column: str, 
+        file_type: str = 'csv', 
+        sep: str = ',', 
+        encoding: str = 'utf-8', 
+        column_name: str = 'systime'
+    ) -> None:
+        """
+        Initializes ValueMapper and the base DataFrame from the Base class.
+
+        Args:
+            dataframe (pd.DataFrame): The DataFrame to be processed and mapped.
+            mapping_file (str): The file path of the mapping table (CSV or JSON).
+            map_column (str): The name of the column in the DataFrame that needs to be mapped.
+            mapping_key_column (str): The column in the mapping table to match with values from the DataFrame.
+            mapping_value_column (str): The column in the mapping table containing the values to map to.
+            file_type (str): The type of the mapping file ('csv' or 'json'). Defaults to 'csv'.
+            sep (str): The separator for CSV files. Defaults to ','.
+            encoding (str): The encoding to use for reading the file. Defaults to 'utf-8'.
+            column_name (str): The name of the column to sort the DataFrame by in the base class. Defaults to 'systime'.
+        """
+        # Initialize the Base class with the sorted DataFrame
+        super().__init__(dataframe, column_name)
+        
+        # Additional attributes for ValueMapper
+        self.map_column: str = map_column
+        self.mapping_key_column: str = mapping_key_column
+        self.mapping_value_column: str = mapping_value_column
+        self.sep: str = sep
+        self.encoding: str = encoding
+        
+        # Load the mapping table based on file type
+        self.mapping_table: pd.DataFrame = self._load_mapping_table(mapping_file, file_type)
+    
+    def _load_mapping_table(self, mapping_file: str, file_type: str) -> pd.DataFrame:
+        """
+        Loads the mapping table from a CSV or JSON file.
+
+        Args:
+            mapping_file (str): The file path of the mapping table.
+            file_type (str): The type of the file ('csv' or 'json').
+
+        Returns:
+            pd.DataFrame: The loaded mapping table as a DataFrame.
+        """
+        if file_type == 'csv':
+            return pd.read_csv(mapping_file, sep=self.sep, encoding=self.encoding)
+        elif file_type == 'json':
+            return pd.read_json(mapping_file, encoding=self.encoding)
+        else:
+            raise ValueError("Unsupported file type. Please use 'csv' or 'json'.")
+    
+    def map_values(self) -> pd.DataFrame:
+        """
+        Maps values in the specified DataFrame column based on the mapping table.
+
+        Returns:
+            pd.DataFrame: A new DataFrame with the mapped values.
+        """
+        # Merge the mapping table with the DataFrame based on the map_column and mapping_key_column
+        mapped_df = self.dataframe.merge(
+            self.mapping_table[[self.mapping_key_column, self.mapping_value_column]],
+            left_on=self.map_column,
+            right_on=self.mapping_key_column,
+            how='left'
+        )
+        
+        # Replace the original column with the mapped values
+        mapped_df[self.map_column] = mapped_df[self.mapping_value_column]
+        
+        # Drop unnecessary columns
+        mapped_df = mapped_df.drop([self.mapping_key_column, self.mapping_value_column], axis=1)
+        
+        return mapped_df

ts_shape/events/__init__.py

@@ -0,0 +1,14 @@
+"""Events
+
+Extract events from shaped timeseries across quality, maintenance,
+production, energy, correlation, and supply chain domains.
+
+Subpackages:
+- quality: Outlier detection, SPC, tolerance deviation
+- production: Machine state, throughput, changeover, OEE, alarms, batches, shifts
+- engineering: Setpoint changes, startup detection
+- maintenance: Degradation detection, failure prediction, vibration analysis
+- supplychain: Inventory monitoring, lead time analysis, demand patterns
+- energy: Consumption analysis, efficiency tracking
+- correlation: Signal correlation, anomaly correlation
+"""

ts_shape/events/correlation/__init__.py

@@ -0,0 +1,24 @@
+"""Correlation Events
+
+Cross-signal correlation analysis for detecting related anomalies
+and patterns across multiple timeseries signals.
+
+Classes:
+- SignalCorrelationEvents: Analyze correlations between signals.
+  - rolling_correlation: Time-windowed Pearson correlation between two signals.
+  - correlation_breakdown: Detect periods where normally correlated signals diverge.
+  - lag_correlation: Cross-correlation with time lag analysis.
+
+- AnomalyCorrelationEvents: Correlate anomaly events across signals.
+  - coincident_anomalies: Find anomalies occurring simultaneously across signals.
+  - cascade_detection: Detect anomaly cascades (signal A anomaly followed by B).
+  - root_cause_ranking: Rank signals by how often their anomalies precede others.
+"""
+
+from .signal_correlation import SignalCorrelationEvents
+from .anomaly_correlation import AnomalyCorrelationEvents
+
+__all__ = [
+    "SignalCorrelationEvents",
+    "AnomalyCorrelationEvents",
+]

ts_shape/events/correlation/anomaly_correlation.py

@@ -0,0 +1,248 @@
+import pandas as pd  # type: ignore
+import numpy as np  # type: ignore
+from typing import List, Dict, Any, Optional
+
+from ts_shape.utils.base import Base
+
+
+class AnomalyCorrelationEvents(Base):
+    """Correlation: Anomaly Correlation Analysis
+
+    Correlate anomaly events across multiple signals to find coincident
+    patterns, cascading failures, and root cause candidates.
+
+    Methods:
+    - coincident_anomalies: Find anomalies that co-occur within a time window.
+    - cascade_detection: Detect anomaly cascades (A precedes B within a window).
+    - root_cause_ranking: Rank signals by how often their anomalies precede others.
+    """
+
+    def __init__(
+        self,
+        dataframe: pd.DataFrame,
+        *,
+        event_uuid: str = "corr:anomaly",
+        value_column: str = "value_double",
+        time_column: str = "systime",
+    ) -> None:
+        super().__init__(dataframe, column_name=time_column)
+        self.event_uuid = event_uuid
+        self.value_column = value_column
+        self.time_column = time_column
+
+    def _detect_signal_anomalies(
+        self,
+        signal_uuid: str,
+        *,
+        z_threshold: float = 3.0,
+    ) -> pd.DataFrame:
+        """Internal: detect anomalies in a single signal using Z-score."""
+        s = (
+            self.dataframe[self.dataframe["uuid"] == signal_uuid]
+            .copy()
+            .sort_values(self.time_column)
+        )
+        if s.empty or len(s) < 3:
+            return pd.DataFrame(columns=[self.time_column, "uuid", self.value_column, "z_score"])
+
+        s[self.time_column] = pd.to_datetime(s[self.time_column])
+        values = s[self.value_column]
+        mean = values.mean()
+        std = values.std()
+        if std == 0:
+            return pd.DataFrame(columns=[self.time_column, "uuid", self.value_column, "z_score"])
+
+        s["z_score"] = ((values - mean) / std).abs()
+        anomalies = s[s["z_score"] >= z_threshold][[self.time_column, "uuid", self.value_column, "z_score"]]
+        return anomalies.reset_index(drop=True)
+
+    def coincident_anomalies(
+        self,
+        signal_uuids: List[str],
+        *,
+        z_threshold: float = 3.0,
+        coincidence_window: str = "5min",
+        min_signals: int = 2,
+    ) -> pd.DataFrame:
+        """Find anomalies that co-occur across multiple signals within a time window.
+
+        Args:
+            signal_uuids: List of signal UUIDs to analyze.
+            z_threshold: Z-score threshold for anomaly detection per signal.
+            coincidence_window: Time window for considering anomalies coincident.
+            min_signals: Minimum number of signals with anomalies to flag.
+
+        Returns:
+            DataFrame: window_start, window_end, uuid, is_delta,
+                       anomaly_count, signal_uuids_involved
+        """
+        all_anomalies = []
+        for uid in signal_uuids:
+            anom = self._detect_signal_anomalies(uid, z_threshold=z_threshold)
+            if not anom.empty:
+                all_anomalies.append(anom)
+
+        if not all_anomalies:
+            return pd.DataFrame(
+                columns=[
+                    "window_start", "window_end", "uuid", "is_delta",
+                    "anomaly_count", "signal_uuids_involved",
+                ]
+            )
+
+        combined = pd.concat(all_anomalies, ignore_index=True)
+        combined = combined.sort_values(self.time_column)
+
+        window_td = pd.to_timedelta(coincidence_window)
+        rows: List[Dict[str, Any]] = []
+        processed = set()
+
+        for i, row in combined.iterrows():
+            if i in processed:
+                continue
+            t = row[self.time_column]
+            window_mask = (
+                (combined[self.time_column] >= t)
+                & (combined[self.time_column] <= t + window_td)
+            )
+            window_data = combined[window_mask]
+            unique_signals = window_data["uuid"].unique()
+
+            if len(unique_signals) >= min_signals:
+                rows.append(
+                    {
+                        "window_start": t,
+                        "window_end": t + window_td,
+                        "uuid": self.event_uuid,
+                        "is_delta": True,
+                        "anomaly_count": len(window_data),
+                        "signal_uuids_involved": ",".join(sorted(unique_signals)),
+                    }
+                )
+                processed.update(window_data.index.tolist())
+
+        return pd.DataFrame(rows)
+
+    def cascade_detection(
+        self,
+        leader_uuid: str,
+        follower_uuid: str,
+        *,
+        z_threshold: float = 3.0,
+        max_delay: str = "10min",
+    ) -> pd.DataFrame:
+        """Detect anomaly cascades: leader anomaly followed by follower anomaly.
+
+        Identifies cases where an anomaly in signal A is followed by an
+        anomaly in signal B within the max_delay window.
+
+        Args:
+            leader_uuid: UUID of the leading signal.
+            follower_uuid: UUID of the following signal.
+            z_threshold: Z-score threshold for anomaly detection.
+            max_delay: Maximum time between leader and follower anomaly.
+
+        Returns:
+            DataFrame: leader_time, follower_time, uuid, is_delta,
+                       leader_uuid, follower_uuid, delay_seconds
+        """
+        leader_anom = self._detect_signal_anomalies(leader_uuid, z_threshold=z_threshold)
+        follower_anom = self._detect_signal_anomalies(follower_uuid, z_threshold=z_threshold)
+
+        if leader_anom.empty or follower_anom.empty:
+            return pd.DataFrame(
+                columns=[
+                    "leader_time", "follower_time", "uuid", "is_delta",
+                    "leader_uuid", "follower_uuid", "delay_seconds",
+                ]
+            )
+
+        max_delay_td = pd.to_timedelta(max_delay)
+        rows: List[Dict[str, Any]] = []
+        used_followers = set()
+
+        for _, lrow in leader_anom.iterrows():
+            lt = lrow[self.time_column]
+            candidates = follower_anom[
+                (follower_anom[self.time_column] > lt)
+                & (follower_anom[self.time_column] <= lt + max_delay_td)
+            ]
+            for fidx, frow in candidates.iterrows():
+                if fidx not in used_followers:
+                    rows.append(
+                        {
+                            "leader_time": lt,
+                            "follower_time": frow[self.time_column],
+                            "uuid": self.event_uuid,
+                            "is_delta": True,
+                            "leader_uuid": leader_uuid,
+                            "follower_uuid": follower_uuid,
+                            "delay_seconds": (
+                                frow[self.time_column] - lt
+                            ).total_seconds(),
+                        }
+                    )
+                    used_followers.add(fidx)
+                    break  # one follower per leader
+
+        return pd.DataFrame(rows)
+
+    def root_cause_ranking(
+        self,
+        signal_uuids: List[str],
+        *,
+        z_threshold: float = 3.0,
+        max_delay: str = "10min",
+    ) -> pd.DataFrame:
+        """Rank signals by how often their anomalies precede others.
+
+        For each pair of signals, counts how many times signal A's anomaly
+        precedes signal B's anomaly within max_delay. Signals that frequently
+        lead are potential root causes.
+
+        Args:
+            signal_uuids: List of signal UUIDs.
+            z_threshold: Z-score threshold.
+            max_delay: Maximum delay for cascade detection.
+
+        Returns:
+            DataFrame: signal_uuid, leader_count, follower_count,
+                       leader_ratio, rank
+        """
+        if len(signal_uuids) < 2:
+            return pd.DataFrame(
+                columns=["signal_uuid", "leader_count", "follower_count", "leader_ratio", "rank"]
+            )
+
+        leader_counts: Dict[str, int] = {uid: 0 for uid in signal_uuids}
+        follower_counts: Dict[str, int] = {uid: 0 for uid in signal_uuids}
+
+        for i, uid_a in enumerate(signal_uuids):
+            for uid_b in signal_uuids[i + 1 :]:
+                cascades_ab = self.cascade_detection(
+                    uid_a, uid_b, z_threshold=z_threshold, max_delay=max_delay
+                )
+                cascades_ba = self.cascade_detection(
+                    uid_b, uid_a, z_threshold=z_threshold, max_delay=max_delay
+                )
+                leader_counts[uid_a] += len(cascades_ab)
+                follower_counts[uid_b] += len(cascades_ab)
+                leader_counts[uid_b] += len(cascades_ba)
+                follower_counts[uid_a] += len(cascades_ba)
+
+        rows = []
+        for uid in signal_uuids:
+            total = leader_counts[uid] + follower_counts[uid]
+            rows.append(
+                {
+                    "signal_uuid": uid,
+                    "leader_count": leader_counts[uid],
+                    "follower_count": follower_counts[uid],
+                    "leader_ratio": leader_counts[uid] / total if total > 0 else 0.0,
+                }
+            )
+
+        result = pd.DataFrame(rows)
+        result = result.sort_values("leader_ratio", ascending=False).reset_index(drop=True)
+        result["rank"] = range(1, len(result) + 1)
+        return result

ts_shape/events/correlation/signal_correlation.py

@@ -0,0 +1,213 @@
+import pandas as pd  # type: ignore
+import numpy as np  # type: ignore
+from typing import List, Dict, Any, Optional
+
+from ts_shape.utils.base import Base
+
+
+class SignalCorrelationEvents(Base):
+    """Correlation: Signal Correlation Analysis
+
+    Analyze time-windowed correlations between pairs of numeric signals.
+    Useful for detecting when normally correlated process variables diverge.
+
+    Methods:
+    - rolling_correlation: Pearson correlation over rolling windows.
+    - correlation_breakdown: Detect periods where correlation drops below threshold.
+    - lag_correlation: Cross-correlation with time lag to find delayed relationships.
+    """
+
+    def __init__(
+        self,
+        dataframe: pd.DataFrame,
+        *,
+        event_uuid: str = "corr:signal",
+        value_column: str = "value_double",
+        time_column: str = "systime",
+    ) -> None:
+        super().__init__(dataframe, column_name=time_column)
+        self.event_uuid = event_uuid
+        self.value_column = value_column
+        self.time_column = time_column
+
+    def _align_signals(
+        self, uuid_a: str, uuid_b: str, resample: str = "1min"
+    ) -> pd.DataFrame:
+        """Align two signals on a common time index via resampling."""
+        a = (
+            self.dataframe[self.dataframe["uuid"] == uuid_a]
+            .copy()
+            .sort_values(self.time_column)
+        )
+        b = (
+            self.dataframe[self.dataframe["uuid"] == uuid_b]
+            .copy()
+            .sort_values(self.time_column)
+        )
+
+        if a.empty or b.empty:
+            return pd.DataFrame(columns=["signal_a", "signal_b"])
+
+        a[self.time_column] = pd.to_datetime(a[self.time_column])
+        b[self.time_column] = pd.to_datetime(b[self.time_column])
+
+        a = a.set_index(self.time_column)[self.value_column].resample(resample).mean()
+        b = b.set_index(self.time_column)[self.value_column].resample(resample).mean()
+
+        aligned = pd.DataFrame({"signal_a": a, "signal_b": b}).dropna()
+        return aligned
+
+    def rolling_correlation(
+        self,
+        uuid_a: str,
+        uuid_b: str,
+        *,
+        resample: str = "1min",
+        window: int = 60,
+    ) -> pd.DataFrame:
+        """Compute rolling Pearson correlation between two signals.
+
+        Args:
+            uuid_a: UUID of first signal.
+            uuid_b: UUID of second signal.
+            resample: Resample interval for alignment.
+            window: Rolling window size (in resampled periods).
+
+        Returns:
+            DataFrame: systime, uuid, source_uuid_a, source_uuid_b,
+                       is_delta, correlation
+        """
+        aligned = self._align_signals(uuid_a, uuid_b, resample=resample)
+        if aligned.empty or len(aligned) < window:
+            return pd.DataFrame(
+                columns=[
+                    "systime", "uuid", "source_uuid_a", "source_uuid_b",
+                    "is_delta", "correlation",
+                ]
+            )
+
+        corr = aligned["signal_a"].rolling(window=window, min_periods=max(2, window // 2)).corr(
+            aligned["signal_b"]
+        )
+        out = pd.DataFrame(
+            {
+                "systime": aligned.index,
+                "uuid": self.event_uuid,
+                "source_uuid_a": uuid_a,
+                "source_uuid_b": uuid_b,
+                "is_delta": True,
+                "correlation": corr.values,
+            }
+        ).dropna(subset=["correlation"])
+
+        return out.reset_index(drop=True)
+
+    def correlation_breakdown(
+        self,
+        uuid_a: str,
+        uuid_b: str,
+        *,
+        resample: str = "1min",
+        window: int = 60,
+        threshold: float = 0.5,
+    ) -> pd.DataFrame:
+        """Detect periods where correlation drops below a threshold.
+
+        Returns intervals where previously correlated signals diverge,
+        which may indicate process issues.
+
+        Args:
+            uuid_a: UUID of first signal.
+            uuid_b: UUID of second signal.
+            resample: Resample interval for alignment.
+            window: Rolling window size.
+            threshold: Correlation threshold below which to flag.
+
+        Returns:
+            DataFrame: start, end, uuid, source_uuid_a, source_uuid_b,
+                       is_delta, min_correlation, duration_seconds
+        """
+        corr_df = self.rolling_correlation(
+            uuid_a, uuid_b, resample=resample, window=window
+        )
+        if corr_df.empty:
+            return pd.DataFrame(
+                columns=[
+                    "start", "end", "uuid", "source_uuid_a", "source_uuid_b",
+                    "is_delta", "min_correlation", "duration_seconds",
+                ]
+            )
+
+        corr_df["below"] = corr_df["correlation"] < threshold
+        corr_df["group"] = (corr_df["below"] != corr_df["below"].shift()).cumsum()
+
+        breakdowns = corr_df[corr_df["below"]].groupby("group")
+        rows: List[Dict[str, Any]] = []
+        for _, grp in breakdowns:
+            rows.append(
+                {
+                    "start": grp["systime"].iloc[0],
+                    "end": grp["systime"].iloc[-1],
+                    "uuid": self.event_uuid,
+                    "source_uuid_a": uuid_a,
+                    "source_uuid_b": uuid_b,
+                    "is_delta": True,
+                    "min_correlation": grp["correlation"].min(),
+                    "duration_seconds": (
+                        grp["systime"].iloc[-1] - grp["systime"].iloc[0]
+                    ).total_seconds(),
+                }
+            )
+
+        return pd.DataFrame(rows)
+
+    def lag_correlation(
+        self,
+        uuid_a: str,
+        uuid_b: str,
+        *,
+        resample: str = "1min",
+        max_lag: int = 30,
+    ) -> pd.DataFrame:
+        """Cross-correlation with time lag analysis.
+
+        Finds the time lag at which two signals are most correlated.
+
+        Args:
+            uuid_a: UUID of first signal (reference).
+            uuid_b: UUID of second signal (lagged).
+            resample: Resample interval for alignment.
+            max_lag: Maximum lag periods to test (in both directions).
+
+        Returns:
+            DataFrame: lag_periods, correlation, is_best_lag
+        """
+        aligned = self._align_signals(uuid_a, uuid_b, resample=resample)
+        if aligned.empty or len(aligned) < max_lag * 2:
+            return pd.DataFrame(columns=["lag_periods", "correlation", "is_best_lag"])
+
+        a = aligned["signal_a"].values
+        b = aligned["signal_b"].values
+        n = len(a)
+
+        rows: List[Dict[str, Any]] = []
+        for lag in range(-max_lag, max_lag + 1):
+            if lag < 0:
+                corr = np.corrcoef(a[:lag], b[-lag:])[0, 1]
+            elif lag > 0:
+                corr = np.corrcoef(a[lag:], b[:n - lag])[0, 1]
+            else:
+                corr = np.corrcoef(a, b)[0, 1]
+
+            if not np.isnan(corr):
+                rows.append({"lag_periods": lag, "correlation": corr})
+
+        result = pd.DataFrame(rows)
+        if result.empty:
+            return pd.DataFrame(columns=["lag_periods", "correlation", "is_best_lag"])
+
+        best_idx = result["correlation"].abs().idxmax()
+        result["is_best_lag"] = False
+        result.loc[best_idx, "is_best_lag"] = True
+
+        return result

ts_shape/events/energy/__init__.py

@@ -0,0 +1,27 @@
+"""Energy Events
+
+Detectors for energy-related patterns: consumption analysis, efficiency
+tracking, and peak demand detection on manufacturing/industrial IoT time
+series data.
+
+Classes:
+- EnergyConsumptionEvents: Analyze energy consumption patterns.
+  - consumption_by_window: Aggregate energy consumption per time window.
+  - peak_demand_detection: Detect peak demand periods exceeding thresholds.
+  - consumption_baseline_deviation: Compare actual vs baseline consumption.
+  - energy_per_unit: Calculate energy consumption per production unit.
+
+- EnergyEfficiencyEvents: Track energy efficiency metrics.
+  - efficiency_trend: Rolling efficiency metric over time.
+  - idle_energy_waste: Detect energy consumption during idle periods.
+  - specific_energy_consumption: Energy per unit output over time.
+  - efficiency_comparison: Compare efficiency across shifts or periods.
+"""
+
+from .consumption_analysis import EnergyConsumptionEvents
+from .efficiency_tracking import EnergyEfficiencyEvents
+
+__all__ = [
+    "EnergyConsumptionEvents",
+    "EnergyEfficiencyEvents",
+]