continuous_process_alignment

continuous_process_alignment ¤

Continuous-process alignment: transport-lag compensation for multi-station lines.

ContinuousProcessAlignmentEvents ¤

ContinuousProcessAlignmentEvents(
    dataframe: DataFrame,
    speed_uuid: str,
    line_config: list[dict],
    *,
    ref_uuid: str | None = None,
    cut_uuid: str | None = None,
    time_column: str = "systime",
    uuid_column: str = "uuid",
    value_column: str = "value_double",
    speed_unit: str = "m/min",
    min_speed: float = 0.01
)

Bases: Base

Align multi-station readings on a continuous production line.

Readings are shifted to a common material reference time via speed-based transport lag compensation.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Long-format DataFrame with `time_column`, `uuid_column`, and signal value columns. All UUIDs (speed, stations, cut signals) share the same DataFrame.	required
`speed_uuid`	`str`	UUID of the line-speed signal.	required
`line_config`	`list[dict]`	Physical layout description — list of dicts with keys `name` (str), `offset` (float, meters from reference), and `uuids` (list[str]).	required
`ref_uuid`	`str \| None`	Deprecated; has no effect and will be removed in the next major release (passing it emits a DeprecationWarning). Put a reference-point signal into `line_config` with `offset` 0 instead.	`None`
`cut_uuid`	`str \| None`	Optional UUID whose values carry the cut piece length in meters. Used by `segment_by_cut` as the default `cut_length_uuid`.	`None`
`time_column`	`str`	Name of the timestamp column (default `"systime"`).	`'systime'`
`uuid_column`	`str`	Name of the UUID/identifier column (default `"uuid"`).	`'uuid'`
`value_column`	`str`	Value column of the speed signal, and the default station value column when no override is supplied to a method (default `"value_double"`).	`'value_double'`
`speed_unit`	`str`	Unit of the speed signal. One of `"m/min"`, `"m/s"`, `"mm/s"`.	`'m/min'`
`min_speed`	`float`	Minimum speed in m/s used to clamp the speed before computing lag, preventing infinite lag at standstill (default `0.01`).	`0.01`

Raises:

Type	Description
`ValueError`	If `speed_unit` is not one of the supported units.

align_to_reference ¤

align_to_reference(
    station_uuids: list[str] | None = None,
    *,
    value_column: str | None = None
) -> pd.DataFrame

Shift each station reading backward by its transport lag.

This produces a common material_ref_time for all stations: systime - offset / speed, with the most recent valid speed reading at each station sample (missing speed values are skipped; samples before the first speed reading use the first one), clamped to at least min_speed.

Parameters:

Name	Type	Description	Default
`station_uuids`	`list[str] \| None`	Subset of UUIDs to process. Defaults to all UUIDs in `line_config`.	`None`
`value_column`	`str \| None`	Value column to carry through. Defaults to the constructor `value_column`.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with columns `material_ref_time`, `systime`, `uuid`, `component`, `position_offset_m`, `lag_seconds`, and `<value_column>`.

segment_by_cut ¤

segment_by_cut(
    aligned_df: DataFrame,
    *,
    cut_length_uuid: str | None = None,
    part_counter_uuid: str | None = None,
    value_column_cut: str = "value_double",
    handle_resets: bool = True
) -> pd.DataFrame

Add piece columns to the output of align_to_reference.

Adds piece_id, piece_length_m, and piece_cut_ref_time to aligned_df.

Cut-event detection strategies (in priority order):

part_counter_uuid (boolean): each True row = 1 cut.
part_counter_uuid (integer/float): each step where the counter increases by delta counts as delta cuts, all attributed to the same timestamp when the signal resolution is coarser than the cut rate. The first reading is the baseline; missing readings are gaps.
cut_length_uuid only: each row of the length signal = 1 cut.

Each cut time is shifted back to the reference point by the cutter's own transport lag (when the cutter's uuid is in line_config), the same way align_to_reference shifts station readings.

Piece assignment: a cut finishes the piece whose material passed the reference point since the previous cut. Rows with material_ref_time in (previous cut, this cut] get this cut's piece_id; rows up to and including the first cut belong to piece 1; rows after the last cut are not cut yet and get piece_id , piece_length_m NaN and piece_cut_ref_time NaT. Pieces cut at the same instant (a counter step > 1) share one boundary, so the material goes to the first of them and the others have no rows.

Parameters:

Name	Type	Description	Default
`aligned_df`	`DataFrame`	Output of `align_to_reference`.	required
`cut_length_uuid`	`str \| None`	UUID carrying the cut piece length value. Defaults to the constructor `cut_uuid` when None.	`None`
`part_counter_uuid`	`str \| None`	UUID of a part-counter signal (boolean or monotonically increasing integer).	`None`
`value_column_cut`	`str`	Column holding the length value in `cut_length_uuid` rows. With a counter, each cut takes the latest length reported at or before it.	`'value_double'`
`handle_resets`	`bool`	When True (default) and a numeric `part_counter_uuid` is used, a decreasing counter (a reset at a shift/part change or PLC restart) is treated as new production: the post-reset counter value is emitted as that many cut events instead of being skipped. When False, a reset's negative delta is ignored and its post-reset pieces are not counted.	`True`

Returns:

Type	Description
`DataFrame`	`aligned_df` augmented with `piece_id` (nullable `Int64`, 1-based, numbered in cut order), `piece_length_m` (float or NaN), and `piece_cut_ref_time` (the piece's cut at the reference point, in the data's time zone).

Raises:

Type	Description
`ValueError`	If neither `cut_length_uuid` (nor the constructor `cut_uuid`) nor `part_counter_uuid` is given.

lag_profile ¤

lag_profile(
    station_uuids: list[str] | None = None,
    *,
    window: str = "1min"
) -> pd.DataFrame

Compute per-window mean lag for each station.

Parameters:

Name	Type	Description	Default
`station_uuids`	`list[str] \| None`	Subset of UUIDs to process. Defaults to all UUIDs in `line_config`.	`None`
`window`	`str`	Pandas resample frequency for the speed averaging window (default `"1min"`).	`'1min'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns `start`, `uuid`, `component`, `position_offset_m`, `mean_speed_m_s`, and `lag_seconds`. Windows without speed readings have NaN speed and lag.

alignment_quality ¤

alignment_quality(
    station_uuids: list[str] | None = None,
    *,
    window: str = "1h"
) -> pd.DataFrame

Coverage check: sample counts per window for speed and each station.

Parameters:

Name	Type	Description	Default
`station_uuids`	`list[str] \| None`	Subset of UUIDs to check. Defaults to all UUIDs in `line_config`.	`None`
`window`	`str`	Pandas resample frequency for the counting window (default `"1h"`).	`'1h'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns `start`, `speed_sample_count`, `has_speed_data`, `has_full_coverage`, and `per_uuid_counts`.