Main¶

class psynet.trial.main.GenericTrialNetwork(*args, **kwargs)[source]¶

Bases: TrialNetwork

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.

full¶: Whether the network is currently full

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

max_size¶: How big the network can get, this number is used by the full() method to decide whether the network is full

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.

role¶: The role of the network. By default dallinger initializes all networks as either “practice” or “experiment”

time_of_death¶: the time at which failing occurred

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

vars¶

class psynet.trial.main.GenericTrialNode(*args, **kwargs)[source]¶

Bases: TrialNode

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.main.NetworkTrialMaker(id_, trial_class, network_class, expected_trials_per_participant, check_performance_at_end, check_performance_every_trial, fail_trials_on_premature_exit, fail_trials_on_participant_performance_check, propagate_failure, recruit_mode, target_n_participants, n_repeat_trials, wait_for_networks, assets=None, sync_group_type=None, sync_group_max_wait_time=45.0)[source]¶

Bases: TrialMaker

Trial maker for network-based experiments. These experiments are organised around networks in an analogous way to the network-based experiments in Dallinger. A Network comprises a collection of Node objects organised in some kind of structure. Here the role of Node objects is to generate Trial objects. Typically the Node object represents some kind of current experiment state, such as the last datum in a transmission chain. In some cases, a Network or a Node will be owned by a given participant; in other cases they will be shared between participants.

An important feature of these networks is that their structure can change over time. This typically involves adding new nodes that somehow respond to the trials that have been submitted previously.

The present class facilitates this behaviour by providing a built-in prepare_trial() implementation that comprises the following steps:

Find the available networks from which to source the next trial, ordered by preference (find_networks()). These may be created on demand, or alternatively pre-created by pre_deploy_routine().
Give these networks an opportunity to grow (i.e. update their structure based on the trials that they’ve received so far) (grow_network()).
Iterate through these networks, and find the first network that has a node available for the participant to attach to. (find_node()).
Create a trial from this node (psynet.trial.main.Trial.__init__()).

The trial is then administered to the participant, and a response elicited. Once the trial is finished, the network is given another opportunity to grow.

The implementation also provides support for asynchronous processing, for example to prepare the stimuli available at a given node, or to postprocess trials submitted to a given node. There is some sophisticated logic to make sure that a participant is not assigned to a Node object if that object is still waiting for an asynchronous process, and likewise a trial won’t contribute to a growing network if it is still pending the outcome of an asynchronous process.

The user is expected to override the following abstract methods/attributes:

pre_deploy_routine(), (optional), which defines a routine that sets up the experiment (for example initialising and seeding networks).
find_networks(), which finds the available networks from which to source the next trial, ordered by preference.
grow_network(), which give these networks an opportunity to grow (i.e. update their structure based on the trials that they’ve received so far).
find_node(), which takes a given network and finds a node which the participant can be attached to, if one exists.

Do not override prepare_trial.

Parameters:

trial_class – The class object for trials administered by this maker.
network_class – The class object for the networks used by this maker. This should subclass :class`~psynet.trial.main.TrialNetwork`.
expected_trials_per_participant – Expected number of trials that the participant will take, including repeat trials (used for progress estimation).
check_performance_at_end – If True, the participant’s performance is evaluated at the end of the series of trials.
check_performance_every_trial – If True, the participant’s performance is evaluated after each trial.
fail_trials_on_premature_exit – If True, a participant’s trials are marked as failed if they leave the experiment prematurely.
fail_trials_on_participant_performance_check – If True, a participant’s trials are marked as failed if the participant fails a performance check.
propagate_failure – If True, the failure of a trial is propagated to other parts of the experiment (the nature of this propagation is left up to the implementation).
recruit_mode – Selects a recruitment criterion for determining whether to recruit another participant. The built-in criteria are "n_participants" and "n_trials", though the latter requires overriding of n_trials_still_required.
target_n_participants – 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".
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. Defaults to 0.
wait_for_networks (bool) – If True, then the participant will be made to wait if there are still more networks to participate in, but these networks are pending asynchronous processes.
sync_group_type (Optional[str]) – Optional SyncGroup type to use for synchronizing participant allocation to nodes. When this is set, then the ordinary node allocation logic will only apply to the ‘leader’ of each SyncGroup. The other members of this SyncGroup will follow that leader around, so that in every given trial the SyncGroup works on the same node together.
sync_group_max_wait_time (float) – The maximum time that the participant will be allowed to wait for the SyncGroup to be ready. If this time is exceeded then the participant will be failed and the experiment will terminate early. Defaults to 45.0 seconds.

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.

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

