Dense¶

class psynet.trial.dense.AXBTrial(*args, **kwargs)[source]¶

Bases: PairedStimulusTrial

Defines an AXB paradigm. Each trial is built from a pair of stimuli located in a random region of the stimulus space. These stimuli are designated “original” and “altered” respectively, and are always separated by a distance of delta in the stimulus space, where delta is defined within the DenseNode object’s definition dictionary.

Each trial in an AXB paradigm takes one of two forms, “AAB” or “ABB”, where the forms dictate the order of presentation of the stimuli, specifically their repetition structure. Put explicitly, “AAB” means the participant hears the same stimulus twice followed by a different stimulus, whereas “ABB” means that the participant hears one stimulus once followed by a different stimulus which is then repeated. If “A” is the “original” stimulus, then “B” will be the “altered” stimulus; however, it is equivalently possible for “A” to be the “altered” stimulus, in which case “B” will then be the “original” stimulus.

The user is responsible for implementing an appropriate show_trial() method, which should make use of the following automatically generated entries within the Trial’s definition attribute:

locations:: A dictionary of the form {"original": [a, b], "altered": [c, d]}, providing the locations of the original and the altered stimuli respectively.
order:: A list providing the order of the original and altered stimuli. Valid values are: * [“original”, “original”, “altered”] (here, the correct answer would be “AAB”) * [“altered”, “altered”, “original”] (here, the correct answer would be “AAB”) * [“original”, “altered”, “altered”] (here, the correct answer would be “ABB”) * [“altered”, “original”, “original”] (here, the correct answer would be “ABB”)
correct_answer:: The correct answer; will be either AAB or ABB.

The show_trial() method should return either AAB or ABB as the answer.

complete¶: whether the info is ‘complete’, i.e. has received its contents

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

failed¶: boolean indicating whether the Network has failed which prompts Dallinger to ignore it unless specified otherwise. Objects are usually failed to indicate something has gone wrong.

failed_reason¶: an optional reason the object was failed. If the object is failed as part of a cascading failure triggered from another object, the chain of objects will be captured in this field.

finalize_definition(definition, experiment, participant)[source]¶

This can be overridden to add additional randomized trial properties. For example:

definition["bass_note"] = random.sample(10)

It can also be used to add FastFunctionAssets:

