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
, andIndividualSpec
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()
, andmatch_to()
. Call one of these methods in theWaitingPage.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 withmatch_chain()
.See also
See
SequentialSpec
andParallelSpec
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
Verifies that the MatchMaker is active and aborts the experiment if necessary.
Verifies that the MatchMaker has available slots for new groups.
Shorthand method for conducting a match if there is only a single spec.
Offers prioritized matchmaking based on multiple specs.
Conducts a match to a random feasible group specification.
Matches participants to a group based on a specific spec.
Toggles MatchMaker activation.
Attributes
Returns True if the MatchMaker is active.
List of experiment sessions currently active and waiting to be matched.