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 rationalisation and nuisance alarm detection.

Example usage

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

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

Initialize alarm management analyser.

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') -> 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'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	window_start
`DataFrame`	alarm_count
`DataFrame`	uuid
`DataFrame`	source_uuid

alarm_duration_stats ¤

alarm_duration_stats() -> 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 = "10m"
) -> 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).	`'10m'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	window_start
`DataFrame`	window_end
`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