sweetpea.primitives module¶

This module provides the fundamental primitives used by the SweetPea domain-specific language.

A Note on Deprecations¶

A number of functions, classes, methods, and attributes in this file are marked as deprecated. These are preserved for backwards compatibility, but will eventually be removed in favor of alternative forms.

class sweetpea.primitives.Level(*_, **__)¶

Bases: object

A discrete value that a Factor can hold.

Note

Do not directly instantiate Level. Instead, construct one of the subclasses:

SimpleLevel
DerivedLevel
ElseLevel

For more on levels, consult the guide.

name: str¶: The name of the level.

internal_name: str¶: The internal name, which is meant to be unique among levels.

Deprecated since version 0.1.0: This attribute will be removed. It should not be used outside of this module.

factor: sweetpea.primitives.Factor¶: The factor to which this level belongs.

property weight: int¶: The level’s weight.

property external_name: str¶: An alias for Level.name.

Deprecated since version 0.1.0: This property will be removed in favor of Level.name.

class sweetpea.primitives.SimpleLevel(*_, **__)¶

Bases: sweetpea.primitives.Level

A simple Level, which only has a name.

For example, in a simple Stroop experiment, a color Factor may consist of a few simple levels such as red, blue, and green.

Parameters: name – The name of the level.

weight: dataclasses.InitVar = 1¶

class sweetpea.primitives.DerivedLevel(*_, **__)¶

Bases: sweetpea.primitives.Level

A Level representing the intersection of other levels, potentially from different Factors. These are produced through use of DerivationWindows, which are constraints on level selection during trial sampling.

For more information on when to use derived levels, consult the Derivations section of the SweetPea guide.

Parameters

name – The name of the level.
window – A DerivationWindow used in producing a cross product of this level.

window: sweetpea.primitives.DerivationWindow¶: The derivation window corresponding to this level.

weight: dataclasses.InitVar = 1¶

get_dependent_cross_product()¶

Produces a list of n-tuples, where each tuple represents a unique combination of Level selections among all possibilities.

For instance, if we have two Factors, each with some Levels:

Factor	Levels
color	red, blue, green
value	1, 2

Then the following list of tuples is returned:

[(red, 1),
 (red, 2),
 (blue, 1),
 (blue, 2),
 (green, 1),
 (green, 2)]

Tip

You can access a Level’s corresponding Factor via the Level.factor attribute.

Return type: typing.List[typing.Tuple[Level, …]]

class sweetpea.primitives.ElseLevel(*_, **__)¶

Bases: sweetpea.primitives.Level

A Level for… something.

Parameters: name – The name of the level.

weight: dataclasses.InitVar = 1¶

derive_level_from_levels(other_levels)¶

Converts the ElseLevel into a DerivedLevel by combining it with other specified DerivedLevels.

Parameters: other_levels (List[sweetpea.primitives.DerivedLevel]) – A list of DerivedLevels for use in constructing the new level.
Return type: sweetpea.primitives.DerivedLevel

class sweetpea.primitives.Factor(name, initial_levels, *_, **__)¶

Bases: object

An independent variable in a factorial experiment. Factors are composed of Levels and come in two flavors:

SimpleFactor
DerivedFactor

However, both classes can be implicitly constructed by the base Factor constructor, so we recommend you always use that for creating factors.

During Factor construction, the first Level in the initial_levels is dynamically type-checked. If it’s a DerivedLevel or ElseLevel, a .DerivedFactor will be initialized. Otherwise, a .SimpleFactor will be initialized.

In all cases, the initial_levels will be processed. This step ensures that all of a factor’s levels will always be Levels. The levels are processed according to these rules:

A Level instance is left alone.
A str instance is converted into a SimpleLevel.
A tuple or list consisting of exactly one str followed by one int will be converted into a SimpleLevel with the str as its name and the int as its weight.
Anything else is converted into a SimpleLevel by using its string representation as a level name.

