MatchMaker.match_random() — alfred3_interact

Skip to main content
`Ctrl`+`K`

# MatchMaker.match_random()

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

  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}'")