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.experiment.
Experiment
(session=None)[source]¶ 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.
-
recruiter
¶
-
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.
-
participant_constructor
¶ Constructor for Participant objects. Callable returning an instance of
Participant
or a sub-class. Used bycreate_participant()
.
-
public_properties
¶
-
add_node_to_network
(node, network)[source]¶ Add a node to a network.
This passes node to
add_node()
.
-
assignment_abandoned
(participant)[source]¶ 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_reassigned
(participant)[source]¶ What to do if the assignment assigned to a participant is reassigned to another participant while the first participant is still working.
This runs when a participant is created with the same assignment_id as another participant if the earlier participant still has the status “working”. Calls
fail_participant()
.
-
assignment_returned
(participant)[source]¶ 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)[source]¶ 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)[source]¶ What to do if a participant fails the attention check.
Runs when participant has failed the
attention_check()
. By default callsfail_participant()
.
-
bonus
(participant)[source]¶ 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
()[source]¶ 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.”
-
collect
(app_id, exp_config=None, bot=False, **kwargs)[source]¶ Collect data for the provided experiment id.
The
app_id
parameter must be a valid UUID. If an existing data file is found for the UUID it will be returned, otherwise - if the UUID is not already registered - the experiment will be run and data collected.See
run()
method for other parameters.
-
create_participant
(worker_id, hit_id, assignment_id, mode, recruiter_name=None, fingerprint_hash=None)[source]¶ Creates and returns a new participant object. Uses
participant_constructor
as the constructor.Parameters: - worker_id (str) – the recruiter Worker Id
- hit_id (str) – the recruiter HIT Id
- assignment_id (str) – the recruiter Assignment Id
- mode (str) – the application mode
- recruiter_name (str) – the recruiter name
Returns: A
Participant
instance
-
dashboard_database_actions
()[source]¶ Returns a sequence of custom actions for the database dashboard. Each action must have a
title
and aname
corresponding to a method on the experiment class.The named methods should take a single
data
argument which will be a list of dicts representing the datatables rendering of a Dallinger model object. The named methods should return adict
containing a"message"
which will be displayed in the dashboard.Returns a single action referencing the
dashboard_fail()
method by default.
-
dashboard_fail
(data)[source]¶ Marks matching non-failed items as failed. Items are looked up by
id
andobject_type
(e.g."Participant"
).Parameters: data – A list of dicts representing model items to be marked as failed. Each must have an id
and anobject_type
Returns: Returns a dict
with a"message"
string indicating how many items were successfully marked as failed.
-
data_check
(participant)[source]¶ 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)[source]¶ What to do if a participant fails the data check.
Runs when participant has failed
data_check()
. By default callsfail_participant()
.
-
events_for_replay
(session=None, target=None)[source]¶ Returns an ordered list of “events” for replaying. Experiments may override this method to provide custom replay logic. The “events” returned by this method will be passed to
replay_event()
. The default implementation simply returns allInfo
objects in the order they were created.
-
get_network_for_participant
(participant)[source]¶ 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.
-
is_complete
()[source]¶ Method for custom determination of experiment completion. Experiments should override this to provide custom experiment completion logic. Returns None to use the experiment server default logic, otherwise should return True or False.
-
is_overrecruited
(waiting_count)[source]¶ Returns True if the number of people waiting is in excess of the total number expected, indicating that this and subsequent users should skip the experiment. A quorum value of 0 means we don’t limit recruitment, and always return False.
-
load_participant
(assignment_id)[source]¶ Returns a participant object looked up by assignment_id.
Intended to allow a user to resume a session in a running experiment.
Parameters: assignment_id (str) – the recruiter Assignment Id Returns: A Participant
instance orNone
if there is not a single matching participant.
-
classmethod
make_uuid
(app_id=None)[source]¶ Generates a new UUID. This is a class method and can be called as Experiment.make_uuid(). Takes an optional app_id which is converted to a string and, if it is a valid UUID, returned.
-
recruit
()[source]¶ 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.
-
replay_event
(event)[source]¶ Stub method to replay an event returned by
events_for_replay()
. Experiments must override this method to provide replay support.
-
replay_start
()[source]¶ Stub method for starting an experiment replay. Experiments must override this method to provide replay support.
-
replay_finish
()[source]¶ Stub method for ending an experiment replay. Experiments must override this method to provide replay support.
-
run
(exp_config=None, app_id=None, bot=False, **kwargs)[source]¶ Deploy and run an experiment.
The exp_config object is either a dictionary or a
localconfig.LocalConfig
object with parameters specific to the experiment run grouped by section.
-
save
(*objects)[source]¶ Add all the objects to the session and commit them.
This only needs to be done for networks and participants.
-
transformation_get_request
(node, transformations)[source]¶ Run when a request to get transformations is complete.
-
transformation_post_request
(node, transformation)[source]¶ Run when a request to transform an info is complete.
-