micro_stop_detection

micro_stop_detection ¤

MicroStopEvents ¤

MicroStopEvents(
    dataframe: DataFrame,
    run_state_uuid: str,
    *,
    event_uuid: str = "prod:micro_stop",
    value_column: str = "value_bool",
    time_column: str = "systime",
    interval_end: str = "next_change",
    data_end: Timestamp | None = None
)

Bases: Base

Production: Micro-Stop Detection

Detect brief idle intervals that individually seem harmless but accumulate into significant availability losses.

Methods: - detect_micro_stops: Find idle intervals shorter than max_duration. - micro_stop_frequency: Count micro-stops per time window. - micro_stop_impact: Time lost to micro-stops per window. - micro_stop_patterns: Group micro-stops by hour-of-day.

Example

import pandas as pd from ts_shape import MicroStopEvents df = pd.DataFrame({ ... "systime": pd.to_datetime([ ... "2025-01-01 08:00:00", "2025-01-01 08:10:00", "2025-01-01 08:10:20", ... "2025-01-01 08:30:00", "2025-01-01 08:30:45", "2025-01-01 09:00:00"]), ... "uuid": "run", ... "value_bool": [True, False, True, False, True, True], ... }) stops = MicroStopEvents(df, "run").detect_micro_stops(max_duration="30s") stops[["start", "end", "duration_seconds"]] start end duration_seconds 0 2025-01-01 08:10:00 2025-01-01 08:10:20 20.0

The 45 s stop at 08:30 is longer than max_duration and is not listed.

Initialize the micro-stop detector.

Parameters:

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

detect_micro_stops ¤

detect_micro_stops(
    max_duration: str = "30s", min_duration: str = "0s"
) -> pd.DataFrame

Find idle intervals shorter than max_duration.

Parameters:

Name	Type	Description	Default
`max_duration`	`str`	Maximum duration to qualify as a micro-stop.	`'30s'`
`min_duration`	`str`	Minimum duration to include (filter very short glitches).	`'0s'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds (float),
`DataFrame`	uuid (event uuid), source_uuid (run-state uuid), duration
`DataFrame`	(Timedelta), preceding_run_duration.

micro_stop_frequency ¤

micro_stop_frequency(
    window: str = "1h", max_duration: str = "30s"
) -> pd.DataFrame

Count micro-stops per time window.

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window.	`'1h'`
`max_duration`	`str`	Maximum idle duration to qualify as micro-stop.	`'30s'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end (start + window),
`DataFrame`	duration_seconds, uuid, source_uuid, count, total_lost_time,
`DataFrame`	pct_of_window.
`DataFrame`	Canonical twin columns: `share_of_window_pct` (after `pct_of_window`); each
`DataFrame`	holds the same values as the deprecated column right before it, which is
`DataFrame`	removed in the next major release.

micro_stop_impact ¤

micro_stop_impact(
    window: str = "1h", max_duration: str = "30s"
) -> pd.DataFrame

Time lost to micro-stops vs total available time per window.

A stop is classified as a micro-stop by its full duration; its time and the run time are then split at the window boundaries (the ISO 22400-2 time model), so a stop across the hour counts in both hours. Every window from the first interval to the end of the last one is reported (0 when it holds no run or micro-stop time).

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window.	`'1h'`
`max_duration`	`str`	Maximum idle duration to qualify as micro-stop.	`'30s'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end (start + window),
`DataFrame`	duration_seconds, uuid, source_uuid, total_run_time,
`DataFrame`	total_micro_stop_time, performance_loss_pct,
`DataFrame`	availability_loss_pct.
`DataFrame`	`performance_loss_pct` is the micro-stop time as a percentage of
`DataFrame`	run + micro-stop time. Minor stops are a performance loss in
`DataFrame`	Nakajima's six big losses (idling and minor stoppages), not an
`DataFrame`	availability loss. `availability_loss_pct` holds the same value
`DataFrame`	under its original, misleading name and is kept for
`DataFrame`	compatibility.

micro_stop_patterns ¤

micro_stop_patterns(
    hour_grouping: bool = True, max_duration: str = "30s"
) -> pd.DataFrame

Group micro-stops by hour-of-day to find clustering patterns.

Parameters:

Name	Type	Description	Default
`hour_grouping`	`bool`	If True, group by hour. If False, group by shift (8h blocks).	`True`
`max_duration`	`str`	Maximum idle duration to qualify as micro-stop.	`'30s'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: hour (or shift), avg_count, avg_lost_time.