sweetpea.blocks module

This module provides the various kinds of blocks that can be used to create a factorial experimental design.

class sweetpea.blocks.Block(design, crossing, constraints, require_complete_crossing, cnf_fn)

Bases: object

Abstract class for Blocks. Contains the required data, and defines abstract methods that other blocks _must_ implement in order to work correctly.

Parameters

• design (List[Factor]) –

• crossing (List[List[Factor]]) –

• constraints (List[Constraint]) –

extract_basic_factor_names(level)

Parameters

level (DerivedLevel) –

Return type

set

abstract trials_per_sample()

Indicates the number of trials that are generated per sample for this block configuration.

Analogous to the old __fully_cross_size function.

abstract variables_per_trial()

Indicates the number of variables that are present in each trial.

Analogous to the old __design_size function.

abstract grid_variables()

Indicates the number of variables that are present in the core variable grid. this does not include variables used to encode complex windows.

In a design without complex windows, this is equivalent to Block.variables_per_sample().

variables_per_sample()

Indicates the total number of variables needed to encode the core experiment description.

Alternatively stated, this returns the number of variables in the formula that constitute the independent support.

variables_for_factor(f)

Indicates the number of variables needed to encode this factor.

Parameters

f (Factor) –

Return type

int

has_factor(factor)

Determines whether a given factor is in this block.

Parameters

factor (Factor) –

Return type

Factor

first_variable_for_level(factor, level)

Returns the first index for this variable in a trial sequence representing the given factor and level. (0-based.)

Parameters

• factor (Factor) –

• level (Any) –

Return type

int

factor_variables_for_trial(f, t)

Given a factor and a trial number (1-based) this function will return a list of the variables representing the levels of the given factor for that trial. The variable list is also 1-based.

Parameters

• f (Factor) –

• t (int) –

Return type

List[int]

variable_list_for_trial(t)

Given a trial number (1-based) this function will return a list of lists of the variables that pertain to that trial.

For example, for stroop-2 with a congruency level, this method would return the following for trial 1:

[[1, 2], [3, 4], [5, 6]]

If a transition were involved, and it didn’t apply to level one, then the factor would have an empty list:

[[1, 2], [3, 4], []]

Parameters

t (int) –

Return type

List[List[int]]

decode_variable(variable)

Given a variable number from the SAT formula, this method will return the associated factor and level name.

Parameters

variable (int) –

Return type

Tuple[Factor, Union[SimpleLevel, DerivedLevel]]

is_excluded(c, d)

Given crossing and design-only variables and returns true if the combination meets any of the exclude contraints.

Parameters

• c (Tuple[int, ...]) –

• d (Tuple[int, ...]) –

Return type

bool

filter_excluded_derived_levels(l)

Given a list of trials, the function filters the trials invalid as per the exclude contraints.

Parameters

l (List[List[List[Tuple[int, ...]]]]) –

Return type

List[List[List[Tuple[int, …]]]]

build_backend_request()

Apply all constraints to build a BackendRequest. Formerly known as __desugar.

Return type

BackendRequest

get_variable(trial_number, level)

Given a trial number (1-based), factor, and level, this method will return the SAT variable that represents that selection. Only works for factors without complex windows at the moment.

Parameters

• trial_number (int) –

• level (Tuple[Factor, Any]) –

Return type

int

build_variable_list(level_pair)

Given a specific level (factor + level pair), this method will return the list of variables that correspond to that level in each trial in the encoding.

Parameters

level_pair (Tuple[Factor, Union[SimpleLevel, DerivedLevel]]) –

Return type

List[int]

factor_in_crossing(factor)

rearrage_samples(samples, results)

calculate_samples_required(samples)

class sweetpea.blocks.FullyCrossBlock(design, crossing, constraints, require_complete_crossing=True, cnf_fn=<function to_cnf_tseitin>)

Bases: Block

A fully-crossed block. This block generates as many trials as needed to fully cross all levels across all factors in the block’s crossing.

trials_per_sample()

Indicates the number of trials that are generated per sample for this block configuration.

Analogous to the old __fully_cross_size function.

variables_per_trial()

Indicates the number of variables that are present in each trial.

Analogous to the old __design_size function.

grid_variables()

Indicates the number of variables that are present in the core variable grid. this does not include variables used to encode complex windows.

In a design without complex windows, this is equivalent to Block.variables_per_sample().

crossing_size()

crossing_size_without_exclusions()

draw_design_graph()

factor_in_crossing(factor)

class sweetpea.blocks.MultipleCrossBlock(design, crossing, constraints, require_complete_crossing=True, cnf_fn=<function to_cnf_tseitin>)

Bases: Block

A multiple-crossed block. This block generates as many trials as needed tocross the levels across factors mentioned as lists in the block’s crossing.

trials_per_sample()

Indicates the number of trials that are generated per sample for this block configuration.

Analogous to the old __fully_cross_size function.

variables_per_trial()

Indicates the number of variables that are present in each trial.

Analogous to the old __design_size function.

grid_variables()

Indicates the number of variables that are present in the core variable grid. this does not include variables used to encode complex windows.

In a design without complex windows, this is equivalent to Block.variables_per_sample().

crossing_size()

crossing_size_without_exclusions()

draw_design_graph()

factor_in_crossing(factor)