Documentation#

Words#

gen2num(g: str) → int#

Convert a generator into its corresponding column number

Generators can only contain lowercase letters from a to z.

Parameters:

g (str) – Generator

Examples

>>> gen2num('acd')
13

See also

num2gen

Convert a column number into its corresponding generator

num2gen(n: int, m: int | None = None) → str#

Return the generator corresponding to a given column number

If a value is provided for the number of four-level factors, the pseudo-factors used to generate the four-level factors will be replaced by their corresponding labels in the generator. The labels are:

  • A1=a, A2=b, A3=ab for the first factor

  • B1=c, B2=d, B3=cd for the second factor

  • C1=e, C2=f, C3=ef for the third factor

Parameters:

  • n (int) – Column number

  • m (Optional[int]) – Number of four-level factors. If no value is provided, the generator will be considered to come from a two-level design. By default, no value is provided.

Examples

>>> num2gen(7)
'abc'
>>> num2gen(7, m=1)
'A1c'

See also

gen2num

Convert a generator into the corresponding column number

relabel_word(word: str, m: int) → str#

Relabel basic factors in a word to their corresponding pseudo-factors.

Relabel a word containing only two-level factors by replacing the basic factors used as pseudo-factors by their corresponding pseudo-factor labels. The pseudo-factor labels are A_i, B_i and C_i with i = 1,2,3, for the first, second, and third four-level factor, respectively.

Parameters:

  • word (str) – Word to relabel

  • m (int) – Number of four-level factors. Define up to which factor the relabeling occurs.

Examples

>>> # The value of `m` define how many factors are relabeled
>>> relabel_word(word='abcde', m=1)
'A3cde'
>>> relabel_word(word='abcde', m=3)
'A3B3C1'
word_length(word: str) → int#

Compute the length of a word that can contain pseudo-factors.

Examples

>>> word_length('abcd')
4
>>> word_length('A1cdC1')
4
word_type(word: str) → int#

Compute the type of a word that can contain pseudo-factors.

Examples

>>> word_type('abcde')
0
>>> word_type('A1cde')
1

Defining relation#

class Relation(words: List[str], m: int = 0)#
expand(relabel: bool = False) → List[str]#

Expand a defining subgroup into the complete defining relation.

For a defining subgroup with p members, expand it into all 2^p -1 interactions between the members.

Parameters:

relabel (bool) – Relabel the pseudo-factors in the words of the defining relation. Default is False

Examples

>>> r = Relation(words=['abcdf', 'aceg'], m=1)
>>> r.expand()
['abcdf', 'aceg', 'bdefg']
>>> # You can also relabel the pseudo-factors in the words
>>> r.expand(relabel=True)
['A3cdf', 'A1ceg', 'A2defg']
word_length_pattern() → List[List[int]]#

Compute the type-specific word length pattern of the defining relation.

The type-specific word length pattern is a list of sublists, where the sublist at index i is the number of word of length 3+i, ordered by increasing type.

Examples

>>> # Create a relation with two words of type 1 and length 4
>>> r = Relation(words=['abcdf', 'aceg'], m=1)
>>> # The third word is bdefg and has length 5
>>> r.word_length_pattern()
[[0, 0], [0, 2], [0, 1]]
>>> # If m=0, then output a normal word length pattern
>>> Relation(words=['abcdf', 'aceg']).word_length_pattern()
[0, 1, 2]

Design#

class Design(runsize: int, m: int, cols: list[int])#

Regular design with four-level and two-level factors.

Parameters:

  • runsize (int) – Number of runs

  • m (int) – Number of four-level factors

  • cols (List[int]) – List of the added factors of the design. Cannot contain columns used in four-level factors and basic factors.

runsize#

Number of runs

Type:

int

m#

Number of four-level factors

Type:

int

n#

Number of two-level factors in the design

Type:

int

k#

Number of basic factors. Equals to the log2 of the runsize.

Type:

int

p#

Number of added factors

Type:

int

bf#

List of the column numbers of the basic factors not used in the pseudo-factors pf.

