signal_correlation

signal_correlation ¤

SignalCorrelationEvents ¤

SignalCorrelationEvents(
    dataframe: DataFrame,
    *,
    event_uuid: str = "corr:signal",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: 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.

rolling_correlation ¤

rolling_correlation(
    signal_uuid_a: str,
    signal_uuid_b: str,
    *,
    window: str = "1min",
    window_size: int = 60
) -> pd.DataFrame

Compute rolling Pearson correlation between two signals.

Parameters:

Name	Type	Description	Default
`signal_uuid_a`	`str`	UUID of first signal.	required
`signal_uuid_b`	`str`	UUID of second signal.	required
`window`	`str`	Resample interval for alignment (offset string).	`'1min'`
`window_size`	`int`	Rolling window size, in resampled periods (rows).	`60`

Returns:

Name	Type	Description
`DataFrame`	`DataFrame`	systime, uuid, source_uuid, source_uuid_a, source_uuid_b, is_delta, correlation. `source_uuid` is `"<signal_uuid_a>,<signal_uuid_b>"`.

correlation_breakdown ¤

correlation_breakdown(
    signal_uuid_a: str,
    signal_uuid_b: str,
    *,
    window: str = "1min",
    window_size: int = 60,
    threshold: float = 0.5,
    interval_end: str = "next_change"
) -> pd.DataFrame

Detect periods where correlation drops below a threshold.

Returns intervals where previously correlated signals diverge, which may indicate process issues.

Parameters:

Name	Type	Description	Default
`signal_uuid_a`	`str`	UUID of first signal.	required
`signal_uuid_b`	`str`	UUID of second signal.	required
`window`	`str`	Resample interval for alignment (offset string).	`'1min'`
`window_size`	`int`	Rolling window size, in resampled periods (rows).	`60`
`threshold`	`float`	Correlation threshold below which to flag.	`0.5`
`interval_end`	`str`	`"next_change"` (default) ends an interval at the next sample (the transition), so the interval spans the time the condition held and change-encoded signals -- one row per change -- keep their duration. `"last_sample"` ends it at its last flagged sample. See :func:`ts_shape.utils.intervals.interval_end_times`.	`'next_change'`

Returns:

Name	Type	Description
`DataFrame`	`DataFrame`	start, end, uuid, source_uuid_a, source_uuid_b, is_delta, min_correlation, duration_seconds. Empty (same columns) when no breakdown is found.

lag_correlation ¤

lag_correlation(
    signal_uuid_a: str,
    signal_uuid_b: str,
    *,
    window: 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.

Sign convention: lag_periods = k correlates a[t] with b[t - k] (b shifted forward by k grid periods). A positive best lag means b leads a (a follows b by k periods); a negative best lag means b lags a. For example, b(t) = a(t - 5) (b delayed by 5 periods) gives a best lag of -5.

Parameters:

Name	Type	Description	Default
`signal_uuid_a`	`str`	UUID of first signal (reference).	required
`signal_uuid_b`	`str`	UUID of second signal, shifted against the reference.	required
`window`	`str`	Resample interval for alignment (offset string).	`'1min'`
`max_lag`	`int`	Maximum lag periods to test (in both directions).	`30`

Returns:

Name	Type	Description
`DataFrame`	`DataFrame`	lag_periods, correlation, is_best_lag