performance_threshold¶

The performance threshold that is used in the performance_check() method.

Type:: float (default = -1.0)

compute_performance_reward(score, passed)[source]¶: Computes the performance reward to allocate to the participant at the end of a trial maker on the basis of the results of the final performance check. Note: if check_performance_at_end = False, then this function will not be run and the performance reward will not be assigned.

find_networks(participant, experiment)[source]¶

Returns a list of all available networks for the participant’s next trial, ordered in preference (most preferred to least preferred).

Parameters:

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

find_node(network, participant, experiment)[source]¶

Finds the node to which the participant should be attached for the next trial.

Parameters:

network – The network to be potentially extended.
participant – An instantiation of psynet.participant.Participant, corresponding to the current participant.
experiment – An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

get_trial_class(node, participant, experiment)[source]¶: Returns the class of trial to be used for this trial maker.

grow_network(network, experiment)[source]¶

Extends the network if necessary by adding one or more nodes. Returns True if any nodes were added.

Parameters:

network – The network to be potentially extended.
experiment – An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

performance_check(experiment, participant, participant_trials)[source]¶

Defines an automated check for evaluating the participant’s current performance. The default behaviour is to take the sum of the trial ‘scores’ (as computed by the Trial.score_answer), but this can be overridden if desired.

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.
participant_trials – A list of all trials completed so far by the participant.

Returns:

dict – The dictionary should include the following values:
- score, expressed as a float or None.
- passed (Boolean), identifying whether the participant passed the check.

prepare_trial(experiment, participant)[source]¶

Prepares and returns a trial to administer the participant.

Parameters:

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

Returns:

A tuple of (Trial, str), where the first is a Trial object,
and the second is a status string.

state_class¶: alias of NetworkTrialMakerState

class psynet.trial.main.NetworkTrialMakerState(*args, **kwargs)[source]¶

Bases: TrialMakerState

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…

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¶

vars¶

class psynet.trial.main.Trial(*args, **kwargs)[source]¶

Bases: SQLMixinDallinger, Info

Represents a trial in the experiment. The user is expected to override the following methods:

make_definition(), responsible for deciding on the content of the trial.
show_trial(), determines how the trial is turned into a webpage for presentation to the participant.
show_feedback(), defines an optional feedback page to be displayed after the trial.

The user must also override the time_estimate class attribute, providing the estimated duration of the trial in seconds. This is used for predicting the participant’s performance reward and for constructing the progress bar.

The user may also wish to override the async_post_trial() method if they wish to implement asynchronous trial processing.

They may also override the score_answer() method if they wish to implement trial-level scoring; for scoring methods that work by analyzing multiple trials at the same time (e.g., test-retest correlations), see the trial maker method performance_check().

This class subclasses the Info class from Dallinger, hence can be found in the Info table in the database. It inherits this class’s methods, which the user is welcome to use if they seem relevant.

Instances can be retrieved using SQLAlchemy; for example, the following command retrieves the Trial object with an ID of 1:

Trial.query.filter_by(id=1).one()

Parameters:

