anomaly_correlation

anomaly_correlation

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