Sync

class psynet.sync.Barrier(id_, waiting_logic=None, waiting_logic_expected_repetitions=3, max_wait_time=20, fix_time_credit=False)[source]

Bases: EltCollection

A barrier is a timeline construct that holds participants in a waiting area until certain conditions are satisfied to release them. The decision about which participants to release at any given point is taken by the choose_who_to_release method, which the user is expected to provide.

Parameters:

  • id – ID parameter for the barrier. Barriers with the same ID share waiting areas; this allows participants at different points in the timeline to share the same waiting areas.

  • waiting_logic – Either a single timeline element or a list of timeline elements (created by join) that is to be displayed to the participant while they are waiting at the barrier. If left at the default value of None then the participant will be shown a default waiting page.

  • waiting_logic_expected_repetitions – The number of times that the participant is expected to experience the waiting_logic during a given barrier visit. This is used for time estimation.

  • max_wait_time – The maximum amount of time in seconds that the participant will be allowed to wait at the barrier; if this time is exceeded and the participant is still not released, then the participant will be failed and sent to the end of the experiment.

  • fix_time_credit – If set to True, then the amount of time ‘credit’ that the participant receives will be capped according to the estimate derived from waiting_logic and waiting_logic_expected_repetitions.

choose_who_to_release(waiting_participants)[source]

Given a list of waiting participants, decides which of these participants should be released from the barrier.

Parameters:

waiting_participants (List[Participant]) – A list of waiting participants.

Return type:

List[Participant]

Returns:

  • A list of participants to be released.

classmethod get_waiting_participants_from_barrier_id(barrier_id, for_update=False)[source]

Gets the participants currently waiting at a barrier.

Parameters:

  • barrier_id (str) – The ID of the barrier to check.

  • for_update (bool) – Set to True if you plan to update the resulting participant objects and their barrier links. The objects will be locked for update in the database and only released at the end of the transaction.

Return type:

List[Participant]

Returns:

  • A list of waiting participants. Note that this only includes currently active participants

  • (not participants who failed and left the experiment).

class psynet.sync.GroupBarrier(id_, group_type, waiting_logic=None, waiting_logic_expected_repetitions=3, max_wait_time=20, on_release=None, fix_time_credit=False)[source]

Bases: Barrier

A GroupBarrier is a Barrier that waits until all participants in a given SyncGroup have reached the Barrier. It also checks the current group size against the group’s minimum size parameter; the group won’t be allowed to proceed if it’s below this size. If join_existing_groups=True for that group, it’ll wait just in case new participants join the group. If join_existing_groups=False, then there’s no hope for new participants, so the group will be released and failed.

Parameters:

  • id – ID parameter for the Barrier. Barriers with the same ID share waiting areas; this allows participants at different points in the timeline to share the same waiting areas.

  • group_type (str) – Identifies the kind of groups that the Barrier is operating over (see Grouper).

  • waiting_logic – Either a single timeline element or a list of timeline elements (created by join) that is to be displayed to the participant while they are waiting at the barrier. If left at the default value of None then the participant will be shown a default waiting page.

  • waiting_logic_expected_repetitions – The number of times that the participant is expected to experience the waiting_logic during a given barrier visit. This is used for time estimation.

  • max_wait_time – The maximum amount of time in seconds that the participant will be allowed to wait at the barrier; if this time is exceeded and the participant is still not released, then the participant will be failed and sent to the end of the experiment.

  • fix_time_credit – If set to True, then the amount of time ‘credit’ that the participant receives will be fixed according to the estimate derived from waiting_logic and waiting_logic_expected_repetitions.

choose_who_to_release(waiting_participants)[source]

Given a list of waiting participants, decides which of these participants should be released from the barrier.

Parameters:

waiting_participants (List[Participant]) – A list of waiting participants.

Returns:

  • A list of participants to be released.

class psynet.sync.GroupCloser(group_type, **kwargs)[source]

Bases: GroupBarrier

A timeline construct for closing a previously created group. This is required before creating a new group with the same group_type.

class psynet.sync.Grouper(group_type, id_=None, waiting_logic=None, waiting_logic_expected_repetitions=3, max_wait_time=20)[source]

Bases: Barrier

A Grouper is a kind of Barrier that assigns incoming participants into groups. This is a generic class that requires several methods to be overrun, in particular ready_to_group and group.