Type:

List[int]

pf#

List of the pseudo-factors triplets (as lists of integers), used to define the four-level factors.

Type:

List[List[int]]

af#

List of the column numbers of the added factors

Type:

List[int]

cols#

List of the column numbers of all the two-level factors of the design.

Type:

List[int]

array#

Design matrix of the design with the four-level factors first and then the two-level factors. The two-level factors are ordered by column number and not kept in the original order.

Type:

np.ndarray

add_factor(number: int)#

Add a two-level factor to the design.

Generate a design with an added two-level factor defined by the number supplied.

Parameters:

number (int) – Column number of the factor to add. Cannot correspond to a column number already in use (as two-level factor or pseudo-factor) in the design.

Returns:

A Design object containing the added two-level factor

Return type:

Design

alpha_wlp(rounding: bool = True) → list[float]#

Compute the alpha word length pattern of the design. The alpha wlp contains 5 values ordered in the following way: Ο‰4, Ο‰2, Ο‰42, Ο‰22, Ο‰44

Parameters:

rounding (bool, optional) – Round the Ο‰ values to 2 decimals, by default True

Returns:

The alpha word length pattern

Return type:

list[float]

beta_star_wlp(max_length: int | None = None) → tuple[list[tuple[float]], list[list[int]]]#

Compute the 𝛽* vector for a design. It contains tuples with the 𝛽*_i value, and the A_i^0 value for values of i starting with 3.

Parameters:

  • design (fatld.Design) – A design object

  • max_length (int | None) – Maximum value of i for which the 𝛽* is computed. Default is None, so all length are considered.

Returns:

  • beta_star_vector (list[tuple[float | int]]) – The 𝛽* vector with tuples of 𝛽* and A_i^0 values

  • perm (list[list[int]]) – Permutation of the four-level factors associated with the 𝛽* vector

beta_wlp(max_length: int | None = None) → tuple[list[float], list[int]]#

Find the permutation of the levels of the m four-level factors that minimize the qWLP for the design.

Parameters:

max_length (int, optional) – Max word length to consider in the qWLP, by default None, all the word lengths are computed (careful as it is computationally intensive for large values of n).

Returns:

best_wlp, permutations – Returns the minimal qWLP and the corresponding permutations of the factor levels. The qWLP starts with words of length 3.

Return type:

tuple[list[float], list[int]]

clarity() → pandas.DataFrame#

Generate the clarity matrix of the design.

The clarity matrix is a table where:

  • the rows represent the type of the interactions (4-4, 4-2, 2-2,

    or any type)

  • the columns represent the type of clarity that the interactions can

    have (4-4 clear, 4-2 clear, 2-2 clear, or totally clear)

Returns:

A pandas dataframe holding the clarity matrix where the rows are [β€œ4-4”, β€œ4-2”, β€œ2-2”, β€œAny type”] and the columns are [β€œ4-4 clear”, β€œ4-2 clear”, β€œ2-2 clear”, β€œTotally clear”]

Return type:

clarity_matrix

clear(interaction_type: str, clear_from: str = 'all') → int#

Compute the number of interactions of type interaction_type that are clear from interactions of the clear_from type.

Parameters:

  • interaction_type (str) – Type of the interaction studied. Can either be β€œ4-4”, β€œ4-2”, β€œ2-2”, or β€œall” to count for all types of interaction.

  • clear_from (str) – Type of clarity to count. Can either be β€œ4-4”, β€œ4-2”, β€œ2-2”, or β€œall” to count the number of totally clear interaction.

defining_relation(raw: bool = False)#

Generate the defining relation of the design.

For each added factor, generate the word representing the added factor. Each word contains the generator + the letter representing the added factor. The pseudo-factors used to generate the four-level factors are replaced by four-level factors labels in the final words. For example, if factor A is created using pseudo-factors a, b and ab, then the replacement scheme is: a -> A1, b -> A2, and ab -> A3.

Parameters:

raw (bool, optional) – Return the relation without replacing the pseudo-factors by their four-level factor label, by default False

