Factors and Levels

class sweetpea.Factor(name, levels)

A factor for use in an experiment design.

By default Factor in SweetPea always creates a DiscreteFactor which contains a finite number of levels (Refer to ContinuousFactor for non-discrete factors). The levels of a factor can be plain Level values, any kind of non-Level value (which is implicitly coerced to a Level value), or DerivedLevel values. In the last case, the result is a derived factor. The levels list must either contain all derived levels or all values that are not derived levels, and derived levels must all use a compatible derivation as described in Derivations. The names of the levels must be distinct; create a level with a weight to get the effect of multiple levels with he same name.

Parameters:

  • name – the factor’s name

  • levels (List[Level]) – the factor’s levels

property name

The factor’s name.

Type:

str

get_level(name)

Finds a returns a level of the factor with a given name. If the factor has multiple levels with the same name, any one of them might be returned.

Indexing a factor with [] is the same as calling the get_level method.

Parameters:

name – the level’s name

Returns:

a level with the given name

Return type:

Level

property levels

Returns the factor’s levels.

Returns:

a list of levels

Return type:

List[Level]

class sweetpea.Level(name, weight=1)

A level for use in a non-derived factor. A level object can be used for only one factor.

If weight is provided as a value greater than 1, it affects how the level is used in crossings, causing it to be combined weight times with each combination of other factors’ levels in a crossing. That’s conceptually similar to having multiple levels with the same name, but as long as the level’s factor is part of a block’s crossing, the weight crossing occurrences of the level are not considered distinct. Consequently, a sampling strategy without replacement (see Gen) will produce fewer samples than it would for separate levels. Along similar lines, a DerivedLevel can have a weight greater than 1 to affect crossings, but cannot be included in a level multiple times, because each derived level’s predicate must match a different set of inputs.

For a non-derived level whose factor is not crossed (or, more generally, is not in all crossings in a MultiCrossBlock), a weight value has the same effect as duplicating the level’s name. That is, the would-be copies are treated as distinct, which means that sampling with replacement is biased toward levels with greater weight. For sampling strategies without replacement, the weight thus increases the number of samples that are considered distinct.

Parameters:

  • name – the level’s name, which can be any value

  • weight (int) – the level’s weight

Return type:

Level

property name

The level’s name, which can be any kind of value.

property factor

Returns the level’s factor. This property exists only for a Level object that is extracted from a Factor object.

Returns:

a factor

Return type:

Factor

class sweetpea.DerivedLevel(name, derivation, weight=1)

Creates a derived level, which depends on the levels of other factors in a design. All derived levels for one factor must use compatible derivations as described in Derivations.

Parameters:

  • name – the level’s name, which can be any value

  • derivation (Derivation) – a condition on other factors’ levels; see Derivations

  • weight (int) – the level’s weight

Returns:

a derived level

Return type:

Level

class sweetpea.ElseLevel(name, weight=1)

Creates a derived level that acts as an “else” case, matching any arguments that other derived levels do not match. An “else” derived level can appear only once among the levels supplied to Factor, and only in combination with other derived levels. It is compatible with any derivation described in Derivations.

Parameters:

  • name – the level’s name, which can be any value

  • weight (int) – the level’s weight

Returns:

a derived level

Return type:

Level

class sweetpea.ContinuousFactor(name, distribution)

Sweetpea also supports a ContinuousFactor for factors without finite levels, which sample continuously at runtime. This is different from DiscreteFactor that requires a finite discrete levels during its initialization. A ContinuousFactor can dynamically generate values at runtime based on the input distribution.

To initialize a ContinuousFactor, a distribution is required in order to generate values at runtime. The distribution must be an instance of a Distribution. Several built-in types are available for Distribution.

UniformDistribution Samples values from a uniform distribution within a given range.

GaussianDistribution Samples values from a normal distribution with a specified mean and standard deviation.

ExponentialDistribution Samples values from an exponential distribution with a given rate parameter.

LogNormalDistribution Samples values from a log-normal distribution with a specified mean and standard deviation.

CustomDistribution Samples values by calling a user-defined input function.

If UniformDistribution, GaussianDistribution, LogNormalDistribution, or LogNormalDistribution is used to initialize the ContinuousFactor, the factor will generate values following the corresponding distribution at runtime through ContinuousFactor.generate(). In this case the factor is always a non-derived continuousfactor.

The user can also use CustomDistribution, in which case the user needs to provide a custom func(Callable) to initialize the ContinuousFactor. The factor will then call func to generate values at runtime through ContinuousFactor.generate(). In addition, CustomDistribution can also accept an additional argument dependents that contains a list of factors that the current ContinuousFactor depends on. The list of factors can be either DiscreteFactor or ContinuousFactor in the design. In such cases, the ContinuousFactor initialized is considered a derived continuousfactor and it also suggests that func would require additional values in order to generate values at runtime. For example, when dependents constains a Factor Color in the design, the factor_values for Color needs to be passed to ContinuousFactor.generate().

If distribution is not set or recognized, an error will be raised.

Parameters:

  • name (str) – The name of the continuous factor.

  • distribution (Distribution) – A distribution used to generate values dynamically.

property name

The continuousfactor’s name.

Type:

str

generate(factor_values=[])

Generate values for the continuousfactor based on the input distribution.

Parameters:

factor_values (List[Any]) – optional factor values when generating values with CustomDistribution. The length of factor_values needs to be the same as the dependents when intializing CustomDistribution.

Returns:

the value for the factor

Return type:

Any

class sweetpea.DiscreteFactor(name, levels)

In contrast to ContinuousFactor that generate values dynamically, a DiscreteFactor takes on a finite set of distinct, separate values (or levels) during its initialization. Each level can be represented using the Level class. A DiscreteFactor is initialized using the Factor class.