Constraints

class sweetpea.Constraint

Abstract class representing a constraint.

class sweetpea.Exclude(level)

Constrains an experiment to disallow the specified level.

An Exclude constraint can affect the number of trials that are included in a sequence. See CrossBlock for more information.

Parameters:

level (Union[Level, Tuple[Factor, Any], Tuple[Factor, Level]]) – either a level, a tuple containing a factor and the name of one of its levels, or a tuple containing a factor and one of its levels

Return type:

Constraint

class sweetpea.Pin(index, level)

Constrains an experiment to require the specified level at the specified trial index. A negative trial index refers to a trial releative to the end of a sequence; for example, -1 refers to the last trial. If index is not in range for trials in an experiment, then the experiment will have no satisfying trial sequences.

Parameters:

  • index (int) – a trial index, counting forward from 0 or backward from -1

  • level (Union[Level, Tuple[Factor, Any], Tuple[Factor, Level]]) – either a level, a tuple containing a factor and the name of one of its levels, or a tuple containing a factor and one of its levels

Return type:

Constraint

class sweetpea.MinimumTrials(k)

Constrains an experiment to set the specified number of minimum trials. See CrossBlock and Repeat for more information.

Parameters:

k (int) – minimum number of trials

class sweetpea.AtMostKInARow(k, level)

Constrains an experiment to allow at most k consecutive trials with the level identified by level.

Parameters:

  • k (int) – the maximum number of consecutive repetitions to allow

  • level (Union[Level, Tuple[Factor, Any], Tuple[Factor, Level], Factor]) – either a level, a tuple containing a factor and the name of one of its levels, a tuple containing a factor and one of its levels, or just a factor; the last case is a shorthand for a separate constraint for each of the factor’s levels

Return type:

Constraint

class sweetpea.AtLeastKInARow(k, level)

Constrains an experiment so that when the level identified by level appears in a trial, it also appears in at least k-1 adjacent trials.

Parameters:
Return type:

Constraint

class sweetpea.ExactlyKInARow(k, level)

Constrains an experiment so that when the level identified by level appears in a trial, it also appears in exactly k-1 adjacent trials.

Parameters:
Return type:

Constraint

class sweetpea.ExactlyK(k, level)

Constrains an experiment so that the level identified by level appears in exactly k trials. If this constraint is not consistent with requirements for crossing, the experiment will have no satisfying trial sequences.

Parameters:
Return type:

Constraint

class sweetpea.Sequential(factor)

Constrains the experiment so that the levels of factor must appear in order over a sequence of trials. When the last level of factor is used for a trial, the next trial starts the sequence again with the first level of factor.

Parameters:

factor (Factor) – the factor to constrain to seqential use of its levels in an experiment

Return type:

Constraint

class sweetpea.LatinSquare(factors)

Constrains an experiment so that the levels of factors are combied in a Latin Square pattern. If the factor in factors with the most levels has N levels, then every N trials will include every level of every factor in factors. Furthermore, each subsequent sequence of N trials will have a distinct possible combination of levels until all possibilities are exhausted, and the combination order is deterministic.

The given factors are typically crossed in an experiment description, but they are not required to be crossed explicitly; a LatinSquare constraint effectivley forces a crossing as long as an experiment includes enough trials.

See Latin Square Counterbalancing for more information.

Parameters:

factors (List[Factor]) – the factors forming the Latin Square pattern

Return type:

Constraint

class sweetpea.ContinuousConstraint(factors, predicate)

Constrains ContinuousFactor in an experiment so that the samples generated for these factors meet the proposed constraint function. Since such constraints only apply to factors with continuous sampling functions that should not be included in the crossing, the experiment will sample these factors until the constraints are met after the trial sequences have been satified for discrete factors.

Parameters:

  • factors (List[ContinuousFactor]) – the factors to add constraints on

  • predicate (Callable[[Any, ...], bool]) – a constraint function takes factors initialized with sampling function. The function should return true if the combination of factors meet the constraints.

Return type:

Constraint