segment_extractor

segment_extractor ¤

SegmentExtractor ¤

SegmentExtractor(
    dataframe: DataFrame, time_column: str = "systime"
)

Bases: Base

Extract time ranges from a categorical signal that changes over time.

Given a signal UUID (e.g. order number or part number) whose value changes over time, detects transitions and produces one row per contiguous segment with its start time, end time, and active value.

Methods: - extract_time_ranges: Detect value changes and return time range segments.

extract_time_ranges `classmethod` ¤

extract_time_ranges(
    dataframe: DataFrame,
    segment_uuid: str,
    uuid_column: str = "uuid",
    value_column: str = "value_string",
    time_column: str = "systime",
    min_duration: str | None = None,
    interval_end: str = "next_change",
    data_end: Timestamp | str | None = None,
) -> pd.DataFrame

Detect value transitions and extract time ranges per segment.

One row per run of consecutive equal values of segment_uuid: repeated samples of the same value (a re-sent order number) are one segment, and the same value coming back later is a new segment with a new segment_index. The signal is ordered by time (rows with the same timestamp keep their input order).

Missing values (NaN / None / pd.NA) mean "no change": they join the running segment. Missing values before the first real value, and runs whose value is an empty or whitespace-only string ("no order active"), are not segments; with interval_end="next_change" the preceding segment ends where such a run starts. Rows without a timestamp are skipped with a :class:~ts_shape.errors.DataQualityWarning.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Input DataFrame in long format. It may hold every signal; only the `segment_uuid` rows define the segments, and (by default) the last timestamp of the whole frame closes the last segment.	required
`segment_uuid`	`str`	The UUID of the categorical signal to segment by (e.g. 'order_number', 'part_number').	required
`uuid_column`	`str`	Column identifying each timeseries.	`'uuid'`
`value_column`	`str`	Column containing the categorical values. Use 'value_string' for string signals, 'value_integer' for integer signals, etc. Nullable and pyarrow dtypes work.	`'value_string'`
`time_column`	`str`	Column containing timestamps.	`'systime'`
`min_duration`	`str \| None`	Optional minimum segment duration (e.g. '10s', '1min'). Segments shorter than this are dropped (`segment_index` is renumbered 0..n-1 afterwards).	`None`
`interval_end`	`str`	`"next_change"` (default) ends a segment where the next value starts (the transition), so change-encoded signals -- one row per change -- keep their real duration. The last segment is still open at the end of the data and ends at `data_end`. `"last_sample"` ends every segment at its own last sample, which collapses a single-row segment to zero length and leaves the time between segments uncovered.	`'next_change'`
`data_end`	`Timestamp \| str \| None`	End of the last (open) segment with `interval_end="next_change"`. Default: the latest timestamp in `dataframe` over all signals, so the process data recorded after the last change belongs to the last segment. Pass e.g. the end of the query window to close it there. The last segment never ends before its own last sample. A naive value is read in the data's time zone.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame, one row per segment in time order, with columns:
`DataFrame`	segment_value: The active value during this range.
`DataFrame`	segment_start: Start timestamp of the range (first sample).
`DataFrame`	segment_end: End timestamp of the range.
`DataFrame`	segment_duration: Duration as Timedelta.
`DataFrame`	segment_index: Sequential index of the segment (0-based).
`DataFrame`	start, end, duration_seconds: The same range in the canonical interval columns (`duration_seconds` as float).
`DataFrame`	source_uuid: `segment_uuid`.
`DataFrame`	end_inclusive: Whether the sample exactly at `segment_end` belongs to the segment (used by `SegmentProcessor.apply_ranges`). False when the next run starts at that instant; True for the last segment and for every `"last_sample"` segment.
`DataFrame`	Time columns keep the input's time zone. With no segments the
`DataFrame`	frame is empty but has all these columns.

segment_extractor