experiment – An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.
node – An object of class dallinger.models.Node to which the Trial object should be attached. Complex experiments are often organised around networks of nodes, but in the simplest case one could just make one Network for each type of trial and one Node for each participant, and then assign the Trial to this Node. Ask us if you want to use this simple use case - it would be worth adding it as a default to this implementation, but we haven’t done that yet, because most people are using more complex designs.
participant – An instantiation of psynet.participant.Participant, corresponding to the current participant.
propagate_failure (bool) – Whether failure of a trial should be propagated to other parts of the experiment depending on that trial (for example, subsequent parts of a transmission chain).

time_estimate¶

The estimated duration of the trial (including any feedback), in seconds. This should generally correspond to the (sum of the) time_estimate parameters in the page(s) generated by show_trial, plus the time_estimate parameter in the page generated by show_feedback (if defined). This is used for predicting the participant’s performance reward and for constructing the progress bar.

Type:: numeric

participant_id¶

The ID of the associated participant. The user should not typically change this directly. Stored in property1 in the database.

Type:: int

node¶: The dallinger.models.Node to which the Trial belongs.

complete¶

Whether the trial has been completed (i.e. received a response from the participant). The user should not typically change this directly.

Type:: bool

finalized¶

Whether the trial has been finalized. This is a stronger condition than complete; in particular, a trial is only marked as finalized once its async processes have completed (if it has any). One day we might extend this to include arbitrary conditions, for example waiting for another user to evaluate that trial, or similar.

Type:: bool

answer¶

The response returned by the participant. This is serialised to JSON, so it shouldn’t be too big. The user should not typically change this directly. Stored in details in the database.

Type:: Object

parent_trial_id¶

If the trial is a repeat trial, this attribute corresponds to the ID of the trial from which that repeat trial was cloned.

Type:: int

earliest_async_process_start_time¶

Time at which the earliest pending async process was called.

Type:: Optional[datetime]

propagate_failure¶

Whether failure of a trial should be propagated to other parts of the experiment depending on that trial (for example, subsequent parts of a transmission chain).

Type:: bool

var¶

A repository for arbitrary variables; see VarStore for details.

Type:: VarStore

definition¶

An arbitrary Python object that somehow defines the content of a trial. Often this will be a dictionary comprising a few named parameters. The user should not typically change this directly, as it is instead determined by make_definition().

Type:: Object

run_async_post_trial¶

Set this to False if you want to disable async_post_trial(). This is only included for back-compatibility.

Type:: bool

wait_for_feedback¶

Set this class attribute to False if you don’t want to wait for asynchronous processes to complete before giving feedback. The default is to wait.

Type:: bool

accumulate_answers¶

Set this class attribute to True if the trial contains multiple pages and you want the answers to all of these pages to be stored as a dict in participant.answer. Otherwise, the default behaviour is to only store the answer from the final page.

Type:: bool

time_credit_before_trial¶

Reports the amount of time credit that the participant had before they started the trial (in seconds).

Type:: float

time_credit_after_trial¶

Reports the amount of time credit that the participant had after they finished the trial (in seconds).

Type:: float

time_credit_from_trial¶

Reports the amount of time credit that was allocated to the participant on the basis of this trial (in seconds). This should be equal to time_credit_after_trial - time_credit_before_trial.

Type:: float

progress_before_trial¶

Reports the progress that the participant had before they started the trial. Mainly useful for debugging.

Type:: float

progress_after_trial¶

Reports the progress that the participant had after they finished the trial. Mainly useful for debugging.

Type:: float

check_time_credit_received¶

If True (default), PsyNet will check at the end of the trial whether the participant received the expected amount of time credit. If the received amount is inconsistent with the amount specified by time_estimate, then a warning message will be delivered, suggesting a revised value for time_estimate.

Type:: bool

response_id¶

ID of the associated Response object. Equals None if no such object has been created yet.

Type:: int

response¶: The associated Response object, which records in detail the response received from the participant’s web browser. Equals None if no such object has been created yet.

async_post_trial()[source]¶: Optional function to be run after a trial is completed by the participant. Will only run if run_async_post_trial is set to True.

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

compute_performance_reward(score)[source]¶

