duty_cycle

duty_cycle

DutyCycleEvents

DutyCycleEvents(
    dataframe: DataFrame,
    signal_uuid: str,
    *,
    event_uuid: str = "prod:duty_cycle",
    value_column: str = "value_bool",
    time_column: str = "systime"
)

Bases: Base

Production: Duty Cycle Analysis

Analyze on/off patterns from a boolean signal: duty cycle percentage, interval listing, transition counts, and excessive cycling detection.

Methods: - duty_cycle_per_window: On-time percentage per time window. - on_off_intervals: List every on and off interval with duration. - cycle_count: Number of on/off transitions per window. - excessive_cycling: Flag windows with too many transitions.

on_off_intervals

on_off_intervals() -> pd.DataFrame

List every on and off interval with duration.

Returns:

Type	Description
DataFrame	DataFrame with columns: start_time, end_time, state (on/off), duration.

duty_cycle_per_window

duty_cycle_per_window(window: str = '1h') -> pd.DataFrame

Percentage of time the signal is True per window.

Parameters:

Name	Type	Description	Default
window	str	Resample window.	'1h'

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, on_time, off_time, duty_cycle_pct.

cycle_count

cycle_count(window: str = '1h') -> pd.DataFrame

Number of on/off transitions per window.

Parameters:

Name	Type	Description	Default
window	str	Resample window.	'1h'

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, on_count, off_count, total_transitions.

excessive_cycling

excessive_cycling(
    max_transitions: int = 20, window: str = "1h"
) -> pd.DataFrame

Flag windows where transition count exceeds threshold.

Excessive cycling indicates hunting, instability, or wear risk.

Parameters:

Name	Type	Description	Default
max_transitions	int	Threshold for flagging.	20
window	str	Resample window.	'1h'

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, transition_count,
DataFrame	avg_on_duration, avg_off_duration.