self.add_assets({
    "audio": FastFunctionAsset(
        function=synth_stimulus,
        extension=".wav",
    )

id¶: a unique number for every entry. 1, 2, 3 and so on…

network¶: the network the info is in

network_id¶: the id of the network the info is in

origin¶: the Node that created the info.

origin_id¶: the id of the Node that created the info

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

show_trial(experiment, participant)[source]¶

Returns a Page object, or alternatively a list of such objects, that solicits an answer from the participant.

Parameters:

experiment – An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.
participant – An instantiation of psynet.participant.Participant, corresponding to the current participant.

time_of_death¶: the time at which failing occurred

type¶: a String giving the name of the class. Defaults to “info”. This allows subclassing.

vars¶

class psynet.trial.dense.DenseNode(*args, **kwargs)[source]¶

Bases: StaticNode

Defines a DenseNode within the dense experiment paradigm.

definition: A dictionary defining the key attributes of the DenseNode. The values in this dictionary will be propagated to the dictionary attribute of the resulting DenseTrial objects, and can be used to customize the display of these items (e.g., changing the instructions to the participant). Crucially, this dictionary must contain an item called “dimensions”, corresponding to a list of Dimension objects which combine to define the stimulus space.
participant_group: The associated participant group. Defaults to a common participant group for all participants.
block: The associated block. Defaults to a single block for all trials. Use this in combination with choose_block_order() to manipulate the order in which Conditions are presented to participants.

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

failed¶: boolean indicating whether the Network has failed which prompts Dallinger to ignore it unless specified otherwise. Objects are usually failed to indicate something has gone wrong.

failed_reason¶: an optional reason the object was failed. If the object is failed as part of a cascading failure triggered from another object, the chain of objects will be captured in this field.

id¶: a unique number for every entry. 1, 2, 3 and so on…

network¶: the network the node is in

network_id¶: the id of the network that this node is a part of

participant¶: the participant the node is associated with

participant_id¶: the id of the participant whose node this is

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

time_of_death¶: the time at which failing occurred

type¶: A String giving the name of the class. Defaults to node. This allows subclassing.

vars¶

class psynet.trial.dense.DenseTrial(*args, **kwargs)[source]¶

Bases: StaticTrial

This trial class is important for defining the behavior of the dense experiment. Ordinarily one will not use this class directly, but will instead use one of the built-in subclasses, for example SingleStimulusTrial, SliderCopyTrial, PairedStimulusTrial, SameDifferentTrial, or AXBTrial.

Parameters:

condition – The DenseNode object to which the trial belongs.
n_dimensions – The number of dimensions of the stimulus space.

complete¶: whether the info is ‘complete’, i.e. has received its contents

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

failed¶: boolean indicating whether the Network has failed which prompts Dallinger to ignore it unless specified otherwise. Objects are usually failed to indicate something has gone wrong.

failed_reason¶: an optional reason the object was failed. If the object is failed as part of a cascading failure triggered from another object, the chain of objects will be captured in this field.

id¶: a unique number for every entry. 1, 2, 3 and so on…

network¶: the network the info is in

network_id¶: the id of the network the info is in

origin¶: the Node that created the info.

origin_id¶: the id of the Node that created the info

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

time_of_death¶: the time at which failing occurred

type¶: a String giving the name of the class. Defaults to “info”. This allows subclassing.

vars¶

class psynet.trial.dense.DenseTrialMaker(*, id_, trial_class, conditions, expected_trials_per_participant, max_trials_per_participant=<class 'psynet.utils.NoArgumentProvided'>, max_trials_per_block=None, recruit_mode=None, target_n_participants=None, target_trials_per_condition=None, balance_across_nodes=True, check_performance_at_end=False, check_performance_every_trial=False, fail_trials_on_premature_exit=True, fail_trials_on_participant_performance_check=True, n_repeat_trials=0)[source]¶

Bases: StaticTrialMaker

This is a trial maker for ‘dense’ experiment paradigms. A ‘dense’ paradigm is one where we have a continuous stimulus space parametrized by a finite number of dimensions, for example color which can be parametrized by R, G, and B values. The experiment then works by densely sampling stimuli from this space.

The trial maker class is paired with a particular DenseTrial class. This DenseTrial class is important for determining the precise nature of the dense experiment paradigm. If each trial corresponds to a random sample from the stimulus space – for example, in a dense rating experiment – we would use the SingleStimulusTrial class. More complex trial classes are available that involve multiple locations in the stimulus space, for example SameDifferentTrial for same-different paradigms and AXBTrial for AXB paradigms.

The user must also specify a ConditionList, which contains a list of DenseNode objects. These different DenseNode objects are used for specifying the different classes of stimuli seen by the participant. A given participant will typically receive trials from a variety of Conditions over the course of the trial maker. By default, the different Conditions will be randomly interspersed with one another; however, it is also possible to assign different Conditions to different blocks, so as to constrain the order of their presentation to the participant.

The user may also override the following methods, if desired:

choose_block_order(); chooses the order of blocks in the experiment. By default the blocks are ordered randomly.
choose_participant_group();
only relevant if the trial maker uses nodes with non-default participant groups. In this case the experimenter is expected to supply a function that takes participant as an argument and returns the chosen participant group for that trial maker.
on_complete(), run once the sequence of trials is complete.
performance_check(); checks the performance of the participant with a view to rejecting poor-performing participants.
compute_performance_reward(); computes the final performance reward to assign to the participant.

Further customisable options are available in the constructor’s parameter list, documented below.

Parameters:

id – A unique ID for the trial maker.
trial_class – The class object for trials administered by this maker (should subclass DenseTrial).
conditions (List[DenseNode]) – Defines a collection of conditions to be administered to the participants.
recruit_mode (Optional[str]) – Selects a recruitment criterion for determining whether to recruit another participant. The built-in criteria are "n_participants" and "n_trials".
target_n_participants (Optional[int]) – Target number of participants to recruit for the experiment. All participants must successfully finish the experiment to count towards this quota. This target is only relevant if recruit_mode="n_participants".
max_trials_per_block (Optional[int]) – Determines the maximum number of trials that a participant will be allowed to experience in each block, including failed trials. Note that this number does not include repeat trials.
max_trials_per_participant (Optional[int]) – Maximum number of trials that each participant may complete; once this number is reached, the participant will move on to the next stage in the timeline.
balance_across_nodes (bool) – If True (default), active balancing across participants is enabled, meaning that node selection favours nodes that have been presented fewest times to any participant in the experiment, excluding failed trials.
check_performance_at_end (bool) – If True, the participant’s performance is evaluated at the end of the series of trials. Defaults to False. See performance_check() for implementing performance checks.
check_performance_every_trial (bool) – If True, the participant’s performance is evaluated after each trial. Defaults to False. See performance_check() for implementing performance checks.
fail_trials_on_premature_exit (bool) – If True, a participant’s trials are marked as failed if they leave the experiment prematurely. Defaults to True.
fail_trials_on_participant_performance_check (bool) – If True, a participant’s trials are marked as failed if the participant fails a performance check. Defaults to True.
n_repeat_trials (int) – Number of repeat trials to present to the participant. These trials are typically used to estimate the reliability of the participant’s responses. Repeat trials are presented at the end of the trial maker, after all blocks have been completed. Defaults to 0.

check_timeout_interval_sec¶

How often to check for trials that have timed out, in seconds (default = 30). Users are invited to override this.

Type:: float

response_timeout_sec¶

How long until a trial’s response times out, in seconds (default = 60) (i.e. how long PsyNet will wait for the participant’s response to a trial). This is a lower bound on the actual timeout time, which depends on when the timeout daemon next runs, which in turn depends on check_timeout_interval_sec. Users are invited to override this.

Type:: float

async_timeout_sec¶

How long until an async process times out, in seconds (default = 300). This is a lower bound on the actual timeout time, which depends on when the timeout daemon next runs, which in turn depends on check_timeout_interval_sec. Users are invited to override this.

Type:: float

network_query¶

An SQLAlchemy query for retrieving all networks owned by the current trial maker. Can be used for operations such as the following: self.network_query.count().

Type:: sqlalchemy.orm.Query

n_networks¶

Returns the number of networks owned by the trial maker.

Type:: int

networks¶

Returns the networks owned by the trial maker.

Type:: list

performance_threshold¶

Score threshold used by the default performance check method, defaults to 0.0. By default, corresponds to the minimum proportion of non-failed trials that the participant must achieve to pass the performance check. Override this to change the behavior.

Type:: float

end_performance_check_waits¶

If True (default), then the final performance check waits until all trials no longer have any pending asynchronous processes.

Type:: bool

class psynet.trial.dense.Dimension(label, min_value, max_value, scale=1.0)[source]¶

Bases: dict

Defines a dimension of the stimulus space.

label: Label for the dimension.
min_value: Minimum value that the dimension can take (in this experiment).
max_value: Maximum value that the dimension can take (in this experiment).
scale: Indicates the relative scale of a dimension as compared to other dimensions. This is relevant for certain classes of dense experiment, for example same-different paradigms; doubling the scale parameter means that the perturbations will be twice as big along the specified dimension as compared to the other dimensions. Defaults to 1.0.

class psynet.trial.dense.PairedStimulusTrial(*args, **kwargs)[source]¶

Bases: DenseTrial

Defines a paradigm where each trial corresponds to a pair of locations in stimulus space. Most users will not use this class directly, but will instead use one of the following subclasses:

SameDifferentTrial
AXBTrial

There are several ways in which one might sample pairs of locations from a stimulus space. The present method may be summarised as follows:

Sample the ‘original’ stimulus uniformly from the stimulus space.

Sample the ‘altered’ stimulus randomly from the stimulus space with the constraint that it must be exactly delta units distant from the ‘original’ stimulus.

We also considered a slight modification of the above, not implemented here, where the ‘original’ stimulus is constrained such that no dimension is less than delta units away from a boundary value.

The delta parameter must be provided as one of the items within the DenseNode object’s definition attribute. One can achieve different perturbation sizes for different Dimensions by manipulating the scale attribute of the Dimension objects.

complete¶: whether the info is ‘complete’, i.e. has received its contents

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

failed¶: boolean indicating whether the Network has failed which prompts Dallinger to ignore it unless specified otherwise. Objects are usually failed to indicate something has gone wrong.

failed_reason¶: an optional reason the object was failed. If the object is failed as part of a cascading failure triggered from another object, the chain of objects will be captured in this field.

finalize_definition(definition, experiment, participant)[source]¶

This can be overridden to add additional randomized trial properties. For example:

definition["bass_note"] = random.sample(10)

It can also be used to add FastFunctionAssets:

self.add_assets({
    "audio": FastFunctionAsset(
        function=synth_stimulus,
        extension=".wav",
    )

id¶: a unique number for every entry. 1, 2, 3 and so on…

network¶: the network the info is in

network_id¶: the id of the network the info is in

origin¶: the Node that created the info.

origin_id¶: the id of the Node that created the info

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

score_answer(answer, definition)[source]¶: Returns 1 if the participant answers correctly, 0 otherwise.

show_trial(experiment, participant)[source]¶

Returns a Page object, or alternatively a list of such objects, that solicits an answer from the participant.

Parameters:

experiment – An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.
participant – An instantiation of psynet.participant.Participant, corresponding to the current participant.

time_of_death¶: the time at which failing occurred

type¶: a String giving the name of the class. Defaults to “info”. This allows subclassing.

vars¶

class psynet.trial.dense.SameDifferentTrial(*args, **kwargs)[source]¶

Bases: PairedStimulusTrial

Defines a same-different paradigm. Each trial comprises a pair of stimuli located in a random region of the stimulus space. These two stimuli may either be “same” or “different”. In the latter case, the two stimuli are separated by a distance of delta in the stimulus space, where delta is defined within the DenseNode object’s definition dictionary.

The user is responsible for implementing an appropriate show_trial() method, which should make use of the following automatically generated entries within the Trial’s definition attribute:

locations:: A dictionary of the form {"original": [a, b], "altered": [c, d]}, providing the locations of the original and the altered stimuli respectively.
order:: A list providing the order of the original and altered stimuli. Valid values are: * [“original”, “original”] * [“altered”, “same”] * [“same”, “altered”] These values can be used to index into locations to find the stimuli to present in the appropriate order.
correct_answer:: The correct answer; will be either same or different.

The show_trial() method should return either same or different as the answer.

complete¶: whether the info is ‘complete’, i.e. has received its contents

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

failed¶: boolean indicating whether the Network has failed which prompts Dallinger to ignore it unless specified otherwise. Objects are usually failed to indicate something has gone wrong.

failed_reason¶: an optional reason the object was failed. If the object is failed as part of a cascading failure triggered from another object, the chain of objects will be captured in this field.

finalize_definition(definition, experiment, participant)[source]¶

This can be overridden to add additional randomized trial properties. For example:

definition["bass_note"] = random.sample(10)

It can also be used to add FastFunctionAssets:

self.add_assets({
    "audio": FastFunctionAsset(
        function=synth_stimulus,
        extension=".wav",
    )

id¶: a unique number for every entry. 1, 2, 3 and so on…

network¶: the network the info is in

network_id¶: the id of the network the info is in

origin¶: the Node that created the info.

origin_id¶: the id of the Node that created the info

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

show_trial(experiment, participant)[source]¶

Returns a Page object, or alternatively a list of such objects, that solicits an answer from the participant.

Parameters:

experiment – An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.
participant – An instantiation of psynet.participant.Participant, corresponding to the current participant.

time_of_death¶: the time at which failing occurred

type¶: a String giving the name of the class. Defaults to “info”. This allows subclassing.

vars¶

class psynet.trial.dense.SingleStimulusTrial(*args, **kwargs)[source]¶

Bases: DenseTrial

Defines a paradigm where each stimulus corresponds to a randomly sampled location from the stimulus space. The user is responsible for implementing show_trial(), which determines how the trial is turned into a webpage for presentation to the participant. This method should make use of the following automatically generated entries within the Trial’s definition attribute:

location:: A list of numbers defining the stimulus’s position within the stimulus space.

complete¶: whether the info is ‘complete’, i.e. has received its contents

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

failed¶: boolean indicating whether the Network has failed which prompts Dallinger to ignore it unless specified otherwise. Objects are usually failed to indicate something has gone wrong.

failed_reason¶: an optional reason the object was failed. If the object is failed as part of a cascading failure triggered from another object, the chain of objects will be captured in this field.

finalize_definition(definition, experiment, participant)[source]¶

This can be overridden to add additional randomized trial properties. For example:

definition["bass_note"] = random.sample(10)

It can also be used to add FastFunctionAssets:

self.add_assets({
    "audio": FastFunctionAsset(
        function=synth_stimulus,
        extension=".wav",
    )

id¶: a unique number for every entry. 1, 2, 3 and so on…

network¶: the network the info is in

network_id¶: the id of the network the info is in

origin¶: the Node that created the info.

origin_id¶: the id of the Node that created the info

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

show_trial(experiment, participant)[source]¶

Returns a Page object, or alternatively a list of such objects, that solicits an answer from the participant.

Parameters:

experiment – An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.
participant – An instantiation of psynet.participant.Participant, corresponding to the current participant.

time_of_death¶: the time at which failing occurred

type¶: a String giving the name of the class. Defaults to “info”. This allows subclassing.

vars¶

class psynet.trial.dense.SliderCopyTrial(*args, **kwargs)[source]¶

Bases: SingleStimulusTrial

Defines a paradigm where each trial corresponds to a random location in the stimulus space; the participant is presented with a stimulus corresponding to that location, and they must then copy that stimulus using a slider. The slider is associated with a randomly chosen dimension of the stimulus (specified by the randomly generated active_index property of the Trial) and moving that slider changes the stimulus along that dimension. The participant must move that slider until they believe that they have reproduced the original stimulus.

This paradigm requires the user to specify several special parameters within each DenseNode object:

slider_width, a number determining the width of the region of the stimulus space that the slider covers;
slider_jitter, a number determining the amount of jitter applied to the slider’s location; the slider will be jittered according to a uniform distribution ranging from - slider_jitter to + slider_jitter.
allow_slider_outside_range, a Boolean determining whether the slider jitter is allowed to take the slider outside the range specified by the relevant Dimension object``.

The user is responsible for implementing an appropriate show_trial() method, which should make use of the following automatically generated entries within the Trial’s definition attribute:

location:: A list of numbers defining the stimulus’s position within the stimulus space.
active_index:: An integer identifying which of the dimensions should be linked with the slider (0-indexed).
slider_range: A pair of numbers identifying the minimum and maximum points of the slider, expressed in the units of the Dimension currently being manipulated.
slider_start_value: The (randomly generated) starting value of the slider.

The class contains a built-in :meth:`~psynet.trial.main.SliderCopyTrial.score_answer method which returns the absolute distance between the true stimulus location and the stimulus location chosen by the participant. The resulting score is stored in the trial’s score attribute, and can be used for performance rewards.

complete¶: whether the info is ‘complete’, i.e. has received its contents

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

failed¶: boolean indicating whether the Network has failed which prompts Dallinger to ignore it unless specified otherwise. Objects are usually failed to indicate something has gone wrong.

failed_reason¶: an optional reason the object was failed. If the object is failed as part of a cascading failure triggered from another object, the chain of objects will be captured in this field.

finalize_definition(definition, experiment, participant)[source]¶

This can be overridden to add additional randomized trial properties. For example:

definition["bass_note"] = random.sample(10)

It can also be used to add FastFunctionAssets:

self.add_assets({
    "audio": FastFunctionAsset(
        function=synth_stimulus,
        extension=".wav",
    )

id¶: a unique number for every entry. 1, 2, 3 and so on…

network¶: the network the info is in

network_id¶: the id of the network the info is in

origin¶: the Node that created the info.

origin_id¶: the id of the Node that created the info

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

score_answer(answer, definition)[source]¶

Scores the participant’s answer. At the point that this method is called, any pending asynchronous processes should already have been completed.

Parameters:

answer – The answer provided to the trial.
definition – The trial’s definition

Returns:

A numeric score quantifying the participant’s success.
The experimenter is free to decide the directionality
(whether high scores are better than low scores, or vice versa).
Alternatively, None indicating no score.

time_of_death¶: the time at which failing occurred

type¶: a String giving the name of the class. Defaults to “info”. This allows subclassing.

vars¶