0
# Classical Factorial Designs
1

2
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.
3

4
## Capabilities
5

6
### Full Factorial Designs
7

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

10
#### General Full Factorial Design
11

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

14
```python { .api }
15
def fullfact(levels):
16
    """
17
    Create a general full-factorial design
18
    
19
    Parameters:
20
    - levels: array-like, number of levels for each factor
21
    
22
    Returns:
23
    - mat: 2d-array, design matrix with coded levels 0 to k-1 for k-level factor
24
    """
25
```
26

27
**Usage Example:**
28
```python
29
import pyDOE3
30

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

37
#### 2-Level Full Factorial Design
38

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

41
```python { .api }
42
def ff2n(n_factors: int) -> np.ndarray:
43
    """
44
    Create a 2-Level full-factorial design
45
    
46
    Parameters:
47
    - n_factors: int, number of factors in the design
48
    
49
    Returns:
50
    - mat: 2d-array, design matrix with coded levels -1 and +1
51
    """
52
```
53

54
**Usage Example:**
55
```python
56
import pyDOE3
57

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

64
### Fractional Factorial Designs
65

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

68
#### Fractional Factorial with Generator String
69

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

72
```python { .api }
73
def fracfact(gen) -> np.ndarray:
74
    """
75
    Create a 2-level fractional-factorial design with a generator string
76
    
77
    Parameters:
78
    - gen: str, generator string defining factors and confounding structure
79
           Uses lowercase letters for main factors, combinations for interactions
80
    
81
    Returns:
82
    - H: 2d-array, fractional factorial design matrix with -1/+1 coding
83
    """
84
```
85

86
**Usage Example:**
87
```python
88
import pyDOE3
89

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

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

100
#### Fractional Factorial by Resolution
101

102
Creates fractional factorial designs based on desired resolution level.
103

104
```python { .api }
105
def fracfact_by_res(n, res):
106
    """
107
    Create a 2-level fractional factorial design by resolution
108
    
109
    Parameters:
110
    - n: int, number of factors
111
    - res: int, minimum resolution (III, IV, V, etc.)
112
    
113
    Returns:
114
    - H: 2d-array, fractional factorial design matrix
115
    """
116
```
117

118
#### Optimal Fractional Factorial Generator
119

120
Finds optimal generator strings for fractional factorial designs.
121

122
```python { .api }
123
def fracfact_opt(n_factors, n_erased, max_attempts=0):
124
    """
125
    Find optimal generator string for fractional factorial design
126
    
127
    Parameters:
128
    - n_factors: int, total number of factors
129
    - n_erased: int, number of factors to generate (not run independently)
130
    - max_attempts: int, maximum optimization attempts (0 for unlimited)
131
    
132
    Returns:
133
    - generator: str, optimal generator string
134
    """
135
```
136

137
#### Aliasing Analysis
138

139
Analyzes confounding patterns in fractional factorial designs.
140

141
```python { .api }
142
def fracfact_aliasing(design):
143
    """
144
    Find aliasing structure in a fractional factorial design
145
    
146
    Parameters:
147
    - design: 2d-array, fractional factorial design matrix
148
    
149
    Returns:
150
    - aliasing: dict, aliasing relationships between effects
151
    """
152
```
153

154
```python { .api }
155
def alias_vector_indices(n_factors):
156
    """
157
    Get indices for alias vector conversion
158
    
159
    Parameters:
160
    - n_factors: int, number of factors
161
    
162
    Returns:
163
    - indices: array, indices for alias vector operations
164
    """
165
```
166

167
### Screening Designs
168

169
Efficient designs for screening many factors with minimal experimental effort.
170

171
#### Plackett-Burman Design
172

173
Orthogonal screening designs for investigating many factors in few runs.
174

175
```python { .api }
176
def pbdesign(n):
177
    """
178
    Generate a Plackett-Burman design
179
    
180
    Parameters:
181
    - n: int, number of factors to screen
182
    
183
    Returns:
184
    - H: 2d-array, orthogonal design matrix with n columns
185
            Number of rows is next multiple of 4 higher than n
186
    """
187
```
188

189
**Usage Example:**
190
```python
191
import pyDOE3
192

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

197
# Screen 11 factors in 12 runs
198
design = pyDOE3.pbdesign(11)  
199
print(f"Design shape: {design.shape}")  # (12, 11)
200
```
201

202
#### Generalized Subset Design
203

204
Generalized screening designs for factors with multiple levels.
205

206
```python { .api }
207
def gsd(levels, reduction, n=1):
208
    """
209
    Create a Generalized Subset Design (GSD)
210
    
211
    Parameters:
212
    - levels: array-like, number of levels per factor
213
    - reduction: int, reduction factor (> 1) for design size
214
    - n: int, number of complementary designs (default 1)
215
    
216
    Returns:
217
    - H: 2d-array or list of 2d-arrays, GSD design matrix(ces)
218
    """
219
```
220

221
**Usage Example:**
222
```python
223
import pyDOE3
224

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

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

235
## Design Selection Guidelines
236

237
### When to Use Each Design Type:
238

239
**Full Factorial Designs:**
240
- Use when you have few factors (typically ≤ 4-5)
241
- Need to estimate all main effects and interactions
242
- Have sufficient experimental resources
243
- Want complete information about factor space
244

245
**Fractional Factorial Designs:**
246
- Use for factor screening with many factors (5-15)
247
- Want to estimate main effects and some interactions efficiently
248
- Have limited experimental budget
249
- Can tolerate confounding of higher-order interactions
250

251
**Plackett-Burman Designs:**  
252
- Use for initial screening of many factors (8-30+)
253
- Primarily interested in main effects
254
- Very limited experimental resources
255
- Don't need interaction information initially
256

257
**Generalized Subset Designs:**
258
- Use when factors have different numbers of levels (not just 2-level)
259
- Need screening capability for mixed-level problems
260
- Want balanced designs for multi-level factors
261

262
### Resolution Guidelines:
263

264
- **Resolution III**: Main effects confounded with 2-factor interactions
265
- **Resolution IV**: Main effects clear, 2-factor interactions confounded with each other  
266
- **Resolution V**: Main effects and 2-factor interactions clear
267

268
## Types
269

270
```python { .api }
271
import numpy as np
272
from typing import Union, List
273

274
# Type aliases
275
LevelsSpec = Union[List[int], np.ndarray]
276
GeneratorString = str
277
DesignMatrix = np.ndarray
278
```