cycle_processor

cycle_processor

Assign sample data to cycles and compute per-cycle results.

Boundary rule (used by every method): a sample belongs to a cycle when cycle_start <= systime < cycle_end. The interval is half-open, so with back-to-back cycles a sample at the shared timestamp belongs to the later cycle only, and every sample is counted once. A cycle without an end (cycle_end NaT) gets no samples. Samples with a missing timestamp belong to no cycle. Samples are matched on time only: pass the values of the machine the cycles belong to.

CycleDataProcessor

CycleDataProcessor(
    cycles_df: DataFrame,
    values_df: DataFrame,
    cycle_uuid_column: str = "cycle_uuid",
    time_column: str = "systime",
)

Bases: Base

A class to process cycle-based data and values with optimized performance. Samples are matched to cycles with a sorted search (no per-cycle scans).

Initializes the CycleDataProcessor with cycles and values DataFrames.

Parameters:

Name	Type	Description	Default
cycles_df	DataFrame	DataFrame containing columns 'cycle_start', 'cycle_end', and 'cycle_uuid'.	required
values_df	DataFrame	DataFrame containing the values and timestamps in the 'systime' column.	required
cycle_uuid_column	str	Name of the column representing cycle UUIDs. cycle_uuid_col is the deprecated name.	'cycle_uuid'
time_column	str	Name of the column representing the timestamps for the values. systime_col is the deprecated name.	'systime'

Raises:

Type	Description
ColumnNotFoundError	If a cycle column or the time column is missing.
TypeError	If one of cycles and values is tz-aware and the other naive.

cycle_uuid_col property writable

cycle_uuid_col: str

Deprecated name of :attr:cycle_uuid_column.

systime_col property writable

systime_col: str

Deprecated name of :attr:time_column.

split_by_cycle

split_by_cycle() -> dict[str, pd.DataFrame]

Splits the values DataFrame by cycles defined in the cycles DataFrame.

Returns:

Type	Description
dict[str, DataFrame]	Dictionary where keys are cycle_uuids and values are DataFrames with the corresponding cycle data. Keys are in chronological cycle order; cycles without samples are left out. Rows keep their values_df index and are sorted by time.

merge_dataframes_by_cycle

merge_dataframes_by_cycle() -> pd.DataFrame

Merges the values DataFrame with the cycles DataFrame based on the cycle time intervals.

Returns:

Type	Description
DataFrame	The samples that fall in a cycle, with an added cycle_uuid column, sorted by time (original index kept). Samples in no cycle are dropped. A sample inside two overlapping cycles appears once per cycle. No match: an empty frame with the same columns.

group_by_cycle_uuid

group_by_cycle_uuid(
    dataframe: DataFrame | None = None,
) -> list[pd.DataFrame]

Group the DataFrame by the cycle_uuid column, resulting in a list of DataFrames, each containing data for one cycle.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame | None	DataFrame to be grouped by cycle_uuid. If None, uses merge_dataframes_by_cycle().	None

Returns:

Type	Description
list[DataFrame]	List of DataFrames, one per cycle uuid, in order of first appearance.

split_dataframes_by_group

split_dataframes_by_group(
    dfs: list[DataFrame], group_column: str
) -> list[pd.DataFrame]

Splits a list of DataFrames by groups based on a specified column. This function performs a groupby operation on each DataFrame in the list and then flattens the result.

Parameters:

Name	Type	Description	Default
dfs	list[DataFrame]	List of DataFrames to be split.	required
group_column	str	Column name to group by.	required

Returns:

Type	Description
list[DataFrame]	List of DataFrames, each corresponding to a group in the original DataFrames. Rows whose group_column is missing are left out.

Raises:

Type	Description
ColumnNotFoundError	If one of dfs has no group_column (it was skipped with a log message before).

compute_cycle_statistics

compute_cycle_statistics() -> pd.DataFrame

Compute statistics for each cycle.

Returns:

Type	Description
DataFrame	One row per cycle in cycles_df order: cycle_uuid, cycle_start, cycle_end, duration_seconds, value_count (samples in the cycle), unique_uuids, mean_value_double / std_value_double (when values_df has value_double), and the canonical start, end, sample_count. An open cycle has NaN duration and 0 samples.

compare_cycles

compare_cycles(
    reference_cycle_uuid: str,
    value_column: str = "value_double",
) -> pd.DataFrame

Compare all cycles against a reference cycle.

Parameters:

Name	Type	Description	Default
reference_cycle_uuid	str	UUID of the reference cycle	required
value_column	str	Column holding the values to compare. metric is the deprecated name.	'value_double'

Returns:

Type

Description

DataFrame

One row per cycle with data for value_column (chronological order): cycle_uuid, is_reference, mean_value, std_value, deviation_from_ref (mean minus reference mean), deviation_pct (relative to the reference mean, NaN when it is 0) and variability_ratio (std over reference std, NaN when that is 0 or undefined). Empty (full columns) with a DataQualityWarning when the reference cycle is unknown or has no data.

Raises:

Type	Description
ColumnNotFoundError	If value_column is not a column of values_df.

identify_golden_cycles

identify_golden_cycles(
    value_column: str = "value_double",
    method: str = "low_variability",
    top_n: int = 5,
    target: float | None = None,
) -> list[str]

Identify the best performing cycles (golden cycles).

Parameters:

Name	Type	Description	Default
value_column	str	Column holding the values to evaluate. metric is the deprecated name.	'value_double'
method	str	'low_variability' (smallest std / |mean|), 'high_mean' (largest mean) or 'target_value' (mean closest to target).	'low_variability'
top_n	int	Number of golden cycles to identify	5
target	float | None	Target value, required for 'target_value'.	None

Returns:

Type	Description
list[str]	Up to top_n cycle UUIDs, best first; ties keep chronological order. Cycles without value_column data, or whose score is undefined (a single sample has no std), are not ranked.

Raises:

Type	Description
ValueError	For an unknown method, or 'target_value' without target.
ColumnNotFoundError	If value_column is not a column of values_df.