lind.design package

Submodules

lind.design.box_behnken module

TODO:

lind.design.box_wilson module

box_wilson: Box-Wilson experiment designs, sometimes referred to as Central-Composite Designs (CCDs), are useful for measuring quadratic effects.

Linear effects are typically measured using 2 level factorial or 2 level Plackett-Burman experiments. However, if the relationship between treatments and response are quadratic, more than 2 levels may be required to accurately represent the response surface of the experiment.

CCDs allow experimenters to model quadratic response surfaces without implementing full 3 level factorial experiments. CCD designs consist of three “runs”: A) a factorial experiment (sometimes fractional in design) B) a set of center points, experimental runs whose values of each factor are the medians of the values used in the factorial portion C) a set of axial points, experimental runs identical to the centre points except for one factor, which will take on values both below and above the median of the two factorial levels.

A) corner points (defined by the factorial design or matrix_f)
B) center points (defined by the matrix_c)
C) axial points (defined by the matrix_e)

Axial points are sometimes referred to as star points.

If the distance from the center of the design space to a factorial point is 1 unit for each factor, the distance from the center of the design space to a star point is |alpha| > 1. The precise value of alpha depends on the variables center, alpha_design, and face_design.

In rare cases (i.e. k=2) a design can be orthogonal and rotatable. However, this is only true in a vary limited number of cases. See the example below: >>> design_box_wilson(k=2, alpha_design=”orthogonal”, center=(1,1), face_design=”CCC”) >>> design_box_wilson(k=2, alpha_design=”rotatable”, center=(1,1), face_design=”CCC”)

lind.design.box_wilson.design_box_wilson(k: int, alpha_design: Optional[str] = 'rotatable', center: Optional[Tuple[int, int]] = (1, 1), face_design: Optional[str] = 'CCC') → pandas.core.frame.DataFrame

boc_wilson: Central Composite Design (CCD)

A CCD design contains an embedded factorial design with center points that are augmented with a group of ‘star points’ that allow estimation of curvature useful for estimating quadratic relationships.

CCD designs can use facing options: CCC (Circumscribed), CCI (Inscribed), and CCF (Face Centered).

CCC designs are the original form of the central composite design. The star points are at some distance alpha from the center based on the properties desired for the design and the number of factors in the design. The star points establish new extremes for the low and high settings for all factors. These designs have circular, spherical, or hyperspherical symmetry and require 5 levels for each factor. Augmenting an existing factorial or resolution V fractional factorial design with star points can produce this design.

CCI is useful in situations where the limits specified for factor settings are truly limits, the CCI design uses the factor settings as the star points and creates a factorial design within those limits (in other words, a CCI design is a scaled down CCC design with each factor level of the CCC design divided by alpha to generate the CCI design). This design also requires 5 levels of each factor. CCI designs can use partial factorial designs for matrix_f. This is not supported here.

CCF design star points are at the center of each face of the factorial space, so alpha=1. This requires 3 levels of each factor. Augmenting an existing factorial or resolution V design with appropriate star points can also produce this design.

Parameters

  • k (int) – the total number of factors considered in the design

  • alpha_design (str, optional) – The method of calculating the distance alpha. Available options: orthogonal, rotatable; Just like MATLAB ccdesign, rotatable is the default

  • center (Tuple[int, int], optional) – the first value of the tuple is the factorial center point, the second value of the tuple is the axial center point; default value is (1, 1)

  • face_design (str, optional) – this input determines the symmetry / geometric of the design; valid options are: CCC, CCF, and CCI

Returns

the box-wilson experimental design

Return type

pd.DataFrame

Examples

>>> design = design_box_wilson(k=2, alpha_design="rotatable", center=(1,1), face_design="CCC")

References

NIST

  • Section 5.3.3.6.1 of the Engineering Statistics Handbook

Myers

  • Response Surface Methodology (1971)

Box and Wilson

  • On the Experimental Attainment of Optimum Conditions (1951)

Notes

  • When face_design=`CCF` the alpha_design argument is ignored and alpha is set to 1.

  • Popular CCD designs are orthogonal (OCCD), rotatable (RCCD), face (FCC), spherical (SCCD), and Slope Rotatable (Slope-R); of these only the first three are supported

