MatchMaker#

class alfred3_interact.match.MatchMaker(*groupspecs, exp, name: str = 'matchmaker', inactive_page=None, full_page=None, raise_exception_if_full: bool = False, respect_version: bool = True, ping_timeout: Union[float, int] = 15)[source]#

Bases: object

Creates groups of multiple experiment sessions.

Parameters
  • *groupspecs – Variable number of group specifications. Each spec defines one blueprint for a group. Currently, ParallelSpec, SequentialSpec, and IndividualSpec are supported.

  • exp (alfred3.ExperimentSession) – Associated experiment session.

  • name (str) – An identifier for the matchmaker. Must be unique within one experiment. Can (and must) be set to a custom value, if you wish to use multiple matchmakers in a single experiment. Defaults to ‘matchmaker’.

  • inactive_page (alfred3.Page) – Page to be displayed to participants if the matchmaker is inactive. If None (default) a default page will be used.

  • full_page (alfred3.Page) – Page to be displayed to participants if all specs have reached their quota of groups. If None (default) a default page will be used.

  • raise_exception_if_full (bool) – As an alternative to using a full_page, you can let the MatchMaker raise the AllSlotsFull exception if all specs have reached their quota of groups. Defaults to False.

  • respect_version (bool) – If True, the MatchMaker will only match sessions that run on the same experiment version into the same group. This setting makes sure that there’s no strange behavior if you make changes to an ongoing experiment. Defaults to True.

  • ping_timeout (float, int) – When matching parallel groups (i.e. groups based on ParallelSpec), only active sessions are included in the matchmaking process. Sessions therefore send a signal of activity to the server on a regular schedule. The argument ping_timeout determines the number of seconds of inactivity before a session is considered to be inactive. Defaults to 15 seconds.

The workhorse methods of the MatchMaker are match_random(), match_chain(), and match_to(). Call one of these methods in the WaitingPage.wait_for() hook to start the matchmaking process.

To initialize the MatchMaker, you must first create a group specification, which is a sort of blueprint for building a group. The spec defines the size of the group, the roles that can be assigned to participants, and the number of groups that should be created based on that spec. If you supply multiple specs, you can randomize group creation with match_random() or create an order of priority with match_chain().

See also

See SequentialSpec and ParallelSpec for more information on specs.

Examples

A minimal example with a single spec:

import alfred3 as al
import alfred3_interact as ali

exp = al.Experiment()

@exp.setup
def setup(exp):
    spec = ali.SequentialSpec("a", "b", nslots=10, name="spec1")
    exp.plugins.mm = ali.MatchMaker(spec, exp=exp)

@exp.member
class Match(ali.WaitingPage):

    def wait_for(self):
        group = self.exp.plugins.mm.match_to("spec1")
        self.exp.plugins.group = group
        return True

@exp.member
class Success(al.Page):

    def on_first_show(self):
        group = self.exp.plugins.group
        role = group.me.role

        self += al.Text(f"Successfully matched to role: {role}")

Methods

check_activation

Verifies that the MatchMaker is active and aborts the experiment if necessary.

check_quota

Verifies that the MatchMaker has available slots for new groups.

match

Shorthand method for conducting a match if there is only a single spec.

match_chain

Offers prioritized matchmaking based on multiple specs.

match_random

Conducts a match to a random feasible group specification.

match_to

Matches participants to a group based on a specific spec.

toggle_activation

Toggles MatchMaker activation.

Attributes

active

Returns True if the MatchMaker is active.

waiting_members

List of experiment sessions currently active and waiting to be matched.