Skip to content

Design Builders

The BaseDesignBuilder is an abstract class that provides the foundation for all DOE builders in DaSPi. It defines the common interface and functionality shared by all design types.

Common Features

All design builders inherit these features from BaseDesignBuilder:

Factors

  • Factor Definition: Define experimental factors with their levels
  • Mixed Types: Support for both numerical and categorical factors
  • Validation: Automatic validation of factor names and properties

Replication

  • Multiple Runs: Repeat each factor combination multiple times
  • Error Estimation: Replication helps estimate experimental error
  • Precision: More replicates increase precision of effect estimates

Blocking

Blocking helps control for nuisance variables that might affect your response:

  • Statistical Blocking: Confound blocks with high-order interactions
  • Simple Blocking: Divide runs evenly across blocks
  • Replica Blocking: Each replicate becomes a block

Central Points

  • Curvature Detection: Central points help detect non-linear effects
  • Pure Error: Provide an estimate of pure experimental error
  • Model Adequacy: Help assess whether a linear model is adequate

Randomization

  • Run Order: Randomize the order of experimental runs
  • Block-wise: Randomization within each block
  • Bias Reduction: Helps reduce the effect of time trends and other nuisance factors

Design Matrix Output

All builders produce standardized design matrices with these columns:

  • std_order: Original order before randomization
  • run_order: Randomized execution order
  • central_point: 1 for factor points, 0 for central points
  • replica: Replicate number for each factor combination
  • block: Block assignment
  • Factor columns: One column per factor with levels

Usage Pattern

All design builders follow the same basic pattern:

import daspi as dsp

# 1. Define factors
factor_a = dsp.Factor('A', (1, 2))
factor_b = dsp.Factor('B', (10, 20))

# 2. Create builder with options
builder = dsp.SomeDesignBuilder(
    factor_a, factor_b,
    replicates=2,
    central_points=3,
    blocks='highest',
    shuffle=True
)

# 3. Generate design matrix
design = builder.build_design(corrected=False)

# 4. Use the design for your experiments
print(design)

Coded vs Original Values

Builders can return designs in two formats:

# Original factor values (for experimental use)
design_original = builder.build_design(corrected=False)

# Coded values (for statistical analysis)
design_coded = builder.build_design(corrected=True)

Coded values use standardized scales (typically -1, 0, +1) that make statistical analysis easier and more interpretable.

Validation and Error Checking

All builders perform extensive validation:

  • Factor names must be unique
  • Factor names cannot conflict with standard column names
  • Positive number of replicates
  • Valid block specifications
  • Proper generator syntax (for fractional factorials)

API Reference

daspi.doe.BaseDesignBuilder(*factors, replicates=1, blocks=1, central_points=0, shuffle=True)

Bases: ABC

Abstract base class for DOE builders.

PARAMETER DESCRIPTION
factors

Factors defining the design space.

TYPE: Iterable[Factor] DEFAULT: ()

replicates

Number of replicates. Must be positive, by default 1.

TYPE: int DEFAULT: 1

blocks

Block assignment: integer for evenly spaced blocks, str | List[str] for user-defined block generator, or Literal 'highest'/'replica'. Must be positive or 'highest'/'replica', by default 1.

TYPE: int | str | List[str] | Literal['highest', 'replica'] DEFAULT: 1

central_points

Number of central points to be added to each block. These are used to test linear effects. Must be non-negative. If set to 0, no central points are added. by default 0.

TYPE: int DEFAULT: 0

shuffle

Whether to shuffle the design, by default True.

TYPE: bool DEFAULT: True

RAISES DESCRIPTION
AssertionError

If any of the parameters are invalid: - At least one factor is required. - Factor names must not conflict with standard columns in the design matrix. - All factors must be instances of Factor class. - Number of replicates must be positive. - Number of central points must be non-negative. - At least one factor must provide a central point, or set central_points to 0. - Number of blocks must be positive. - Factor names must be unique.

fold instance-attribute

Whether to add a foldover to the design.

shuffle = shuffle instance-attribute

Whether to shuffle the design.

factors property writable

Tuple of factors defining the design space.

replicates property writable

Number of replicates (read-only).

central_points property writable

Number of central points (read-only).

blocks property writable

Block assignment: integer for evenly spaced blocks, str | List[str] for user-defined block generator, or Literal 'highest'/'replica'.

factor_names property

List of factor names (read-only).

level_counts property

Tuple of level counts for each factor (read-only).

standard_columns property

List of standard columns in the design matrix.

columns property

List of columns in the design matrix.

is_2k property

Check if the design is a 2^k design.

build_design(corrected=True)

Generate the design matrix with original factor values.

This method builds the design matrix by generating the corrected (integer-coded) design, replicating it according to the replicates parameter, shuffling it if specified, and adding central points if specified. Block assignment is controlled by the blocks option at initialization:

  • If blocks is an int > 1: blocks are assigned evenly (not statistically confounded).
  • If blocks is an str or List[str]: blocks are assigned by confounding with the specified interaction (statistically correct).
  • If blocks is 'highest': blocks are assigned by confounding with the highest-order interaction (all centralized factors).
  • If blocks is 'replica': blocks are assigned based on the replicate number.
  • If blocks == 1: all runs are assigned to block 1.
RETURNS DESCRIPTION
DataFrame

Design matrix with original factor values if corrected is False, otherwise with integer codes representing factor levels.
Notes

Statistically correct block assignment is performed by confounding the block effect with a specified interaction (block generator). For each run, the value of the block generator (the product of the coded levels of the specified factors) is computed, and unique values are mapped to block numbers. If blocks is 'highest', the highest-order interaction (all factors) is used. This ensures that block effects are orthogonal to main effects and lower-order interactions when using a confounding generator, as recommended in DOE literature (see Montgomery, 2017). If blocks is a str or List[str], the specified interaction is used. If blocks is 'replica', blocks are assigned by replicate. If blocks is an int, blocks are assigned evenly (not statistically confounded).