Matching Service

Multistage provides several different built-in algorithms to divide all of the subjects into groups, and also the ability to write custom matching algorithms and to specify matching manually.

Included Matching Algorithms

Each extension's parameters file, as part of the generic parameters, should supply the following line: match.N.matching=%algorithm% where %algorithm% is one of the options listed below:

  • random
  • totalrandom
  • zipper
  • rr
  • continue
  • fixed
  • file


random is an algorithm which assigns subjects into groups randomly, but will preserve a subject's position in its group when reassigning groups.

For example, if the groupsize is set to 3 and a subject is assigned to be the first player in a group, then for subsequent matches he will remain the first player.

Total Random

totalrandom is an algorithm which assigns subjects to groups in a completely random fashion. It will not preserve group position like the random algorithm will. Each match, all players are put back and chosen into groups again, randomly.


zipper is an algorithm which is specialized for extensions where the group size is 2. It divides the set of subjects into two different groups of equal size, and matches each player in the first group with each player in the second group.

For example, for a subject pool of size 10, the algorithm would first divide them into two columns:

 1  2
 3  4
 5  6
 7  8
 9  10

So for the first match, subject 1 would be paired with subject 2 and subject 3 would be paired with subject 4, and so on. For the second match, the pairings would then be:

 1  4
 3  6
 5  8
 7  10
 9  2

where the right column has been shifted upward by one space, pairing subject 1 with subject 4, and subject 3 with subject 6, and so on.

Notice that for this algorithm, if the number of matches specified is more than half the group size, subjects will be matched with opponents more than once.

Round Robin

rr is another algorithm meant for use with groups of size 2. Round robin allows a player to be matched once with each other player in the experiment, not repeating any pairings until (group size - 1) matchings have been made. The usage of this algorithm requires the use of the rr parameter for the first match, and the use of the continue parameter for each successive match. Using the rr parameter again will restart the round robin algorithm rather than continuing the one started before.

For example, to properly use the rr algorithm, one would specify the matching parameters as follows:


Special Parameters


continue is a special parameter used to tell the matching service to continue using a previously initialized and started matching algorithm. For manual matching algorithms, it tells the software to call the continueManualMatching method rather than the manualMatching method of the implementing class when determining groups.


fixed is a special matching parameter which is used to use exactly the same grouping in a match as in the previous match.

For example:


would randomly assign the group for match 0, but wouldn't reassign groups for match 1, but rather use the same groups again.


file is a parameter used to enable file-based subject matching, in which any subject matching can be specified. When file is used, a second parameter must be added to the parameter file, indicating the location of the matching file:


where the matchFile parameter gives the path to the matching file. <br>Note: The double backslashes are required for windows paths

The format of the matching format is described in the File Matching Format section.

Custom Matching Algorithms

If matching behavior is desired which cannot be accomodated by any combination of the existing matching algorithms, Multistage allows for the creation of custom matching algorithms. Custom matching algorithms are created by extending the ManualMatcher? class, located in:


with a class placed in:


The custom matching algorithm must be named in the form %name%Matcher, where %name% is a word which starts with a capital letter. The algorithm must also implement three methods:

    /** Return true if the given group size is compatible with this matcher. For example, a 
     *  'round robin' matching algorithm only matches people into groups of two, so it is
     *  incompatible with a group size of 3. Return false to indicate incompatibility (or throw
     *  an InvalidParameterException )*/
    public abstract boolean verifyGroupSize(int groupSize) throws InvalidParameterException;
    /** Return a representation of the groups to use in matching. Indexed by groupnumber, the
     *  array should be of the form int[][] groups = new int[numGroups][groupSize]. Save key
     *  information used to generate these groups for use in the continueManualMatching method.
     *  This is the first method called in ManualMatcher extensions, and it is only called once in
     *  order to initialize the algorithm to be used subsequently by continueManualMatching(). In other
     *  words, each time matching=someManualMatching, the previous manual matching object is destroyed,
     *  a new one is created, and this method is called. Each time matching=continue for a manual
     *  matching scheme, continueManualMatching() is called */
    public abstract int[][] manualMatching() throws Exception;
    /** Continue the algorithm that was begun in manualMatching. This is called each time matching=continue
     *  for a manual matching scheme. This method relies on static information stored by the
     *  manualMatching method */
    public abstract int[][] continueManualMatching() throws Exception;

In order to use the custom matching algorithm, the matching parameter must be the exact same name as was given the implementing matcher class, so if the java class is called CustomMatcher?, then the parameter used to specify it is: match.0.matcher=Custom

Manual Matching Algorithm

The format of the file required to use manual matching is described in the File Matching Format section.

Last modified 6 months ago Last modified on 10/18/2013 04:14:47 PM