VI. Random Group and Role Assignment


In this tutorial I will explain, and give you sample code, which can be used to generate randomly assigned IDs (e.g. Subject, Group, Role, etc). If you want to dive into the program immediately, you can find the source code on Github. I do encourage you to read through the tutorial to get a better understanding of the algorithm used. Doing so will empower you not only to use this algorithm, but to build different and more powerful solutions that those I have provided for you here.

Starting with A Simple Case: Randomly Shuffling Subject IDs

How would you go about randomly assigning IDs to a group of subjects without the use of a computer? One possibility would be to write down a sequence of IDs on a deck of cards (1-N), shuffle it, and pass each card to a subject. This will generally be the method (Algorithm) we will be using, called the Fisher-Yates shuffle (Durstenfeld method), to randomly shuffle IDs in an array.

In order to understand the provided source code you should be familiar with concept of an array, while loop, and the random number generation function. Fortunately, if you’re not, tutorials on each topic can be found on our main Z-Tree tutorial page.

In the following section I will illustrate the steps the shuffling algorithm takes to produce a shuffled list of IDs.

A Walking Through The Algorithm

In this section I will walk you through the algorithm, supplying you with illustrations, and source code. If you just want to get an intuition for how the algorithm works, you are free to skip the source code and just look at the diagrams and descriptions. Lets get started.

Following our pen and paper analogy, the first initial steps required to shuffle subject IDs is to, get a deck of index cards, and write down the sequence of subject IDs. To implement that in code we will first state how many subjects we have in this session, stored in numSubjects. Then we will create an array (deck) in which we will store, and shuffle the Subject IDs.


Screen Shot 2015-02-20 at 10.40.15 AM

Note: When a Z-Tree array is created it will contain all zeros.

The next step is to write down the IDs of each subject sequentially onto each card. We will do this in code with the help of a while loop. The loop will step through each element (card) in the array (deck), and assign the corresponding id (1-4) to each element. As shown below:


Screen Shot 2015-02-19 at 4.50.52 PM

Now that we have placed all of the subject IDs in each element of the array we will now begin the shuffling phase. I will illustrate the shuffling first and provide you with the code at the end.

We begin the shuffling algorithm by pointing to the last element in the array at index 4.

Screen Shot 2015-02-20 at 11.35.39 AM

We randomly draw an index ID between 1 and 4, lets say index 2.

Screen Shot 2015-02-19 at 4.49.05 PM

Swap the values at random index 2, with index 4. 

Screen Shot 2015-02-20 at 11.35.00 AM


Subtract 1 from the old pointer index 4 to produce the new pointer index 3.

Screen Shot 2015-02-20 at 10.57.46 AM

Again we random select a index, but between 1 and 3, instead of 1-4. Lets say index 3 is randomly chosen

Screen Shot 2015-02-19 at 5.00.38 PM

Our random index 3 just happens to be the same as our pointer index 3. We swap it with itself, to keep the algorithm simple. Yet the position remains the same.

We decrement the index pointer again to produce index 2.

Screen Shot 2015-02-20 at 11.08.07 AM

We randomly select an new index between 1 and 2. Lets say index 1 is randomly chosen. We swap it.

Screen Shot 2015-02-20 at 11.14.54 AM

The pointer index index 2  is decremented to index 1, and the algorithm stops.

Here is the implementation code:



In order to assign the subject IDs to each subject put the following:


All subjects have now been randomly assigned a subject ID.

Now that you know how the algorithm works, In the following sections I will describe how modify the algorithm to to produce group and role Ids. There  are many different kinds of grouping methods, so I might not cover the one your particularly interested in. Yet, if you understand how this algorithm works, and the method I use to modify it, you should be able to taylor it to satisfy your needs.

Tailoring the Shuffling Algorithm: Random Group Assignment

We can taylor this algorithm to produce randomly assigned group IDs by choose which values we will place in the array before we shuffle it. Lets say you have an experiment with two players in each group. Using the deck/card analogy, we simply write the number 1 on the first two cards, increment the ID to 2, write 2 on the next two cards, increment and repeat until we have written ids on each subject card.

Here is the implementation code:



After this step all of the subjects have been assigned a random group ID.


Tailoring the Shuffling Algorithm: Random Role Assignment

Lets say you have an experiment with a sender and receiver. We can taylor our algorithm to assign these roles by filling half of the shuffling array with the sender ID (1), and the remaining half with the receiver ID (2). The role ID array is shuffled using our algorithm, and we assign a role to each subject as we have in previous examples.

Here is the implementation code:






I hope you now understand how the above algorithm works, and are equipped to use in your current and future experiments!

The example code for this tutorial can be downloaded (Forked, Pulled, etc.) from Github.