Returns:

Defining relation as a Relation object.

Return type:

Relation

flatten(zero_coding: bool = True) → numpy.ndarray#

Flatten each four-level factor of the design into three two-level pseudo-factors.

Parameters:

zero_coding (bool, optional) – The matrix is in 0/1 coding instead of -1/1 coding, by default True

Returns:

The flattened design containing 2*m + n two-level factors

Return type:

np.ndarray

remove_factor(number: int)#

Remove a two-level factor from the design.

Parameters:

number (int) – Column number of the factor to remove. Must correspond to one of the factor used in the design.

Returns:

A Design object containing the added two-level factor

Return type:

Design

resolution() → int | None#

Compute the resolution of the design.

tfi_clearance() → dict[str, dict[str, object]]#

Compute clarity of all two-factor interactions in the design.

There are three types of two-factor interactions in a design:

  • 4-4: interaction between two pseudo-factors of four-level factors

  • 4-2: interaction between a pseudo-factor of a four-level factor and

    a two-level factor.

  • 2-2: interaction between two two-level factors.

An interaction is called clear when it is not aliased with any other interaction of a specific type. Thus, an interaction is β€˜4-4 clear’ when it is not aliased with any 4-4 interactions, β€˜4-2 clear’ when it is not aliased with any 4-2 interactions, and β€˜2-2 clear’ when it is not aliased with any 2-2 interactions. When an interaction is 4-4 clear, 4-2 clear, and 2-2 clear, we call it a totally clear (TC)” interaction. Defining how clear is an interaction, is called the clarity of an interaction.

Returns:

  • A dictionary where each entry corresponds to an interaction of the

  • design, where the key is the name of the interaction, and the value is

  • another dictionary containing four entries –

    • β€˜clear’: the interaction is clear from main effects

    • ’4-4’: the interaction is β€˜4-4’ clear (True or False)

    • ’4-2’: the interaction is β€˜4-2’ clear (True or False)

    • ’2-2’: the interaction is β€˜2-2’ clear (True or False)

    • ’Type’: the type of the interaction, either β€˜4-4’, β€˜4-2’,

    or β€˜2-2’

twlp(type_0: bool = True, max_length: int | None = None) → list[list[int]]#

Type-specific word length pattern

Compute the type-specific word length pattern of a design, starting with words of length 3.

Parameters:

  • type_0 (bool, optional) – Return the word length pattern of type 0, by default True. If False, return the word length pattern of type m.

  • max_length (int, optional) – Max word length to display in the word length pattern, by default None, all the word lengths are displayed. If this number is more than the maximum word length of the design, ignores it.

Returns:

Type-specific word length pattern, starting with words of length 3. Each sublist give the number of words of that length, sorted by type.

Return type:

List[List[int]]

w2_wlp() → tuple[list[int], str]#

Compute the W_2 word length pattern of the design. The structure of the W_2 vector is: A3.0, A2.1, A4.0, A5.0, A3.1, A6.0, A7.0, …

Returns:

  • W2_vector (list[int]) – The vector containing the A_x.i values of the W_2 word length pattern

  • factor (str) – A string indicating which factor must be used to obtain W_2 optimal blocking. Can either be β€˜A’, β€˜B’, or β€˜C’.

wlp(max_length: int | None = None) → list[int]#

Generalized word length pattern

Compute the word length pattern, i.e., the number of words in the defining relation of the design, and arrange them by length.

Parameters:

max_length (int, optional) – Max word length to display in the word length pattern, by default None, all the word lengths are displayed. If this number is more than the maximum word length of the design, ignores it.

Returns:

Word length pattern, starting with words of length 3.

Return type:

List[int]

from_array(mat: numpy.ndarray, zero_coded: bool = True) → Design#

Create a Design object from a matrix.

Parameters:

  • mat (np.ndarray) – Design matrix

  • zero_coded (bool, optional) – The two-level factors in the design matrix are coded in 0/1, by default True.

Returns:

A Design object with the factors detected in the matrix.

Return type:

Design