The Experiment Class

Experiments are designed in Dallinger by creating a custom subclass of the base Experiment class. The code for the Experiment class is in experiments.py. Unlike the other classes, each experiment involves only a single Experiment object and it is not stored as an entry in a corresponding table, rather each Experiment is a set of instructions that tell the server what to do with the database when the server receives requests from outside.

class dallinger.experiments.Experiment(session)

Define the structure of an experiment.

verbose

Boolean, determines whether the experiment logs output when running. Default is True.

task

String, the name of the experiment. Default is “Experiment title”.

session

session, the experiment’s connection to the database.

practice_repeats

int, the number of practice networks (see role). Default is 0.

experiment_repeats

int, the number of non practice networks (see role). Default is 0.

recruiter

Recruiter, the Dallinger class that recruits participants. Default is PsiTurkRecruiter.

initial_recruitment_size

int, the number of participants requested when the experiment first starts. Default is 1.

known_classes

dictionary, the classes Dallinger can make in response to front-end requests. Experiments can add new classes to this dictionary.

__init__(session)

Create the experiment class. Sets the default value of attributes.

add_node_to_network(node, network)

Add a node to a network.

This passes node to add_node().

assignment_abandoned(participant)

What to do if a participant abandons the hit.

This runs when a notification from AWS is received indicating that participant has run out of time. Calls fail_participant().

assignment_returned(participant)

What to do if a participant returns the hit.

This runs when a notification from AWS is received indicating that participant has returned the experiment assignment. Calls fail_participant().

attention_check(participant)

Check if participant performed adequately.

Return a boolean value indicating whether the participant‘s data is acceptable. This is mean to check the participant’s data to determine that they paid attention. This check will run once the participant completes the experiment. By default performs no checks and returns True. See also data_check().

attention_check_failed(participant)

What to do if a participant fails the attention check.

Runs when participant has failed the attention_check(). By default calls fail_participant().

bonus(participant)

The bonus to be awarded to the given participant.

Return the value of the bonus to be paid to participant. By default returns 0.

bonus_reason()

The reason offered to the participant for giving the bonus.

Return a string that will be included in an email sent to the participant receiving a bonus. By default it is “Thank you for participating! Here is your bonus.”

create_network()

Return a new network.

create_node(participant, network)

Create a node for a participant.

data_check(participant)

Check that the data are acceptable.

Return a boolean value indicating whether the participant‘s data is acceptable. This is meant to check for missing or invalid data. This check will be run once the participant completes the experiment. By default performs no checks and returns True. See also, attention_check().

data_check_failed(participant)

What to do if a participant fails the data check.

Runs when participant has failed data_check(). By default calls fail_participant().

fail_participant(participant)

Fail all the nodes of a participant.

get_network_for_participant(participant)

Find a network for a participant.

If no networks are available, None will be returned. By default participants can participate only once in each network and participants first complete networks with role=”practice” before doing all other networks in a random order.

info_get_request(node, infos)

Run when a request to get infos is complete.

info_post_request(node, info)

Run when a request to create an info is complete.

log(text, key='?????', force=False)

Print a string to the logs.

log_summary()

Log a summary of all the participants’ status codes.

networks(role='all', full='all')

All the networks in the experiment.

node_get_request(node=None, nodes=None)

Run when a request to get nodes is complete.

node_post_request(participant, node)

Run when a request to make a node is complete.

recruit()

Recruit participants to the experiment as needed.

This method runs whenever a participant successfully completes the experiment (participants who fail to finish successfully are automatically replaced). By default it recruits 1 participant at a time until all networks are full.

save(*objects)

Add all the objects to the session and commit them.

This only needs to be done for networks and participants.

setup()

Create the networks if they don’t already exist.

submission_successful(participant)

Run when a participant submits successfully.

transformation_get_request(node, transformations)

Run when a request to get transformations is complete.

transformation_post_request(node, transformation)

Run when a request to transform an info is complete.

transmission_get_request(node, transmissions)

Run when a request to get transmissions is complete.

transmission_post_request(node, transmissions)

Run when a request to transmit is complete.

vector_get_request(node, vectors)

Run when a request to get vectors is complete.

vector_post_request(node, vectors)

Run when a request to connect is complete.