MatchMaker — alfred3_interact

Skip to main content
`Ctrl`+`K`

# 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)

  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.