Prediction

Use a fitted MLR model to predict one response at factor settings loaded from a CSV or Excel workbook.

Load prediction points

PredictionPointsMixin.load_prediction_points(source, coded=False)

Load and validate factor settings at which to make predictions.

Parameters:

• source (str | Path | DataFrame) – DataFrame or CSV/XLSX file containing every factor column. Additional columns are ignored.

• coded (bool) – Whether process and categorical factor values are coded. Mixture components are unaffected. Defaults to False.

Raises:

• FileNotFoundError – If a supplied path does not exist.

• TypeError – If coded is not Boolean.

• ValueError – If the file is empty, has duplicate or missing factor columns, or contains invalid factor settings.

Return type:

None

Notes

Row order, index, and duplicate factor settings are preserved. A failed load leaves any previously loaded points unchanged.

The file must contain one column for every factor. Additional columns are ignored, row order and repeated settings are retained, and invalid files do not replace previously loaded points. Values use actual factor units by default:

design.load_prediction_points(
    source="prediction_points.xlsx",
    coded=False,
)

An existing DataFrame can be loaded without writing an intermediate file:

design.load_prediction_points(source=prediction_points)

Set coded=True when continuous and categorical factors use their coded levels. Mixture components are always supplied as proportions. The same bounds, categorical levels, mixture constraints, and domain filters used for confirmation runs are applied to prediction points.

Retrieve stored points

PredictionPointsMixin.get_prediction_points(coded=False)

Return loaded prediction settings in actual or coded units.

Parameters:

coded (bool) – Whether to return coded factor settings. Defaults to False.

Returns:

A defensive copy of the prediction factor settings.

Return type:

DataFrame

Raises:

• TypeError – If coded is not Boolean.

• ValueError – If prediction points have not been loaded.

Both forms are available as defensive copies:

actual_points = design.get_prediction_points()
coded_points = design.get_prediction_points(coded=True)

Calculate predictions and intervals

Configure and fit the model with set_model_terms() and compute_mlr_model(), then select one fitted response:

PredictionPointsMixin.get_prediction_results(response, alpha=0.05, coded=False, *, interval='confidence', variance_source='residuals')

Return predictions and pointwise confidence or prediction intervals.

Parameters:

• response (str) – Fitted response to predict.

• alpha (float) – Pointwise significance level for the two-sided confidence interval. Must lie strictly between 0 and 1. Defaults to 0.05.

• coded (bool) – Whether factor columns in the result use coded values. Defaults to False.

• interval (Literal['confidence', 'prediction']) – “confidence” for the expected mean (default), or “prediction” for one new independent observation.

• variance_source (Literal['residuals', 'pure_error']) – “residuals” (default) or “pure_error”. Pure error requires valid replicated observations.

Returns:

Factor settings followed by Predicted, CI Lower,

and CI Upper columns for confidence intervals, or PI Lower and PI Upper for prediction intervals, one row per loaded point.

Return type:

DataFrame

Raises:

• TypeError – If alpha is not numeric or coded is not Boolean.

• ValueError – If points or a fitted response model are unavailable, or if alpha is outside the open interval (0, 1).

Notes

Half-widths are t * sqrt(MS * h) for the mean and t * sqrt(MS * (1 + h)) for one new observation. The selected variance and its degrees of freedom are used for both terms. These are two-sided pointwise intervals under the OLS assumptions of independent homoscedastic normal errors and an adequate model. Results are calculated from the current fitted model on every call. If residual degrees of freedom or the residual mean square are unavailable, point predictions are still returned and both selected interval columns contain NaN. Unavailable pure error raises an explicit error instead of falling back to residual variance.

results = design.get_prediction_results(
    response="Yield",
    alpha=0.05,
    coded=False,
)

The result contains the factor-setting columns followed by Predicted, CI Lower, and CI Upper. Setting coded=True changes only the displayed factor values; statistical results are identical.

For saturated models, or other fits without a valid residual mean square, the point prediction remains available but CI Lower and CI Upper are NaN because a confidence interval cannot be estimated.

For a model row vector \(x_0\), the pointwise confidence interval for the expected mean response is

\[\hat{y}_0 \pm t_{1-\alpha/2,\,df_{res}} \sqrt{MS_{res}\,x_0^T(X^TX)^+x_0}.\]

This default, interval="confidence", describes uncertainty in the mean. For one new independent observation, select interval="prediction":

results = design.get_prediction_results(
    "Yield", interval="prediction", variance_source="residuals", alpha=0.05,
)

The limit columns are then PI Lower and PI Upper. Its half-width is

\[t_{1-\alpha/2,\,df_{res}}\sqrt{MS_{res}(1+h_0)}, \qquad h_0 = x_0^T(X^TX)^+x_0.\]

Clear prediction points

PredictionPointsMixin.clear_prediction_points()

Remove loaded prediction points without changing the fitted model.

Return type:

None

Clearing the points does not modify the fitted model, responses, design matrix, or confirmation runs.