Computes a performance reward to allocate to the participant as a reward for the current trial. By default, no performance reward is given. Note: this trial-level performance reward system is complementary to the trial-maker-level performance reward system, which computes an overall performance reward for the participant at the end of a trial maker. It is possible to use these two performance reward systems independently or simultaneously. See compute_performance_reward() for more details.

Parameters:

score – The score achieved by the participant, as computed by score_answer().

Returns:

The resulting performance reward, typically in dollars.

property contents¶

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

classmethod cue(definition, assets=None)[source]¶

Use this method to add a trial directly into a timeline, without needing to create a corresponding trial maker.

Parameters:

definition – This can be a dict object, which will then be saved to the trial’s definition slot. Alternatively, it can be a Node object, in which case the Node object will be saved to trial.node, and node.definition will be saved to trial.definition.
assets – Optional dictionary of assets to add to the trial (in addition to any provided by providing a Source containing assets to the definition parameter).

details¶: a generic column for storing structured JSON data

fail(reason=None)[source]¶

Fail this object, and potentially its related objects.

Set failed to True and time_of_death to now.

If a reason argument is passed, this will be stored in failed_reason.

Failure will then be propagated to related objects as defined by the failure_cascade property.

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 OnDemandAsset:

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

format_answer(raw_answer, **kwargs)[source]¶: Optional function to be run after a trial is completed by the participant.

classmethod get_for_participant(participant_id, trial_maker_id=None)[source]¶: Returns all trials for a given participant.

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

json_data()[source]¶

Returns a JSON serializable dict (datetime values allowed) to describe this object. This method can be overridden by sub-classes to extend the default model data used for display in the Dashboard Network Monitor and Database views.

Returns:: dict with JSON serializable data

make_definition(experiment, participant)[source]¶

Creates and returns a definition for the trial, which will be later stored in the definition attribute. This can be an arbitrary object as long as it is serialisable to JSON.

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.

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

property position¶: Returns the position of the current trial within that participant’s current trial maker (0-indexed). This can be used, for example, to display how many trials the participant has taken so far.

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.

property ready_for_feedback¶: Determines whether a trial is ready to give feedback to the participant.

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.

show_feedback(experiment, participant)[source]¶

Returns a Page object displaying feedback (or None, which means no feedback).

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.

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

to_dict()[source]¶: Determines the information that is shown for this object in the dashboard and in the csv files generated by psynet export.

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

vars¶

property visualization_html¶

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

class psynet.trial.main.TrialMaker(id_, trial_class, expected_trials_per_participant, check_performance_at_end, check_performance_every_trial, fail_trials_on_premature_exit, fail_trials_on_participant_performance_check, propagate_failure, recruit_mode, target_n_participants, n_repeat_trials, assets, sync_group_type=None, sync_group_max_wait_time=45.0)[source]¶

Bases: Module

Generic trial generation module, to be inserted in an experiment timeline. It is responsible for organising the administration of trials to the participant.

Users are invited to override the following abstract methods/attributes:

prepare_trial(), which prepares the next trial to administer to the participant.
pre_deploy_routine() (optional), which defines a routine that sets up the experiment in advance of deployment (for example initialising and seeding networks).
init_participant() (optional), a function that is run when the participant begins this sequence of trials, intended to initialize the participant’s state. Make sure you call super().init_participant when overriding this.
finalize_trial() (optional), which finalizes the trial after the participant has given their response.
on_complete() (optional), run once the sequence of trials is complete.
performance_check() (optional), which 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.
n_trials_still_required (optional), which is used to estimate how many more participants are still required in the case that recruit_mode="n_trials".
give_end_feedback_passed (default = False); if True, then participants who pass the final performance check will be given feedback. This feedback can be customised by overriding get_end_feedback_passed_page().

Users are also invited to add new recruitment criteria for selection with the recruit_mode argument. This may be achieved using a custom subclass of TrialMaker as follows:

class CustomTrialMaker(TrialMaker):
    def new_recruit(self, experiment):
        if experiment.my_condition:
            return True # True means recruit more
        else:
            return False # False means don't recruit any more (for now)

    recruit_criteria = {
        **TrialMaker.recruit_criteria,
        "new_recruit": new_recruit
    }

With the above code, you’d then be able to use recruit_mode="new_recruit". If you’re subclassing a subclass of TrialMaker, then just replace that subclass wherever TrialMaker occurs in the above code.

Parameters:

trial_class – The class object for trials administered by this maker.
expected_trials_per_participant (Union[int, float]) – Expected number of trials that the participant will take, including repeat trials (used for progress estimation).
check_performance_at_end (bool) – If True, the participant’s performance is evaluated at the end of the series of trials.
check_performance_every_trial (bool) – If True, the participant’s performance is evaluated after each trial.
fail_trials_on_premature_exit (bool) – If True, a participant’s trials are marked as failed if they leave the experiment prematurely.
fail_trials_on_participant_performance_check (bool) – If True, a participant’s trials are marked as failed if the participant fails a performance check.
propagate_failure (bool) – If True, the failure of a trial is propagated to other parts of the experiment (the nature of this propagation is left up to the implementation).
recruit_mode (str) – Selects a recruitment criterion for determining whether to recruit another participant. The built-in criteria are "n_participants" and "n_trials", though the latter requires overriding of n_trials_still_required.
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".
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. Defaults to 0.

check_timeout_interval_sec¶

How often to check for timeouts, in seconds (default = 30). Users are invited to override this.

Type:: float

response_timeout_sec¶

Type:: float

async_timeout_sec¶

Type:: float

introduction¶: An optional event or list of elts to execute prior to beginning the trial loop.

give_end_feedback_passed¶

If True, then participants who pass the final performance check are given feedback. This feedback can be customised by overriding get_end_feedback_passed_page().

Type:: bool

performance_threshold¶

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

sync_group_type¶: Optional SyncGroup type to use for synchronizing participant allocation to nodes. When this is set, then the ordinary node allocation logic will only apply to the ‘leader’ of each SyncGroup. The other members of this SyncGroup will follow that leader around, so that in every given trial the SyncGroup works on the same node together.

sync_group_max_wait_time¶: The maximum time that the participant will be allowed to wait for the SyncGroup to be ready. If this time is exceeded then the participant will be failed and the experiment will terminate early. Defaults to 45.0 seconds.

check_fail_logic()[source]¶

Determines the timeline logic for when a participant fails the performance check. By default, the participant is shown an UnsuccessfulEndPage.

Returns:

An Elt or a list of Elt s.

cue_trial()[source]¶: You can use this in combination with init_participant to administer trials outside of a trialmaker.

finalize_trial(answer, trial, experiment, participant)[source]¶

This function is run after the participant completes the trial. It can be optionally customised, for example to add some more postprocessing. If you override this, make sure you call super().finalize_trial(...) somewhere in your new method.

Parameters:

answer – The answer object provided by the trial.
trial – The Trial object representing the trial.
experiment – An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.
participant – An instantiation of psynet.participant.Participant, corresponding to the current participant.

get_end_feedback_passed_page(score)[source]¶

Defines the feedback given to participants who pass the final performance check. This feedback is only given if give_end_feedback_passed is set to True.

Parameters:

score – The participant’s score on the performance check.

Returns:

Page – A feedback page.

get_participant_trials(participant)[source]¶

Returns all trials (complete and incomplete) owned by the current participant, including repeat trials. Not intended for overriding.

Parameters:: participant – An instantiation of psynet.participant.Participant, corresponding to the current participant.

init_participant(experiment, participant)[source]¶

Initializes the participant at the beginning of the sequence of trials. If you override this, make sure you call super().init_particiant(...) somewhere in your new method.

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.

on_complete(experiment, participant)[source]¶

An optional function run once the participant completes their sequence of trials.

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.

on_first_launch(experiment)[source]¶

Defines a routine to run when the experiment is launched for the first time.

Parameters:: experiment – An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