Note

The DerivedFactor subclass does additional processing after these steps.

Parameters

name (str) – The name of this factor.
initial_levels (typing.Sequence[Any]) – The levels comprising this factor. The list can be made of anything, but any values in the list that are not instances of Level or one of its subclasses will be converted into SimpleLevel instances by using their string representation, as determined by SimpleLevel(str(value)).

Return type

Factor

Tip

See the Factorial Experiment Design section of the SweetPea guide for more about factors, levels, and how to use them.

name: str¶: The name of this factor.

initial_levels: dataclasses.InitVar¶: The levels used during factor initialization.

levels: Sequence[sweetpea.primitives.Level]¶: The discrete values that this factor can have.

get_level(name)¶

Returns a Level instance corresponding to the given name, if it exists within this factor. Otherwise, returns None.

Parameters: name (str) –
Return type: Optional[sweetpea.primitives.Level]

property first_level: sweetpea.primitives.Level¶: The first Level in this factor.

is_derived()¶

Whether this factor is derived.

Deprecated since version 0.1.0: Instead of using this function, we recommend doing a dynamic type check with isinstance(). This provides the same semantic information to the programmer while also providing greater type guarantees when using a static type checker, such as mypy.

factor: Factor = ...
if isinstance(factor, DerivedFactor):
    # Code requiring a derived factor.
    ...
else:
    # Code if it's not a derived factor.
    ...

Return type: bool

property has_complex_window: bool¶

Whether this factor has a complex derivation window.

A complex derivation window is a window of derived factors whose first-level derivations are themselves considered complex.

applies_to_trial(trial_number)¶

Whether this factor applies to the given trial. For example, factors with TransitionDerivation derivations in their levels do not apply to trial number 1, but do apply to all subsequent trials.

Tip

Trials start their numbering at 1.

Parameters: trial_number (int) –
Return type: bool

property factor_name: str¶: An alias for Factor.name for backwards compatibility.

Deprecated since version 0.1.0: This property will be removed in favor of Factor.name.

has_level(name)¶

Whether the given level name corresponds to a level in this factor.

Deprecated since version 0.1.0: This method will be removed in favor of straightforward membership checks, such as:

factor: Factor = ...
if 'level_name' in factor:
    ...

Parameters: name (str) –
Return type: bool

class sweetpea.primitives.SimpleFactor(name, initial_levels, *_, **__)¶

Bases: sweetpea.primitives.Factor

A Factor comprised of SimpleLevels. If a subclass of Level is passed in that is not a SimpleLevel, an error is raised during initialization.

Parameters

name (str) – The name of this factor.
initial_levels (typing.Sequence[SimpleLevel]) – The levels comprising this factor.

Return type

SimpleFactor

levels: Sequence[sweetpea.primitives.SimpleLevel]¶: The discrete values that this factor can have.

get_level(name)¶

Returns a Level instance corresponding to the given name, if it exists within this factor. Otherwise, returns None.

Parameters: name (str) –
Return type: Optional[sweetpea.primitives.SimpleLevel]

property first_level: sweetpea.primitives.SimpleLevel¶: The first Level in this factor.

class sweetpea.primitives.DerivedFactor(name, initial_levels, *_, **__)¶

Bases: sweetpea.primitives.Factor

A Factor composed of DerivedLevels.

After doing the level processing described by Factor, an additional step is taken: all ElseLevels are converted into DerivedLevels. This is done by calling ElseLevel.derive_level_from_levels(), supplying all the natural DerivedLevels that were passed in.

Parameters

name (str) – The name of this factor.
initial_levels (typing.Sequence[typing.Union[DerivedLevel, ElseLevel]]) –
The levels comprising this factor. The levels may be instances of either DerivedLevels or ElseLevels.

Note

Any given ElseLevel will be converted to a DerivedLevel by way of ElseLevel.derive_level_from_levels(), so that the Factor.levels list will only contain DerivedLevels.