Parameters:

  • group_type (str) – A textual label for the groups that are created. This label is used to link the Grouper with subsequent GroupBarriers.

  • id – Optional ID parameter for this grouper. If left blank the default value is group_type + "_" + "grouper". Groupers with the same ID are treated as equivalent and share the same participant waiting areas.

  • waiting_logic – Either a single timeline element or a list of timeline elements (created by join) that is to be displayed to the participant while they are waiting at the barrier. If left at the default value of None then the participant will be shown a default waiting page.

  • waiting_logic_expected_repetitions – The number of times that the participant is expected to experience the waiting_logic during a given barrier visit. This is used for time estimation.

  • max_wait_time – The maximum amount of time in seconds that the participant will be allowed to wait at the barrier; if this time is exceeded and the participant is still not released, then the participant will be failed and sent to the end of the experiment.

choose_who_to_release(waiting_participants)[source]

Given a list of waiting participants, decides which of these participants should be released from the barrier.

Parameters:

waiting_participants (List[Participant]) – A list of waiting participants.

Returns:

  • A list of participants to be released.

group(participants)[source]

This method is run if ready_to_group returns True. It is responsible for grouping participants.

Parameters:

participants (List[Participant]) – Participants who are candidates for grouping.

Return type:

A list of SyncGroups who should be populated by the grouped participants.

ready_to_group(participants)[source]

Determines whether the Grouper is ready to group a given collection of participants. Note that not all participants need to be grouped at once; it’s permissible to leave some participants still waiting.

Parameters:

participants (List[Participant]) – List of participants who are candidates for grouping.

Return type:

bool

Returns:

  • True if the grouper is ready to group (some of) the participants, False otherwise.

select_leader(participants)[source]

By default the leader is randomly chosen from the list of available participants.

Parameters:

participants (List[Participant]) – Participants to choose from.

Return type:

Participant

Returns:

  • A participant to be assigned ‘leader’ of the SyncGroup.

class psynet.sync.ParticipantLinkBarrier(*args, **kwargs)[source]

Bases: Base, SQLMixin

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.sync.ParticipantLinkSyncGroup(*args, **kwargs)[source]

Bases: Base, SQLMixin

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.sync.SimpleGrouper(group_type, *, initial_group_size=None, max_group_size='initial_group_size', min_group_size='initial_group_size', batch_size='initial_group_size', join_existing_groups=False, **kwargs)[source]

Bases: Grouper

A Simple Grouper waits until batch_size many participants are waiting, and then randomly partitions this group of participants into groups of size initial_group_size.

Parameters:

  • group_type (str) – A textual label for the groups that are created. This label is used to link the Grouper with subsequent GroupBarriers.

  • initial_group_size (Optional[int]) – Size of the groups to create.

  • max_group_size (Union[int, str, None]) – If join_existing_groups=True, then participants will be allowed to join groups until they reach this maximum size. If set to "initial_group_size" (default), then the maximum size will be set to the initial group size.

  • min_group_size (Union[int, str]) – If the current group size is below this value (taking into account failed participants and participants who have left the experiment), then the group will be considered under-quota. The group will not be allowed to pass through barriers until it is at or above this size. If set to "initial_group_size" (default), then the minimum size will be set to the initial group size.

  • batch_size (Union[int, str]) – Number of participants that should be waiting until the groups are created. If set to "initial_group_size" (default), then the batch size will be set to the initial group size.

  • join_existing_groups (bool) – If set to True, then before a new group is created, the Grouper will check if there are any existing groups that are under-quota (e.g. because some participants left the experiment early). If so, the arriving participant will be assigned to one of these groups instead.

  • kwargs – Further arguments to pass to Grouper.

group(participants)[source]

This method is run if ready_to_group returns True. It is responsible for grouping participants.

Parameters:

participants (List[Participant]) – Participants who are candidates for grouping.

Return type:

A list of SyncGroups who should be populated by the grouped participants.

ready_to_group(participants)[source]

Determines whether the Grouper is ready to group a given collection of participants. Note that not all participants need to be grouped at once; it’s permissible to leave some participants still waiting.

Parameters:

participants (List[Participant]) – List of participants who are candidates for grouping.

Return type:

bool

Returns:

  • True if the grouper is ready to group (some of) the participants, False otherwise.

class psynet.sync.SimpleSyncGroup(*args, **kwargs)[source]

Bases: SyncGroup

A SyncGroup that is created by a SimpleGrouper.

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.sync.SyncGroup(*args, **kwargs)[source]

Bases: Base, SQLMixin

A SyncGroup represents a group of participants that are synchronized at various points in the experiment. Such groups are created by Groupers and synchronized by GroupBarriers.

leader

The leader of the SyncGroup. This can be reassigned by logic such as group.leader = participant.

Type:

Participant

participants

A list of participants in that group. Additional participants can be added by logic such as group.participants.append(participant).

Type:

List[Participant]

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