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",
    interval_end: str = "next_change",
    data_end: Timestamp | None = None
)

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

Initialize the duty-cycle analyzer.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Long-format input data.	required
`signal_uuid`	`str`	UUID of the boolean on/off signal (True = on).	required
`event_uuid`	`str`	UUID assigned to generated events.	`'prod:duty_cycle'`
`value_column`	`str`	Column holding the on/off state. Missing values count as off.	`'value_bool'`
`time_column`	`str`	Timestamp column.	`'systime'`
`interval_end`	`str`	How on/off intervals are closed. `"next_change"` (default) closes each interval at the next transition, which measures both dense and change-encoded (`is_delta`) signals. `"last_sample"` ends each interval at its last sample; on a change-encoded signal (one row per transition) every on/off interval then has zero duration.	`'next_change'`
`data_end`	`Timestamp \| None`	Optional bound for the final, still-open interval when `interval_end="next_change"`.	`None`

on_off_intervals ¤

on_off_intervals(
    *, max_gap: str | Timedelta | None = None
) -> pd.DataFrame

List every on and off interval with duration.

Parameters:

Name	Type	Description	Default
`max_gap`	`str \| Timedelta \| None`	Longest time between two samples an interval may span (e.g. `"15min"`). A longer gap is "no data": the interval before it ends at its last sample and a new interval starts after the gap, even if the state is unchanged. `None` (default): no limit.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds (float),
`DataFrame`	uuid (event uuid), source_uuid (signal uuid), state (on/off),
`DataFrame`	duration (Timedelta).

duty_cycle_by_window ¤

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

Percentage of time the signal is True per window.

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window.	`'1h'`
`time_weighted`	`bool`	When True (default), each sample is weighted by the gap to the next sample, so the duty cycle reflects wall-clock on-time on change-encoded and irregularly sampled signals; `on_time` and `off_time` are the covered seconds in the window. When False, the duty cycle is the mean of the boolean samples in the window, which equals the time share only under uniform sampling (`On@09:00, Off@09:59` reads 50 %).	`True`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end (start + window),
`DataFrame`	duration_seconds, uuid, source_uuid, on_time, off_time,
`DataFrame`	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: start, end (start + window),
`DataFrame`	duration_seconds, uuid, source_uuid, on_count, off_count,
`DataFrame`	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: start, end (start + window),
`DataFrame`	duration_seconds, uuid, source_uuid, transition_count,
`DataFrame`	avg_on_duration, avg_off_duration.