sweetpea package

The sweetpea module provides the SweetPea domain-specific programming language. The SweetPea language allows for the specification of randomized experimental designs and the synthesis of trial sequences from those designs.

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

Returns a fully crossed Block meant to be used in experiment synthesis. This is the preferred mechanism for describing an experiment.

Parameters

  • design (List[sweetpea.primitives.Factor]) – A list of all the Factors in the design. When a sequence of trials is generated, each trial will have one level from each factor in design.

  • crossing (List[sweetpea.primitives.Factor]) –

    A list of Factors used to produce crossings. The number of trials in each run of the experiment is determined as the product of the number of levels of factors in crossing.

    If require_complete_crossing is False, the constraints can reduce the total number of trials.

    Different trial sequences of the experiment will have different combinations of levels in different orders. The factors in crossing supply an implicit constraint that every combination of levels in the cross should appear once. Derived factors impose additional constraints: only combinations of levels that are consistent with derivations can appear as a trial. Additional constraints can be manually imposed via the constraints parameter.

  • constraints (List[sweetpea.base_constraint.Constraint]) – A list of Constraints that restrict the generated trials.

  • require_complete_crossing – Whether every combination in crossing must appear in a block of trials. True by default. A False value is appropriate if combinations are excluded through an Exclude Constraint.

  • cnf_fn – A CNF conversion function. Default is to_cnf_tseitin().

Return type

sweetpea.blocks.Block

sweetpea.multiple_cross_block(design, crossings, constraints, require_complete_crossing=True, cnf_fn=<function to_cnf_tseitin>)

Returns a Block with multiple crossings, meant to be used in experiment synthesis. Similar to fully_cross_block(), except it can be configured with multiple crossings.

Parameters

  • design (List[sweetpea.primitives.Factor]) – A list of all the Factors in the design. When a sequence of trials is generated, each trial will have one level from each factor in design.

  • crossings (List[List[sweetpea.primitives.Factor]]) –

    A list of lists of Factors representing crossings. The number of trials in each run of the experiment is determined by the maximum product among the number of levels in the crossings.

    Every combination of levels in each individual crossing in crossings appears at least once. Different crossings can refer to the same factors, which constrains how factor levels are chosen across crossings.

  • constraints (List[sweetpea.base_constraint.Constraint]) – A list of Constraints that restrict the generated trials.

  • require_complete_crossing – Whether every combination in crossings must appear in a block of trials. True by default. A False value is appropriate if combinations are excluded through an Exclude Constraint.

  • cnf_fn – A CNF conversion function. Default is to_cnf_tseitin().

Return type

sweetpea.blocks.Block

sweetpea.simplify_experiments(experiments)

Converts a list of experiments into a list of lists of tuples, where each tuple represents a crossing in a given experiment.

Parameters

experiments (List[Dict]) – A list of experiments as dicts. These are produced by calls to any of the synthesis functions (synthesize_trials(), synthesize_trials_non_uniform(), or synthesize_trials_uniform()).

Returns

A list of lists of tuples of strings, where each sub-list corresponds to one of the experiments, each tuple corresponds to a particular crossing, and each string is the simple surface name of a level.

Return type

List[List[Tuple[str, …]]]

sweetpea.print_experiments(block, experiments)

Displays the generated experiments in a human-friendly form.

Parameters
sweetpea.tabulate_experiments(experiments, factors=None, trials=None)

Tabulates and prints the given experiments in a human-friendly form. Outputs a table that shows the absolute and relative frequencies of combinations of factor levels.

Parameters
sweetpea.experiment_to_csv(experiments, file_prefix='experiment')

Exports a list of experiments to CSV files. Each experiment will be saved to a separate .csv file.

Parameters
sweetpea.synthesize_trials_non_uniform(block, samples)

Synthesizes experimental trials with non-uniform sampling. See synthesize_trials() for more information.

Note

This function is built to circumvent some shortcomings in the Unigen solving engine. Specifically, it works by taking the following steps:

  1. Find a solution to the given formula.

  2. Add that solution to the formula to exclude the solution in subsequent attempts.

  3. Repeat as needed.

This is not an ideal method of handling this problem, so it should be replaced at some point if we find a better way around Unigen’s limitations.

Parameters
Returns

A list of trial sets. Each set is represented as a dictionary mapping each factor name to a list of levels, where each such list contains to one level per trial.

Return type

List[dict]

sweetpea.synthesize_trials_uniform(block, samples)

Synthesizes experimental trials with uniform sampling. See synthesize_trials() for more information.

Parameters
Returns

A list of trial sets. Each set is represented as a dictionary mapping each factor name to a list of levels, where each such list contains to one level per trial.

Return type

List[dict]

sweetpea.synthesize_trials(block, samples=10, sampling_strategy=<class 'sweetpea.sampling_strategies.non_uniform.NonUniformSamplingStrategy'>)

Given an experiment described with a Block, randomly generates multiple sets of trials for that experiment.

The number of trials in each set is determined by the experiment’s crossing. Each trial is a combination of levels, subject to constraints imposed both implicitly and explicitly in the experimental description.

This function should be used on the Block produced by either fully_cross_block() or multiple_cross_block(). Using that Block, synthesize_trials() will produce a single cohesive CNF formula that will be solved with Unigen. The result of this solution is then decoded into something that is both human-readable and compatible with PsyNeuLink.

Warning

Effective uniform sampling is a work in progress, so straightforward use of this function may result in non-termination. If this happens, you can try to get some initial results via synthesize_trials_non_uniform().

Parameters

  • block (sweetpea.blocks.Block) – An experimental description as a Block.

  • samples (int) –

    The number of trial sets to generate. For example, a value of 1 produces a list of length 1, which contains a single set of trials with a random ordering of the crossings that satisfies the given constraints.

    Default is 10.

  • sampling_strategy – The strategy to use for trial generation. The default is NonUniformSamplingStrategy.

Returns

A list of trial sets. Each set is represented as a dictionary mapping each factor name to a list of levels, where each such list contains to one level per trial.

Return type

List[dict]

sweetpea.save_cnf(block, filename)

Generates a CNF formula from a Block and then writes that CNF formula to the indicated file in the Unigen-specific DIMACS format.

Parameters

  • block (sweetpea.blocks.Block) – A description of a CNF formula as a Block.

  • filename (str) – The name of the file to write the CNF formula to.