Return type

DerivedFactor

levels: Sequence[sweetpea.primitives.DerivedLevel]¶: The discrete values that this factor can have.

get_level(name)¶

Returns a Level instance corresponding to the given name, if it exists within this factor. Otherwise, returns None.

Parameters: name (str) –
Return type: Optional[sweetpea.primitives.DerivedLevel]

property first_level: sweetpea.primitives.DerivedLevel¶: The first Level in this factor.

class sweetpea.primitives.DerivationWindow(predicate, factors, width, stride)¶

Bases: object

A mechanism to specify the window of a derivation. Derivation windows are used to inform a derivation based on levels from other factors in the current trial and, potentially, multiple preceding trials.

For detailed information, see the SweetPea guide’s section on derivation.

Parameters

predicate (typing.Callable[[Any, ...], bool]) –
A predicate function used during derivation. Different derivation windows require different forms of predicates.

Warning

The type of arguments passed to the predicate varies by Derivation subclass. Read their documentation carefully!
factors (typing.Sequence[Factor]) – The factors upon which this derivation window depends.
width (int) – The number of trials that this derivation window depends upon. The current trial must be included, so the number must be greater than or equal to 1.
stride (int) – TODO DOC

Return type

None

predicate: Callable¶: The predicate used during derivation with this window.

factors: List[sweetpea.primitives.Factor]¶: The factors upon which this derivation depends.

width: int¶: The width of this window.

stride: int¶: The stride of this window.

initial_factor_count: int¶: The number of factors that originally came in, disregarding any expansion caused by a DerivedLevel changing things.

property size: Tuple[int, int]¶

The width and stride of this derivation window as a pair.

Return type: typing.Tuple[int, int]

property first_factor: sweetpea.primitives.Factor¶

The first Factor in the internal list of Factors.

Return type: Factor

property is_complex: bool¶

Whether this derivation window is considered complex. A complex derivation windowis one for which at least one of the following is true:

The window’s width is greater than 1.
The window’s stride is greater than 1.
The window’s first_factor is a complex derived factor.

Return type: bool

property args: List[sweetpea.primitives.Factor]¶

An alias for DerivationWindow.factors.

Return type: typing.List[Factor]

Deprecated since version 0.1.0: This property will be removed in favor of DerivationWindow.factors.

property fn: Callable¶

An alias for DerivationWindow.predicate.

Return type: Callable

Deprecated since version 0.1.0: This property will be removed in favor of DerivationWindow.predicate.

class sweetpea.primitives.WithinTrialDerivationWindow(predicate, factors)¶

Bases: sweetpea.primitives.DerivationWindow

A derivation window that depends on levels from other factors, all within the same trial.

Parameters

predicate (typing.Callable[[str, ...], bool]) – A predicate that takes as many strs as factors in this derivation window, where each str will be the name of a factor.
factors (typing.Sequence[Factor]) – The factors upon which this derivation window depends.

Return type

None

width: int = 1¶: The width of this window.

stride: int = 1¶: The stride of this window.

class sweetpea.primitives.TransitionDerivationWindow(predicate, factors)¶

Bases: sweetpea.primitives.DerivationWindow

A derivation window that depends on levels from other factors in the current trial and the immediately preceding trial. TransitionDerivations are used to constrain the transition points between trials.

Parameters

predicate (typing.Callable[[typing.Sequence[Factor], ...], bool]) – A predicate that takes as many lists of factors as factors in this derivation window.
factors (typing.Sequence[Factor]) – The factors upon which this derivation window depends.

Return type

None

width: int = 2¶: The width of this window.

stride: int = 1¶: The stride of this window.

sweetpea.primitives.get_external_level_name(level)¶

Returns Level.name.

Deprecated since version 0.1.0: This function will be removed in favor of Level.name.

Parameters: level (sweetpea.primitives.Level) –
Return type: str

