tessl/pypi-pydoe3

Design of experiments library for Python with comprehensive experimental design capabilities

—

Pending

Overview

Eval results

Files

Classical Factorial Designs

Name: tessl/pypi-pydoe3
Author: tessl

Traditional experimental designs including full factorial, fractional factorial, and screening designs. These methods form the foundation of experimental design methodology and are suitable for factor screening, main effects analysis, and interaction studies.

Capabilities

Full Factorial Designs

Complete experimental designs that test all possible combinations of factor levels.

General Full Factorial Design

Creates a general full-factorial design for factors with different numbers of levels.

def fullfact(levels):
    """
    Create a general full-factorial design
    
    Parameters:
    - levels: array-like, number of levels for each factor
    
    Returns:
    - mat: 2d-array, design matrix with coded levels 0 to k-1 for k-level factor
    """

Usage Example:

import pyDOE3

# 3-factor design: 2 levels, 4 levels, 3 levels
design = pyDOE3.fullfact([2, 4, 3])
print(f"Design shape: {design.shape}")  # (24, 3)
# Factor levels coded as 0,1 for factor 1; 0,1,2,3 for factor 2; 0,1,2 for factor 3

2-Level Full Factorial Design

Creates a 2-level full-factorial design with coded levels -1 and +1.

def ff2n(n_factors: int) -> np.ndarray:
    """
    Create a 2-Level full-factorial design
    
    Parameters:
    - n_factors: int, number of factors in the design
    
    Returns:
    - mat: 2d-array, design matrix with coded levels -1 and +1
    """

Usage Example:

import pyDOE3

# 3-factor, 2-level full factorial (2^3 = 8 runs)
design = pyDOE3.ff2n(3)
print(f"Design shape: {design.shape}")  # (8, 3)
# All factors coded as -1 (low level) and +1 (high level)

Fractional Factorial Designs

Efficient screening designs that test a subset of all possible factor combinations while preserving important statistical properties.

Fractional Factorial with Generator String

Creates fractional factorial designs using generator strings to define the factor confounding structure.

def fracfact(gen) -> np.ndarray:
    """
    Create a 2-level fractional-factorial design with a generator string
    
    Parameters:
    - gen: str, generator string defining factors and confounding structure
           Uses lowercase letters for main factors, combinations for interactions
    
    Returns:
    - H: 2d-array, fractional factorial design matrix with -1/+1 coding
    """

Usage Example:

import pyDOE3

# 2^(4-1) fractional factorial design (4 factors in 8 runs)
# Main factors: a, b, c; Generated factor: d = abc
design = pyDOE3.fracfact("a b c abc")
print(f"Design shape: {design.shape}")  # (8, 4)

# 2^(5-2) fractional factorial design (5 factors in 8 runs)  
design = pyDOE3.fracfact("a b c ab ac")
print(f"Design shape: {design.shape}")  # (8, 5)

Fractional Factorial by Resolution

Creates fractional factorial designs based on desired resolution level.

def fracfact_by_res(n, res):
    """
    Create a 2-level fractional factorial design by resolution
    
    Parameters:
    - n: int, number of factors
    - res: int, minimum resolution (III, IV, V, etc.)
    
    Returns:
    - H: 2d-array, fractional factorial design matrix
    """

Optimal Fractional Factorial Generator

Finds optimal generator strings for fractional factorial designs.

def fracfact_opt(n_factors, n_erased, max_attempts=0):
    """
    Find optimal generator string for fractional factorial design
    
    Parameters:
    - n_factors: int, total number of factors
    - n_erased: int, number of factors to generate (not run independently)
    - max_attempts: int, maximum optimization attempts (0 for unlimited)
    
    Returns:
    - generator: str, optimal generator string
    """

Aliasing Analysis

Analyzes confounding patterns in fractional factorial designs.

def fracfact_aliasing(design):
    """
    Find aliasing structure in a fractional factorial design
    
    Parameters:
    - design: 2d-array, fractional factorial design matrix
    
    Returns:
    - aliasing: dict, aliasing relationships between effects
    """

def alias_vector_indices(n_factors):
    """
    Get indices for alias vector conversion
    
    Parameters:
    - n_factors: int, number of factors
    
    Returns:
    - indices: array, indices for alias vector operations
    """

Screening Designs

Efficient designs for screening many factors with minimal experimental effort.

Plackett-Burman Design

Orthogonal screening designs for investigating many factors in few runs.

def pbdesign(n):
    """
    Generate a Plackett-Burman design
    
    Parameters:
    - n: int, number of factors to screen
    
    Returns:
    - H: 2d-array, orthogonal design matrix with n columns
            Number of rows is next multiple of 4 higher than n
    """

Usage Example:

import pyDOE3

# Screen 7 factors in 8 runs
design = pyDOE3.pbdesign(7)
print(f"Design shape: {design.shape}")  # (8, 7)

# Screen 11 factors in 12 runs
design = pyDOE3.pbdesign(11)  
print(f"Design shape: {design.shape}")  # (12, 11)

Generalized Subset Design

Generalized screening designs for factors with multiple levels.

def gsd(levels, reduction, n=1):
    """
    Create a Generalized Subset Design (GSD)
    
    Parameters:
    - levels: array-like, number of levels per factor
    - reduction: int, reduction factor (> 1) for design size
    - n: int, number of complementary designs (default 1)
    
    Returns:
    - H: 2d-array or list of 2d-arrays, GSD design matrix(ces)
    """

Usage Example:

import pyDOE3

# GSD for mixed-level factors with reduction
levels = [3, 4, 2, 5]  # factors with 3, 4, 2, 5 levels respectively
design = pyDOE3.gsd(levels, reduction=4)
print(f"Design shape: {design.shape}")

# Multiple complementary designs
designs = pyDOE3.gsd(levels, reduction=4, n=2)
print(f"Number of designs: {len(designs)}")

Design Selection Guidelines

When to Use Each Design Type:

Full Factorial Designs:

Use when you have few factors (typically ≤ 4-5)
Need to estimate all main effects and interactions
Have sufficient experimental resources
Want complete information about factor space

Fractional Factorial Designs:

Use for factor screening with many factors (5-15)
Want to estimate main effects and some interactions efficiently
Have limited experimental budget
Can tolerate confounding of higher-order interactions

Plackett-Burman Designs:

Use for initial screening of many factors (8-30+)
Primarily interested in main effects
Very limited experimental resources
Don't need interaction information initially

Generalized Subset Designs:

Use when factors have different numbers of levels (not just 2-level)
Need screening capability for mixed-level problems
Want balanced designs for multi-level factors

Resolution Guidelines:

Resolution III: Main effects confounded with 2-factor interactions
Resolution IV: Main effects clear, 2-factor interactions confounded with each other
Resolution V: Main effects and 2-factor interactions clear

Types

import numpy as np
from typing import Union, List

# Type aliases
LevelsSpec = Union[List[int], np.ndarray]
GeneratorString = str
DesignMatrix = np.ndarray

Install with Tessl CLI