Participant¶

psynet.participant.get_participant(participant_id, for_update=False)[source]¶

Returns the participant with a given ID. Warning: we recommend just using SQLAlchemy directly instead of using this function. When doing so, use with_for_update().populate_existing() if you plan to update this Participant object, that way the database row will be locked appropriately.

Parameters:

participant_id (int) – ID of the participant to get.
for_update (bool) – Set to True if you plan to update this Participant object. The Participant object will be locked for update in the database and only released at the end of the transaction.

Return type:

Participant

Returns:

psynet.participant.Participant – The requested participant.

class psynet.participant.Participant(*args, **kwargs)[source]¶

Represents an individual participant taking the experiment. The object is linked to the database - when you make changes to the object, it should be mirrored in the database.

Users should not have to instantiate these objects directly.

The class extends the Participant class from base Dallinger (dallinger.models.Participant) to add some useful features, in particular the ability to store arbitrary variables.

The following attributes are recommended for external use:

answer
var
failure_tags

The following method is recommended for external use:

append_failure_tags()

See below for more details.

id¶

The participant’s unique ID.

Type:: int

elt_id¶

Represents the participant’s position in the timeline. Should not be modified directly. The position is represented as a list, where the first element corresponds to the index of the participant within the timeline’s underlying list representation, and successive elements (if any) represent the participant’s position within (potentially nested) page makers. For example, [10, 3, 2] would mean go to element 10 in the timeline (0-indexing), which must be a page maker; go to element 3 within that page maker, which must also be a page maker; go to element 2 within that page maker.

Type:: list

elt_bounds¶

Represents the number of elements at each level of the current elt_id hierarchy; used to work out when to leave a page maker and go up to the next level. Should not be modified directly.

Type:: list

page_uuid¶

A long unique string that is randomly generated when the participant advances to a new page, used as a passphrase to guarantee the security of data transmission from front-end to back-end. Should not be modified directly.

Type:: str

complete¶

Whether the participant has successfully completed the experiment. A participant is considered to have successfully completed the experiment once they hit a SuccessfulEndPage. Should not be modified directly.

Type:: bool

aborted¶

Whether the participant has aborted the experiment. A participant is considered to have aborted the experiment once they have hit the “Abort experiment” button on the “Abort experiment” confirmation page.

Type:: bool

answer¶

The most recent answer submitted by the participant. Can take any form that can be automatically serialized to JSON. Should not be modified directly.

Type:: object

response¶

An object of class Response providing detailed information about the last response submitted by the participant. This is a more detailed version of answer.

Type:: Response

branch_log¶

Stores the conditional branches that the participant has taken through the experiment. Should not be modified directly.

Type:: list

failure_tags¶

Stores tags that identify the reason that the participant has failed the experiment (if any). For example, if a participant fails a microphone pre-screening test, one might add “failed_mic_test” to this tag list. Should be modified using the method append_failure_tags().

Type:: list

var¶

A repository for arbitrary variables; see VarStore for details.

Type:: VarStore

progress¶

The participant’s estimated progress through the experiment.

Type:: float [0 <= x <= 1]

client_ip_address¶

The participant’s IP address as reported by Flask.

Type:: str

answer_is_fresh¶

True if the current value of participant.answer (and similarly participant.last_response_id and participant.last_response) comes from the last page that the participant saw, False otherwise.

Type:: bool

browser_platform¶

Information about the participant’s browser version and OS platform.

Type:: str

all_trials¶

A list of all trials for that participant.

Type:: list

alive_trials¶

A list of all non-failed trials for that participant.

Type:: list

failed_trials¶

A list of all failed trials for that participant.

Type:: list

abort_info()[source]¶

Information that will be shown to a participant if they click the abort button, e.g. in the case of an error where the participant is unable to finish the experiment.

Returns:: dict which may be rendered to the worker as an HTML table when they abort the experiment.

append_failure_tags(*tags)[source]¶

Appends tags to the participant’s list of failure tags. Duplicate tags are ignored. See failure_tags for details.

Parameters:

*tags – Tags to append.

Returns:

psynet.participant.Participant – The updated Participant object.

assignment_id¶: A String, the assignment id of the participant.

base_pay¶: The amount the participant was paid for finishing the experiment.

bonus¶: the amount the participant was paid as a bonus.

calculate_reward()[source]¶

Calculates and returns the currently accumulated reward for the given participant.

Returns:: The reward as a float.

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

details¶: a generic column for storing structured JSON data

end_time¶: The time at which the participant finished.

entry_information¶: column containing structured data from the recruiter

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.

property failure_cascade¶

List of callables to determine which related objects to fail when fail() is called on this object.

By default, no related objects are failed, but subclasses can provide a list of functions (typically bound instance methods) which will be called in order to retrieve additional objects on which to call fail().

Example: The following implentation would cause fail() to be called on each value returned by self.nodes(), and then on each value returned by self.questions():

>>> @property
>>> def failure_cascade(self):
>>>     return [self.nodes, self.questions]

fingerprint_hash¶: A String, the fingerprint hash of the participant.

hit_id¶: A String, the id of the hit the participant is working on

mode¶

live, sandbox or debug.

Type:: A String, the mode in which Dallinger is running

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.

recruiter_id¶: A String, the nickname of the recruiter used by this participant.

status¶

String representing the current status of the participant, can be:

working - participant is working
overrecruited - number of recruited participants exceed number required for the experiment, so this participant will not be used
recruiter_submission_started - participant has submitted their assignment to their recruiter, but the recruiter is still processing it
submitted - participant’s assignment submission processing has been completed by their recruiter
approved - their work has been approved and they have been paid
rejected - their work has been rejected
returned - they returned the hit before finishing
abandoned - they ran out of time
did_not_attend - the participant finished, but failed the attention check
bad_data - the participant finished, but their data was malformed
missing_notification - this indicates that Dallinger has inferred that a Mechanical Turk notification corresponding to this participant failed to arrive. This is an uncommon, but potentially serious issue.

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 “participant”. This allows subclassing.

unique_id¶: A String, a concatenation of worker_id and assignment_id

vars¶

worker_id¶: A String, the worker id of the participant.