lind.design.factorial module

factorial: This module contains tools for designing factorial experiments. Full factorial experiments (where every combination of treatments is explored) and partial factorial (where only a fraction of combinations are explored). Partial factorial experiments are sometimes referred to as fractional factorial experiments.

The factorial designs here are meant to yield balanced and orthogonal designs. An experimental design is orthogonal if the effects of any factor (i.e. factor A) balance out (sum to zero) across the effects of the other factors (i.e. factors B and C). In other words, if A is orthogonal to B and C, then the measurement of factors B and C will not be biased by the effect size fo A. A balanced design assumes equal sample sizes across att cohorts / test cells.

One quick check of orthogonality for a 2 level design is to take the sum of the columns of the design. They should all sum to 0. See below: >>> design_partial_factorial(factors=6, res=4).sum(axis=0)

If possible, all combinations (rows) in these designs should be run in a random order, or in parallel using proper randomization of cohort assignment.

Recommended import style: >>> from lind.design import factorial

lind.design.factorial.design_full_factorial(factors: List[List], factor_names: Optional[List[str]] = None) → pandas.core.frame.DataFrame

This function helps create a full factorial experiment design. Given how easy it is to design a full factorial experiment once the factors and levels have been specified, this is more of a convenience function.

Parameters

  • factors (List[List]) – a list of lists representing factors and levels

  • factor_names (List[str], optional) – a list of names for the factors in the first argument. Must share the order of the first argument.

Returns

Return type

pd.DataFrame

Examples

>>> # create full factorial design for a 2 level 3 factor experiment
>>> design_df = design_full_factorial(factors=[[-1, 1], [-1,1], [-1, 1]],
>>>     factor_names=["factor_one", "factor_two", "factor_three"])
lind.design.factorial.design_partial_factorial(k: int, res: int) → pandas.core.frame.DataFrame

This function helps design 2 level partial factorial experiments. These experiments are often described using the syntax l**(k-p) where l represents the level of each factor, k represents the total number of factors considered, and p represents a scaling factor relative to the full factorial design.

This function assumes that l=2. Users are not asked to set p, instead the user sets a minimum desired resolution for their experiment. Resolution describes the kind of aliasing incurred by scaling down from a full to a partial factorial design. Higher resolutions have less potential aliasing (confounding).

Resolution number is determined through the defining relation of the partial factorial design. For the 6 factor design 2**(6-p) with factors ABCDEF, example defining relations (I) are shown below. The resolution cannot exceed the number of factors in the experiment. So a 6 factor experiment can be at most a resolution 6 (otherwise it would be a full factorial experiment).

  • Res I: I = A

  • Res II: I = AB

  • Res III: I = ABC

  • Res IV: I = ABCD

  • Res V: I = ABCDE

  • Res VI: I = ABCDEF

Practically we tend to use resolution III-, IV- and V-designs.

  • Res I: Cannot distinguish between levels within main effects (not useful).

  • Res II: Main effects may be aliased with other main effects (not useful).

  • Res III: Main effects may be aliased with two-way interactions.

  • Res IV: Two-way interactions may be aliased with each other.

  • Res V: Two-way interactions may be aliased with three-way interactions.

  • Res VI: Three-way interactions may be aliased with each other.

Parameters

  • k (int) – the total number of factors considered in the experiment

  • res (int) – the desired minimum resolution of the experiment

Returns

A dataframe with the partial factorial design

Return type

pd.DataFrame

Examples

>>> # create partial factorial design for a 2 level 4 factor resolution III experiment
>>> design_df = design_partial_factorial(k=4, res=3)
lind.design.factorial.fetch_partial_factorial_design(design_name: str = 'toc') → pandas.core.frame.DataFrame

The function design_partial_factorial auto generates partial factorial designs using an algorithm. We validate that algorithm in our unit tests by comparing against known designs from popular experimental design textbooks. For those that want to use the designs from these books rather than the auto-generated designs, please use thos function.

There are multiple ways to generate certain designs given a fixed k and p (using formula l**k-p). Both fetch_partial_factorial_design and design_partial_factorial deterministically return designs, but there are typically other ways to formulate these designs if the user would like to work it out on their own.