performance_check(experiment, participant, participant_trials)[source]¶

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.
participant_trials – A list of all trials completed so far by the participant.

Returns:

dict – The dictionary should include the following values:
- score, expressed as a float or None.
- passed (Boolean), identifying whether the participant passed the check.

pre_deploy_routine(experiment)[source]¶

Defines a routine for setting up the experiment prior to deployment. This is a good place to prepare networks etc.

Parameters:: experiment – An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

prepare_trial(experiment, participant)[source]¶

Prepares and returns a trial to administer 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.

Returns:

A tuple of (Trial, str), where the first is a Trial object,
and the second is a status string.

state_class¶: alias of TrialMakerState

class psynet.trial.main.TrialMakerState(*args, **kwargs)[source]¶

Bases: ModuleState

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…

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¶

vars¶

class psynet.trial.main.TrialNetwork(*args, **kwargs)[source]¶

Bases: SQLMixinDallinger, Network

A network class to be used by NetworkTrialMaker. The user must override the abstract method add_node(). The user may also wish to override the async_post_grow_network() method if they wish to implement asynchronous network processing.

Parameters:: experiment – An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

target_n_trials¶

Indicates the target number of trials for that network. Left empty by default, but can be set by custom __init__ functions. Stored as the field property2 in the database.

Type:: int or None

participant¶

Returns the network’s Participant, or None if none can be found.

Type:: Optional[Participant]

sync_group_type¶

The sync_group_type attribute of the trial maker that owns this network.

Type:: Optional[str]

sync_group¶

The SyncGroup that owns this network (normally only relevant for within-style chains).

Type:: Optional[SyncGroup]

sync_group_id¶

The ID of the SyncGroup that owns this network (normally only relevant for within-style chains).

Type:: Optional[int]

n_alive_nodes¶

Returns the number of non-failed nodes in the network.

Type:: int

n_completed_trials¶

Returns the number of completed and non-failed trials in the network (irrespective of asynchronous processes, but excluding repeat trials).

Type:: int

all_trials¶

A list of all trials owned by that network.

Type:: list

alive_trials¶

A list of all non-failed trials owned by that network.

Type:: list

failed_trials¶

A list of all failed trials owned by that network.

Type:: list

var¶

A repository for arbitrary variables; see VarStore for details.

Type:: VarStore

run_async_post_grow_network¶

Set this to True if you want the async_post_grow_network() method to run after the network is grown.

Type:: bool

add_node(node)[source]¶: Adds a node to the network. This method is responsible for setting self.full = True if the network is full as a result.

async_post_grow_network()[source]¶: Optional function to be run after the network is grown. Will only run if run_async_post_grow_network is set to True.

calculate_full()[source]¶: Set whether the network is full.

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

details¶: a generic column for storing structured JSON data

fail(reason=None)[source]¶

Fail this object, and potentially its related objects.

Set failed to True and time_of_death to now.

If a reason argument is passed, this will be stored in failed_reason.

Failure will then be propagated to related objects as defined by the failure_cascade property.

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.

full¶: Whether the network is currently full

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

max_size¶: How big the network can get, this number is used by the full() method to decide whether the network is full

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.

role¶: The role of the network. By default dallinger initializes all networks as either “practice” or “experiment”

time_of_death¶: the time at which failing occurred

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

vars¶

class psynet.trial.main.TrialNode(*args, **kwargs)[source]¶

Bases: SQLMixinDallinger, Node

async_on_deploy()[source]¶: Called when the node is deployed to the remote server. This includes both deploying nodes from the local machine to the remote machine (e.g. when we have static stimuli that are preregistered in the database) and creating new nodes on the remote machine (e.g. when we have a chain experiment).

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

details¶: a generic column for storing structured JSON data

fail(reason=None)[source]¶

Fail this object, and potentially its related objects.

Set failed to True and time_of_death to now.

If a reason argument is passed, this will be stored in failed_reason.

Failure will then be propagated to related objects as defined by the failure_cascade property.

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¶