design_of_experiments

design_of_experiments

Design-of-Experiments (DOE) run segmentation and effect estimation.

A DOE campaign sweeps one or more factor signals through discrete levels while a response signal is measured. This detector recovers the run structure from continuous process data: contiguous time intervals where every factor signal is stationary at a recognisable level. Each run is tagged with its factor-level combination, and a follow-up method aggregates the response per factor level to expose main effects.

The detector is deliberately classical -- no regression model fit, no fractional factorial enumeration -- so it works on any factor pattern an experimenter actually ran on the line, including OFAT, full factorial, fractional, and Latin square designs.

DesignOfExperimentsEvents

DesignOfExperimentsEvents(
    dataframe: DataFrame,
    factor_uuids: list[str],
    *,
    event_uuid: str = "dev:doe_run",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Segment continuous process data into DOE runs and estimate effects.

A run is a contiguous interval during which every factor signal sits on a single discrete level (low rolling std relative to its tolerance) long enough to be a deliberate experimental setting rather than a transient. Tagging each run with its factor-level combination produces an experimental dataset that downstream effect estimation can act on.

detect_runs

detect_runs(
    *,
    min_duration: str = "5min",
    stability_tol: float = 0.02,
    n_levels: dict[str, int] | None = None
) -> pd.DataFrame

Identify DOE runs as stable intervals across all factor signals.

Parameters:

Name	Type	Description	Default
min_duration	str	Minimum run length to be reported (e.g. "5min"). Shorter stable intervals are treated as transients.	'5min'
stability_tol	float	Maximum relative range (max - min) / (|mean| + eps) permitted within a run for each factor. Default 2%.	0.02
n_levels	dict[str, int] | None	Optional {factor_uuid: k} mapping. When given, the factor values are quantile-binned into k levels; otherwise the rounded observed value is used as the level.	None

Returns:

Type	Description
DataFrame	Interval-shape DataFrame with columns: start, end,
DataFrame	duration_seconds, uuid, run_id, and one
DataFrame	factor__<uuid>_level column per factor.

compute_effects

compute_effects(
    response_uuid: str,
    *,
    statistic: str = "mean",
    min_duration: str = "5min",
    stability_tol: float = 0.02,
    n_levels: dict[str, int] | None = None
) -> pd.DataFrame

Aggregate the response signal per factor level (main effects).

Parameters:

Name	Type	Description	Default
response_uuid	str	UUID of the response (output) signal.	required
statistic	str	Aggregation applied to the response within each run. One of "mean" (default), "median", "max", "min", or "settled" -- the latter takes the mean of the final third of the run, useful for response signals that need to stabilise after a factor change.	'mean'
min_duration	str	Forwarded to :meth:detect_runs.	'5min'
stability_tol	float	Forwarded to :meth:detect_runs.	0.02
n_levels	dict[str, int] | None	Forwarded to :meth:detect_runs.	None

Returns:

Type	Description
DataFrame	Summary DataFrame with one row per (factor, level), columns:
DataFrame	factor, level, n_runs, response_mean,
DataFrame	response_std, main_effect.
DataFrame	main_effect is response_mean minus the grand mean
DataFrame	across all runs.