Parameters

design_name (str) – the name of the design to fetch; to see available designs input toc

Returns

experiment design or toc of available designs

Return type

pd.DataFrame

Examples

>>> table_of_contents_of_designs = fetch_partial_factorial_design("toc")
>>> design = fetch_partial_factorial_design("2**3-1")

References

NIST

  • Section 5.3.3.4.7 of the Engineering Statistics Handbook

Box, Hunter, & Hunter

  • Statistics For Experimentors

Taguchi

  • Systems Of Experimental Design, VOL. 2

Notes

  • 2**3-1 is equivalent to a Taguchi L4 design

  • 2**15-11 is equivalent to a Taguchi L16 design

  • 2**31-26 is equivalent to a Taguchi L32 design

lind.design.latin_hyper_cube module

TODO:

lind.design.plackett_burman module

plackett_burman: This module contains tools for designing Plackett-Burman experiments.

Plackett and Burman generated sets of useful 2 level experimental designs using a method Raymond Paley identified in 1933. This method generated orthogonal matrices with elements (1, -1). Paley’s method could be used to find such matrices of size N for most N equal to a multiple of 4 (all such N up to 100 except N = 92). This gave Plackett and Burman the interesting quality that they only increase the number of rows (require runs) in the experiment for every 4 factors added to the design.

Plackett and Burman are structured so that each combination of levels for any pair of factors appears the same number of times, throughout all the experimental runs.

These designs achieved orthogonality with many fewer runs than a full factorial design. When N is a power of 2 then a Plackett and Burman design is equivalent to a partial factorial resolution III design. All Plackett and Burman designs assume negligible interaction effects relative to main effects.

Plackett and Burman do mention designs with more then 2 levels (a rediscovery of methods invented by Raj Chandra Bose and K. Kishen), however these are rarely used in practice.

Recommended import style: >>> from lind.design import plackett_burman as pb

lind.design.plackett_burman.fetch_plackett_burman_design(num_factors: int) → pandas.core.frame.DataFrame

This function helps create Plackett-Burman experimental designs. Plackett-Burman designs are very efficient screening designs when only main effects are of interest.

Parameters

num_factors (int) – the number of factors in the design. Currently only supports up to 47 factors per design.

Returns

experiment design or toc of available designs

Return type

pd.DataFrame

Examples

>>> design = fetch_plackett_burman_design(7)

References

NIST

  • Section 5.3.3.5 of the Engineering Statistics Handbook

Plackett and Burman

  • The Design of Optimum Multifactorial Experiments

lind.design.taguchi module

taguchi: Taguchi experiments are quick and dirt designs that are effective for quality control in engineering. Some experimenters use Taguchi Method designs as screening experiments in a similar manner to Plackett Burman designs. They are useful designs in quality control but due to recent fads in marketing are often misapplied in other fields. Taguchi methods were some of the first Robust Parameter Designs.

The Taguchi Method is a multi-step process for producing a design. To fully understand the process see the reources mentioned below. We provide a quick overview here: First split your factors into A) inner array factors (factors you control) and B) outer array factors (environmental factors out of your control). The function recommend_inner_array will help identify an orthogonal array to use as your design base. Once you know which array you want to use as your base, the function fetch_inner_array will retrieve that array. If there are non-trivial interactions you need to model in your inner array, you may need to censor certain columns before proceeding. Finally, append the outer array to your inner array using the function append_outer_array.

An example workflow is shown below.

Unlike traditional factorial designs like those in the module lind.design/factorial, Taguchi designs rely heavily on pre-experiment judgement. This is often useful in quality control, but can introduce dangerous assumptions in other fields. Taguchi’s method builds on the theory of fractional factorial designs, depending on the experiment requirements, either methodology may be more efficient and/or less biased. It is up to the experimenter to understand when to use each method.

Workflow Example

