Skip to content

Index

correlation ¤

Correlation Events

Cross-signal correlation analysis for detecting related anomalies and patterns across multiple timeseries signals.

  • 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.

  • RootCauseCorrelationEvents: Rank candidate causes for events another detector already found (directed, event-driven analysis).

  • rank_causes: Ranked causal candidates with lead time and p-value.
  • top_cause: Single-row verdict naming the best-supported candidate.
  • lag_profile: Correlation-vs-lag curve for one candidate signal.

AnomalyCorrelationEvents ¤

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

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

coincident_anomalies ¤

coincident_anomalies(
    signal_uuids: list[str],
    *,
    n_sigma: 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.

Parameters:

Name Type Description Default
signal_uuids list[str]

List of signal UUIDs to analyze.

 required
n_sigma float

Z-score threshold for anomaly detection per signal.

 3.0
coincidence_window str

Time window for considering anomalies coincident.

 '5min'
min_signals int

Minimum number of signals with anomalies to flag.

 2

Returns:

Name Type Description
DataFrame DataFrame

systime, start, end, uuid, source_uuid, is_delta, anomaly_count, signal_uuids_involved. systime is the first anomaly of the group (= start) and source_uuid the comma-joined involved signals. Empty (same columns) when nothing coincides.

cascade_detection ¤

cascade_detection(
    leader_uuid: str,
    follower_uuid: str,
    *,
    n_sigma: 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.

Parameters:

Name Type Description Default
leader_uuid str

UUID of the leading signal.

 required
follower_uuid str

UUID of the following signal.

 required
n_sigma float

Z-score threshold for anomaly detection.

 3.0
max_delay str

Maximum time between leader and follower anomaly.

 '10min'

Returns:

Name Type Description
DataFrame DataFrame

systime, leader_time, follower_time, uuid, source_uuid, is_delta, leader_uuid, follower_uuid, delay_seconds. systime is the follower anomaly time; source_uuid is "<leader>,<follower>".

root_cause_ranking ¤

root_cause_ranking(
    signal_uuids: list[str],
    *,
    n_sigma: 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.

Parameters:

Name Type Description Default
signal_uuids list[str]

List of signal UUIDs.

 required
n_sigma float

Z-score threshold.

 3.0
max_delay str

Maximum delay for cascade detection.

 '10min'

Returns:

Name Type Description
DataFrame DataFrame

signal_uuid, leader_count, follower_count, leader_ratio, rank

RootCauseCorrelationEvents ¤

RootCauseCorrelationEvents(
    dataframe: DataFrame,
    *,
    event_uuid: str = "corr:root_cause",
    value_column: str = "value_double",
    time_column: str = "systime",
    uuid_column: str = "uuid"
)

Bases: Base

Correlation: rank candidate causes for a set of detected events.

trigger_events is any detector's output — the onset timestamp is read from systime (point events) or start (interval/summary events)::

stops = LongDowntimeEvents(df, ...).detect_long_downtime(min_gap="10min")
rc = RootCauseCorrelationEvents(df)
rc.rank_causes(stops, ["temp:spindle", "press:hydraulic", "flow:coolant"])

Methods: - rank_causes: Ranked causal candidates with lag and p-value. - top_cause: Single-row verdict naming the best-supported candidate. - lag_profile: Correlation-vs-lag curve for one candidate signal.

Initialize the root-cause ranker.

Parameters:

Name Type Description Default
dataframe DataFrame

Timeseries frame holding the candidate signals.

 required
event_uuid str

UUID stamped on emitted rows.

 'corr:root_cause'
value_column str

Column holding the numeric readings.

 'value_double'
time_column str

Timestamp column.

 'systime'
uuid_column str

Column identifying the signal.

 'uuid'

rank_causes ¤

rank_causes(
    trigger_events: DataFrame,
    candidate_uuids: list[str],
    *,
    window: str = "1min",
    max_lag: int = 30,
    p_threshold: float = 0.05,
    trigger_uuid: str | None = None,
    trigger_event_type: str | None = None,
    only_significant: bool = False
) -> pd.DataFrame

Rank candidate signals by how strongly they lead the trigger events.

Parameters:

Name Type Description Default
trigger_events DataFrame

Event frame whose onsets are being explained.

 required
candidate_uuids list[str]

Signals to test as possible causes.

 required
window str

Grid resolution (offset string); also the unit of max_lag.

 '1min'
max_lag int

Largest lead tested, in window periods.

 30
p_threshold float

Bonferroni-corrected p-value at or below which a candidate is marked significant.

 0.05
trigger_uuid str | None

Identifier of the triggering signal, for the audit trail. Defaults to the source_uuid carried by trigger_events when it has one.

 None
trigger_event_type str | None

Label of the triggering event. Defaults to the uuid carried by trigger_events when it has one.

 None
only_significant bool

Drop candidates above p_threshold.

 False

Returns:

Type Description
DataFrame

Static-shape DataFrame, ranked by absolute correlation:
DataFrame

uuid, trigger_event_type, trigger_uuid,
DataFrame

candidate_uuid, correlation_coefficient, lag_seconds,
DataFrame

p_value (raw, at the winning lag), p_value_adjusted
DataFrame

(Bonferroni over the lag scan), significant, sample_count,
DataFrame

trigger_count, rank, method.

top_cause ¤

top_cause(
    trigger_events: DataFrame,
    candidate_uuids: list[str],
    *,
    window: str = "1min",
    max_lag: int = 30,
    p_threshold: float = 0.05,
    trigger_uuid: str | None = None,
    trigger_event_type: str | None = None
) -> pd.DataFrame

Name the best-supported cause, or report that none qualifies.

Only significant candidates are eligible: when no candidate clears p_threshold the row still comes back — with top_cause_uuid set to None and the tested counts filled in — so a search that found nothing is visible rather than silently empty.

Parameters:

Name Type Description Default
trigger_events DataFrame

Event frame whose onsets are being explained.

 required
candidate_uuids list[str]

Signals to test as possible causes.

 required
window str

Grid resolution (offset string); also the unit of max_lag.

 '1min'
max_lag int

Largest lead tested, in window periods.

 30
p_threshold float

Significance level for eligibility.

 0.05
trigger_uuid str | None

See :meth:rank_causes.

 None
trigger_event_type str | None

See :meth:rank_causes.

 None

Returns:

Type Description
DataFrame

Static-shape DataFrame with a single row: uuid,
DataFrame

trigger_event_type, trigger_uuid, top_cause_uuid,
DataFrame

top_cause_lag_seconds, top_cause_correlation, p_value,
DataFrame

p_value_adjusted, confidence, candidates_tested,
DataFrame

candidates_significant, trigger_count, method.

lag_profile ¤

lag_profile(
    trigger_events: DataFrame,
    candidate_uuid: str,
    *,
    window: str = "1min",
    max_lag: int = 30
) -> pd.DataFrame

Correlation against the trigger onsets at every tested lag.

The curve is the diagnostic behind :meth:rank_causes: a genuine cause peaks at one lead time and falls away, while a spurious match tends to wander without a clear peak. p_value here is the raw per-lag value — the whole point of the profile is to see every lag, so no multiple-comparison correction is applied; use :meth:rank_causes for the corrected verdict.

Parameters:

Name Type Description Default
trigger_events DataFrame

Event frame whose onsets are being explained.

 required
candidate_uuid str

The signal to profile.

 required
window str

Grid resolution (offset string); also the unit of max_lag.

 '1min'
max_lag int

Largest lead tested, in window periods.

 30

Returns:

Type Description
DataFrame

Static-shape DataFrame, one row per lag: uuid,
DataFrame

candidate_uuid, lag_seconds, correlation,
DataFrame

p_value, sample_count, is_best_lag, method.

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