MatchMaker.match_random()#

MatchMaker.match_random(wait: Optional[int] = None, nmin: Optional[int] = None)[source]#

Conducts a match to a random feasible group specification.

Parameters

  • wait (int) – Number of seconds to wait before actually starting a matching effort. Defaults to None, which means that there is no waiting time.

  • nmin (int) – Minimum number of waiting participants that must be active before actually starting a matching effort. If there are nmin participants waiting, matching will start even if the waiting time specified in wait is not over yet. Thus, nmin can be used to cut the waiting time short. Defaults to None, which means that waiting time alone determines when matching will start. Note: The parameter nmin will only take effect, if wait is not None.

This is the right method, if you wish to randomize participants into groups of different sizes.

Important

match_random() matches randomly among all feasible specs at the time of matching. A spec is feasible if there are enough participants waiting for a group based on that spec.

For instance, let’s say you have an IndividualSpec and a ParallelSpec with two roles, forming a dyad. Four participants are scheduled for a session. Participant 1 logs in one minute early, Participant 2 is on time, Participant 3 logs in 30 seconds late, and Participant 4 logs in 2 minutes late. All of them will be matched immediately to the IndividualSpec, because this spec is always feasible. The ParallelSpec on the other hand requires at least two participants to be waiting simultaneously.

This behavior can be adjusted through the arguments wait and nmin. In this example case, you may, for instance, specify nmin=3 and wait=2*60 to ensure that there is some time for participants to register. Participants 1, 2, and 3 will be matched to a random spec once Participant 3 logs in, because nmin has been reached. Participant 4 will wait for two minutes before being assigned to the individual spec. The possible outcomes are: (1) Four individual specs (if the randomization does not lead to the formation of a dyad), (2) two individual specs and one parallel spec (if a dyad is formed in the randomization).

The method match_chain() may be an even more suitable option.

Note

Randomization into groups of different sizes can be a little tricky because large groups may have an unequal (lower) chance of being filled at the same rate as smaller groups due to participant dropout. We provide the arguments wait and nmin to improve the feasibility of such designs. However, the method match_chain() may be an even more suitable option.

Raises

NoMatch – If a single matching effort was unsuccesful. This exception gets handled by WaitingPage and is part of a normal matching process.

Returns

The group object.

Return type

Group

See also

match_chain()

Examples

import alfred3 as al
import alfred3_interact as ali

exp = al.Experiment()

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

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

    def wait_for(self):
        group = self.exp.plugins.mm.match_random()
        self.exp.plugins.group = group
        self.exp.condition = group.data.spec_name
        return True

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

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

        self += al.Text(f"Successfully matched to role '{role}' in condition '{cond}'")