>>> # find the appropriate orthogonal array to build inner array of experiment design
>>> print(
>>>     recommend_inner_array(
>>>         levels_group_a=2,
>>>         num_factors_group_a=2,
>>>         interactions_group_a=1,
>>>         measured_moments=1
>>> )) # shows applicable designs
>>> # fetch pandas data frame for inner array
>>> inner_array = fetch_inner_array(design_file_name="L4_2_3")
>>> # print taguchi line graph of inner array interactions
>>> interaction_diagrams("L4_2_3")
>>> # censor columns for interactions assumed to be significant
>>> inner_array = inner_array.drop(columns=["C (A:B)"])
>>> # append noise factors (outer array) to produce full experiment design
>>> experiment_design = append_outer_array(inner_array,
>>>                                        noise_factors=[[-1, 1], [-1, 0, 1], [3.4, 6.7, 1.9]])

References

Taguchi, Chowdhury, and Wu

  • Taguchi’s Quality Engineering Handbook (Appendix C)

Experiment Design and Analysis Reference (reliawiki)

  • Experiment Design and Analysis Reference (Appendix D)

lind.design.taguchi.recommend_inner_array(levels_group_a: int = 0, num_factors_group_a: int = 0, levels_group_b: int = 0, num_factors_group_b: int = 0, interactions_group_a: int = 0, interactions_group_b: int = 0, measured_moments: int = 1) → pandas.core.frame.DataFrame

It is sometimes difficult to know which orthogonal array to use when defining the inner array of a Taguchi experiment. This function can help narrow down the appropriate choices available to an experimenter. The experimenter will often want to choose the design with the fewest number of runs, but that may not always be the case.

If all arguments are left at default values then the function will return all supported Taguchi designs. See module docstring for references and examples.

Parameters

  • levels_group_a (int, optional)

  • num_factors_group_a (int, optional)

  • levels_group_b (int, optional)

  • num_factors_group_b (int, optional)

  • interactions_group_a (int, optional)

  • interactions_group_b (int, optional)

  • measured_moments (int, optional)

Returns

A data frame describing the available designs that meet the user’s criteria; if the data frame is empty then no Taguchi orthogonal arrays meet the user’s specification

Return type

pd.DataFrame

lind.design.taguchi.fetch_inner_array(design_file_name: Optional[str] = None) → pandas.core.frame.DataFrame

The inner array of a Taguchi design is often just a fractional factorial design very similar to more traditional Fisher factorial designs. These are represented by orthogonal arrays that are then censored used the experimenter’s prior judgement about factor interactions.

See module docstring for references and examples.

Parameters

design_file_name (str, optional) – the name of the design / design file name that the experimenter wants to use for the inner array of their design

Returns

a data frame representing the orthogonal array of interest; users may need to censor columns in this array to represent prior knowledge about number of factors or number of significant interactions

Return type

pd.DataFrame

lind.design.taguchi.append_outer_array(inner_array: pandas.core.frame.DataFrame, noise_factors: List[List], noise_factor_names: Optional[List[str]] = None) → pandas.core.frame.DataFrame

The outer array of a Taguchi design represents the noise factors that the designer wants to control for with respect to the inner array. The outer array represents mini-full factorial designs each centered at the individual runs in the inner array. This helps provide data that is “robust” to the levels of the noise factors.

See module docstring for references and examples.

Parameters

  • inner_array (pd.DataFrame) – a dataframe representing the inner array of the Taguchi design

  • noise_factors (List[List]) – a list of lists representing the noise factors and levels

  • noise_factor_names (List[str], optional) – a list of names for the factors in the first argument. Must share the order of the first argument.

Returns

a combination of the inner and outer arrays representing the full taguchi design; uses the same format as all factorial designs in this package as opposed to more traditional Taguchi design display formats

Return type

pd.DataFrame

lind.design.taguchi.interaction_diagrams(design_name: str, save_path: Optional[str] = None, file_name: Optional[str] = None) → None

Line diagrams are vidual aids used by Taguchi to show assumptions about factor interactions that could be using for adapting the design of the inner array.

See module docstring for references and examples.

Parameters

  • design_name (str) – the name of the Taguchi design assocaited with the line graph(s); i.e. L4_2_3

  • save_path (str, optional) – the name to use when saving the png of the line graph; should be an absolute path

  • file_name (str, optional) – the name to use when saving the png of the line graph; if multiple line graphs are saved a number will be appended to the end of the name

Returns

does not return anything

Return type

None

Module contents

Design

This module is dedicated to design of experiments (DOE).