alarm_management

alarm_management ¤

ISA-18.2 style alarm analysis.

Provides alarm frequency, duration statistics, chattering detection, and standing alarm identification from boolean alarm signals.

AlarmManagementEvents ¤

AlarmManagementEvents(
    dataframe: DataFrame,
    alarm_uuid: str,
    *,
    event_uuid: str = "prod:alarm",
    value_column: str = "value_bool",
    time_column: str = "systime"
)

Bases: Base

Analyze alarm signals following ISA-18.2 alarm management principles.

Works with boolean alarm signals where True = alarm active, False = alarm cleared. Provides metrics for alarm rationalization and nuisance alarm detection.

Example usage

alarms = AlarmManagementEvents(df, alarm_uuid='temp_high_alarm')

freq = alarms.alarm_frequency(window='1h') stats = alarms.alarm_duration_statistics() chatter = alarms.chattering_detection(min_transitions=5, window='10min') standing = alarms.standing_alarms(min_duration='1h')

Example

import pandas as pd from ts_shape import AlarmManagementEvents df = pd.DataFrame({ ... "systime": pd.to_datetime([ ... "2025-01-01 08:00", "2025-01-01 08:05", "2025-01-01 08:20", ... "2025-01-01 09:30", "2025-01-01 09:40", "2025-01-01 09:41"]), ... "uuid": "temp_high", ... "value_bool": [True, False, True, False, True, False], ... }) alarms = AlarmManagementEvents(df, "temp_high") alarms.alarm_duration_statistics()[ ... ["alarm_count", "max_duration_seconds", "total_duration_seconds"]] alarm_count max_duration_seconds total_duration_seconds 0 3 4200.0 4560.0 alarms.standing_alarms(min_duration="1h")[["start", "end", "duration_seconds"]] start end duration_seconds 0 2025-01-01 08:20:00 2025-01-01 09:30:00 4200.0

Initialize alarm management analyzer.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Input DataFrame with timeseries data.	required
`alarm_uuid`	`str`	UUID of the alarm signal.	required
`event_uuid`	`str`	UUID to tag derived events with.	`'prod:alarm'`
`value_column`	`str`	Column holding the boolean alarm state.	`'value_bool'`
`time_column`	`str`	Name of timestamp column.	`'systime'`

alarm_frequency ¤

alarm_frequency(
    window: str = "1h", *, include_initial: bool = True
) -> pd.DataFrame

Count alarm activations per time window.

An activation is a transition from False to True.

Parameters:

Name	Type	Description	Default
`window`	`str`	Pandas offset alias for the aggregation window.	`'1h'`
`include_initial`	`bool`	When True (default) an alarm that is already active in the first sample is counted as an activation, because `shift(fill_value=False)` treats the leading True as a rising edge. Pass `False` to ignore an alarm that was raised before the data window began (no real activation occurred inside it).	`True`

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	start: window start
`DataFrame`	end: window end (start + window)
`DataFrame`	duration_seconds: window length in seconds
`DataFrame`	alarm_count
`DataFrame`	uuid
`DataFrame`	source_uuid

alarm_duration_statistics ¤

alarm_duration_statistics() -> pd.DataFrame

Compute min / avg / max / total duration of alarm-ON states.

Returns:

Type	Description
`DataFrame`	DataFrame with a single row containing:
`DataFrame`	source_uuid
`DataFrame`	alarm_count
`DataFrame`	min_duration_seconds
`DataFrame`	avg_duration_seconds
`DataFrame`	max_duration_seconds
`DataFrame`	total_duration_seconds

chattering_detection ¤

chattering_detection(
    min_transitions: int = 5, window: str = "10min"
) -> pd.DataFrame

Detect chattering alarms (too many transitions in a short window).

A chattering alarm is one that toggles on/off rapidly, which is a nuisance and masks real alarms.

Parameters:

Name	Type	Description	Default
`min_transitions`	`int`	Minimum state changes within window to flag.	`5`
`window`	`str`	Rolling window size (Pandas offset alias).	`'10min'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	start
`DataFrame`	end
`DataFrame`	duration_seconds: float seconds (end - start)
`DataFrame`	transition_count
`DataFrame`	uuid
`DataFrame`	source_uuid

standing_alarms ¤

standing_alarms(min_duration: str = '1h') -> pd.DataFrame

Identify alarms that stay active longer than min_duration.

Standing (stale) alarms reduce operator trust and should be investigated for shelving or re-engineering.

Parameters:

Name	Type	Description	Default
`min_duration`	`str`	Minimum ON duration to flag (Pandas offset alias).	`'1h'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	start
`DataFrame`	end
`DataFrame`	duration_seconds
`DataFrame`	uuid
`DataFrame`	source_uuid