sweetpea.primitives.get_internal_level_name(level)¶

Returns Level.internal_name.

Deprecated since version 0.1.0: This function will be removed. It should not be used outside of this module.

Parameters: level (sweetpea.primitives.Level) –
Return type: str

sweetpea.primitives.WithinTrial¶

An alias for WithinTrialDerivationWindow.

Deprecated since version 0.1.0: This class will be removed in favor of WithinTrialDerivationWindow.

alias of sweetpea.primitives.WithinTrialDerivationWindow

sweetpea.primitives.Transition¶

An alias for TransitionDerivationWindow.

Deprecated since version 0.1.0: This class will be removed in favor of TransitionDerivationWindow.

alias of sweetpea.primitives.TransitionDerivationWindow

sweetpea.primitives.Window¶

An alias for DerivationWindow.

Deprecated since version 0.1.0: This class will be removed in favor of DerivationWindow.

alias of sweetpea.primitives.DerivationWindow

sweetpea.primitives.simple_level(name, weight=None)¶

A function alias for SimpleLevel.

Deprecated since version 0.1.2: This function will be removed in favor of direct instantiation of SimpleLevel.

Parameters

name (str) – The name of the level.
weight (Optional[int]) – An optional weight for the level.

Return type

sweetpea.primitives.SimpleLevel

sweetpea.primitives.derived_level(name, derivation, weight=None)¶

A function alias for DerivedLevel.

Deprecated since version 0.1.2: This function will be removed in favor of direct instantiation of DerivedLevel.

Parameters

name (str) – The name of the level.
derivation (sweetpea.primitives.DerivationWindow) – The derivation window for this level.
weight (Optional[int]) – An optional weight for the level.

Return type

sweetpea.primitives.DerivedLevel

sweetpea.primitives.else_level(name, weight=None)¶

A function alias for ElseLevel.

Deprecated since version 0.1.2: This function will be removed in favor of direct instantiation of ElseLevel.

Parameters

name (str) – The name of the level.
weight (Optional[int]) – An optional weight for the level.

Return type

sweetpea.primitives.ElseLevel

sweetpea.primitives.factor(name, levels)¶

A function alias for Factor.

Deprecated since version 0.1.2: This function will be removed in favor of direct instantiation of Factor.

Parameters

name (str) – The name of the factor.
levels (Sequence[Any]) – A sequence of levels for the factor.

Return type

sweetpea.primitives.Factor

sweetpea.primitives.within_trial(fn, args)¶

A function alias for WithinTrialDerivationWindow.

Deprecated since version 0.1.2: This function will be removed in favor of direct instantiation of WithinTrialDerivationWindow.

Parameters

fn (Callable) – A predicate function. See WithinTrialDerivationWindow.
args (List[sweetpea.primitives.Factor]) – A list of Factors. See WithinTrialDerivationWindow.

Return type

sweetpea.primitives.WithinTrialDerivationWindow

sweetpea.primitives.transition(fn, args)¶

A function alias for TransitionDerivationWindow.

Deprecated since version 0.1.2: This function will be removed in favor of direct instantiation of TransitionDerivationWindow.

Parameters

fn (Callable) – A predicate function. See TransitionDerivationWindow.
args (List[sweetpea.primitives.Factor]) – A list of Factors. See TransitionDerivationWindow.

Return type

sweetpea.primitives.TransitionDerivationWindow

sweetpea.primitives.window(fn, args, width, stride)¶

A function alias for DerivationWindow.

Deprecated since version 0.1.2: This function will be removed in favor of direct instantiation of DerivationWindow.

Parameters

fn (Callable) – A predicate function. See DerivationWindow.
args (List[sweetpea.primitives.Factor]) – A list of Factors. See DerivationWindow.
width (int) – The width of the window.
stride (int) – The stride of the window.

Return type

sweetpea.primitives.DerivationWindow