Export Experiments

In this section, we cover how to export the experimental design matrix for execution in the laboratory. The export_experiments() method writes an Excel workbook (.xlsx) with options for randomization and response columns. CSV export is not supported.

If you plan to import measured results with import_responses(), define the response names when exporting. Those names are retained by the design and identify the response columns expected during import.

Before exporting the design, you can modify it by adding replicates to improve precision and enable lack-of-fit testing.

Design Modification

add_replicates

Add replicate runs to improve precision and enable lack-of-fit testing. This method supports four types of replicates:

  • Center Point Replicates: Add replicates at the design center to estimate pure error and detect curvature.

  • Leverage-Based Replicates: Add replicates at high-leverage points to improve model stability and prediction accuracy in influential regions.

  • Manual Replicates: Add replicates at specific run indices based on experimental priorities or constraints.

  • All Runs Replicates: Add replicates to all runs for a fully replicated design (not recommended for large designs).

Design.add_replicates(type, n_replicates, indices=None)[source]

Add replicate runs to the experimental design.

Augments the design with additional experimental runs to improve precision of model estimates or pure error estimation. Supports multiple replication strategies.

Parameters:

  • type (Literal['all', 'leverage', 'center', 'manual']) –

    Replication strategy:

    • ’all’: Replicate all design points

    • ’leverage’: Replicate high-leverage points only

    • ’center’: Add center point replicates

    • ’manual’: Replicate specific points by index

  • n_replicates (int) – Number of replicates to add (interpretation depends on type).

  • indices (Optional[List[int]]) – Row indices of points to replicate (required when type=’manual’).

Raises:

  • ValueError – If n_replicates is negative or not an integer.

  • ValueError – If type is not one of the allowed options.

  • ValueError – If indices are not provided for manual replication.

  • ValueError – If model matrix is not defined when using leverage replication.

Return type:

None

Notes

Replication updates both the coded and decoded design matrices. If a model matrix exists, it is automatically rebuilt to include the new runs.

For type=’leverage’, points are selected based on their hat matrix diagonal values, with higher leverage points being more influential on model estimates.

Example:

# Add 3 center point replicates
design.add_replicates(type="center", n_replicates=3)

# Replicate high-leverage points
# Add 1 replicate to the top 2 leverage points
design.add_replicates(type="leverage", n_replicates=2)

# Replicate specific runs
# Add 1 replicate to runs at indices 0, 5, and 10
design.add_replicates(type="manual", n_replicates=1, indices=[0, 5, 10])

Export Experiments

export_experiments

Export a design matrix to an Excel workbook for laboratory execution.

Note

Exp. Order is the planned sequence in which to perform the runs. Follow it during laboratory execution; it is randomized when randomize=True.

Exp. Idx is the stable identifier of the original internal design row. Do not edit it: import_responses() uses it to associate measured responses with the correct run and restore the internal design order.

Design.export_experiments(responses=None, randomize=True, destination='design_matrix.xlsx', coded=False)[source]

Export the experimental design to an Excel file for laboratory execution.

The execution order can be randomized to reduce systematic effects during laboratory work. Export is supported only for Excel workbooks; use an .xlsx path.

Parameters:

  • responses (Optional[List[str]]) – Names of response variables to add to the workbook. Provide these names when results will later be imported with import_responses(); they are retained for validating the import. Defaults to None.

  • randomize (bool) – Whether to randomize the execution order. Defaults to True.

  • destination (str | Path) – Destination Excel workbook path. CSV export is not supported. Defaults to "design_matrix.xlsx".

  • coded (bool) – If True, export coded factor values. If False, export values in the original experimental units. Defaults to False.

Return type:

None

Notes

The workbook contains the following columns:

  • Exp. Order is the planned execution sequence. Follow this column in the laboratory; it is randomized when randomize=True.

  • Exp. Idx is the stable identifier of the corresponding internal design row. Do not edit it: import_responses() uses it to restore the internal design order.

  • Factor columns contain the settings for each run.

  • Response columns contain the named measurements to complete after running the experiments.

Example:

# Export with randomization for blind experiments
design.export_experiments(
    responses=["Yield", "Purity", "Cost"],
    randomize=True,
    destination="experiment_plan.xlsx",
    coded=False  # Use actual factor units
)