====== Randomization ======

Randomization is used to assign a participant at random to an experimental group (random sampling). 

This is different to [[rotation|rotation]], in which the order of questions or items is varied in order to reduce bias that might be introduced by the order in which questions/choices are listed on the page.

Tip: Read the chapters [[php|Introduction to PHP]] and [[array|Introduction to Arrays]] for a better understanding of the complex example codes shown below.


===== General Usage =====

The experimental logic (between-subject) assumes that the participants of an experiment are divided into experimental groups. Depending on the group assignment, a question, text, image or video (the treatment or stimulus) is then varied.

Even if your goal "only" is that, for example, half of the participants should answer question A and the other half of the participants should answer question B: Please remember that conceptually a division into experimental groups takes place.


==== Step 1: Assignment to experimental groups ====

Create a question of type [[:en:create:questions:random]]. In the field //Codes (contents)// write a short description of your experimental groups, e.g.

<code>
Control Group
Positive Exemplars
Negative Exemplars
</code>

After saving, SoSci Survey adds a numeric code for each group, e.g.

<code>
1 = Control Group
2 = Positive Exemplars
3 = Negative Exemplars
</code>

With the //Type of drawing// you can decide whether you want to select "Equal distribution in completed questionnaires" instead of "Equally distributed" draw. This can be useful if you expect systematically more drop-outs in an experimental group.

For //Codes drawn per interview// leave the value 1. Thus, the participant is only assigned to one of the experimental conditions/groups. The drawing of several codes is useful for certain within-subject designs.


==== Step 2: Presentation of the Stimulus ====

In **Combine Questionnaire**, drag the newsly created random generator question onto the page in the questionnaire where you want the participant to be assigned to an experimental group. Usually this is the page where the stimulus is presented.

The random generator will now randomly draw one of the defined groups and store its code in a variable with the random generator's ID. For example, if the random generator question has the ID "RG01", the number drawn would be stored in the data set as variable "RG01". In the above example, code 1, 2 or 3 would be stored.

Place an element "PHP-Code" ([[:en:create:php]]) where you want the stimulus to appear (in any case under the random number generator question or on a later page). Here you need the PHP code for a [[:de:create:filters|PHP filter]], which displays the appropriate stimulus depending on the assigned experimental group (=drawn random number).

If the stimulus is a question (i.e. in group A another question from the **List of Questions** is to be displayed than in group B), the function ''[[:de:create:functions:question]]'' is used. For texts, images and videos use the function ''[[:de:create:functions:text]]'', that integrates the HTML code to display the corresponding stimulus from a text module. More about this below and under [[:en:create:images]] and [[:en:create:media]].

The following PHP code would display the question "AB01" in the group "Positive Exemplars", the question "AB02" in the group "Negative Exemplars" and nothing at all in the control group.

<code php>
if (value('RG01') == 2) {
  question('AB01');
} elseif (value('RG01') == 3) {
  question('AB02');
} else {
  // You may omit the else part,
  // nothing happens here
}
</code>

The function ''[[:en:create:functions:value]]'' is responsible for reading the random number drawn from the variable "RG01" (this ID may have to be replaced by the ID of the random generator!) and making it available in the PHP code for the filter.

The other sections of this manual explain various areas of application of randomization.


===== Drawing of a Random Number =====

The random event -- drawing a random number --  lies at the core of every randomization. Generally, there are two possibilities when randomly selecting a stimulus, question, sequence etc: drawing "with" or "without" replacement. 

Once a random number has been drawn for the first time, the continued use is independent of "with" or "without". The random number is selected from the data record through ''[[:en:create:functions:value|value()]]'' and used, for example, in a filter.

  * Often, the best solution for drawing a random number is a functional question of type [[:en:create:questions:random]]. This question's chapter lists a series of applications for randomization.
  * An option to the random generator is [[:en:create:random_urns]]. These may draw combinations of multiple values and are therefore especially useful for multi-factor experiments and conjoint analyses.
  * Very rarely, the different variants of the questionnaire are so diverse that using filters is impractical. If this is the case, the participant can be allocated at random to different questionnaires ([[random_questionnaire|Random Selection for Questionnaires]]). Drawing with replacement is always used when a questionnaire is selected at random. Therefore, the resulting group sizes may vary considerably.

**Tip:** Use ''value()'' to get the previously drawn random value. Note, that ''​value()''​ works already on the same page for random values, and on any later page. This allows to present different parts of the stimulus and/or related questions on different pages.


===== Randomize Stimulus =====

Particularly in experiments, participants often have to be allocated at random to trial and control groups. Put another way: the participant who is to be shown multiple stimuli must be selected at random. 

The follow example shows how one of 4 pictures can be shown by using [[php|PHP code]]. The prerequisite, as described above,  is that you drew a random number between 1 and 4 and saved this in the variable ''RG01''. Furthermore, you have to have uploaded the four pictures beforehand in **Image and Media Files** into the survey project

<code php>
$number = value('RG01');  // select random number drawn

// display graphic depending on the number
// (HTML code used for this)
if ($number == 1) {
  html('<p><img src="stimulus1.png"></p>');
} elseif ($number == 2) {
  html('<p><img src="stimulus2.png"></p>');
} elseif ($number == 3) {
  html('<p><img src="stimulus3.png"></p>');
} elseif ($number == 4) {
  html('<p><img src="stimulus4.png"></p>');
}
</code>

This example shows graphic "stimulus1.png", "stimulus2.png", "stimulus3.png" or "stimulus4.png" at random. As an example, a question evaluating the picture could be displayed below this.

Instead of using ''html()'' to display text or a graphic, ''[[:en:create:functions:text|text()]]'' can also be used to show a longer text, integrate a video or show a question with ''[[:en:create:functions:question|question()]]''.

The following PHP code presents the same image like the avove PHP code. Yet, this code does not use the full HTML code for each image, but a placeholder ''​%filename%''​ and the funktion ''​[[:​en:​create:​functions:​replace]]''​.
<code php>
$code = value('​RG01'​); ​ // Auslesen der gezogenen Zufallszahl

// Grafikdatei in Abhängigkeit von der Zufallszahl in einen Platzhalter schreiben
if ($code == 1) {
  replace('​%filename%',​ '​stimulus1.png'​);​
} elseif ($code == 2) {
  replace('​%filename%',​ '​stimulus2.png'​);​
} elseif ($code == 3) {
  replace('​%filename%',​ '​stimulus3.png'​);​
} elseif ($code == 4) {
  replace('​%filename%',​ '​stimulus4.png'​);​
}
// The HTML code may be embedded via html()
// or (not shown here) as text element
html('<​p><​img src="​%filename%"></​p>'​);​
</​code>​

**Tip:** Placeholders are especially helpful if the stimulus requires more HTML code then shown in the example above (e.g., to embed videos).
	
**Tip:** The name of the PHP variable (the examples use ''​$number''​ and ''​$code''​) is chosen arbitraryly. See also [[en:​create:​variables#​php-variables|PHP variables]].

If your stimuli require extensive HTML code (e.g., videos), when there are substantial differences in the experiment groups' HTML codes, or when a [[:​en:​create:​multilang|multilingual questionnaire]] is employed, then create four texts in the list of questions (e.g., "​RG02"​ to "​RG05",​ //​Layout//​ must be HTML code) and use one of them, depending on the random number:

<code php>
$code = value('​RG01'​); ​ // Getting the previously drawn random number

// Embed text or HTML code
if ($code == 1) {
  text('​RG02'​);​
} elseif ($code == 2) {
  text('​RG03'​);​
} elseif ($code == 3) {
  text('​RG04'​);​
} elseif ($code == 4) {
  text('​RG05'​);​
}
</​code>​


==== Pictures, Texts, Films, HTML ====

In this chapter, several example codes describe how pictures can be rotated or randomized. A HTML tag ''<img>'' is integrated into each code, for example:

<code php>
$number = value('​RG01'​);​

// enter complete HTML code every time 
if ($number == 1) {
  html('<img src="imageA.jpg" alt="election poster candidate A">');
} elseif ($number == 2) {
  html('<img src="imageB.jpg" alt="election poster candidate B">');
}
</code>

<code php>
$number = value('​RG01'​);​

// only determine the image's name in the filter ...
if ($number == 1) {
  $image = 'imageA.jpg';
} elseif ($number == 2) {
  $image = 'imageB.jpg';
}
// ... and only after this generate HTML code 
html('<img src="'.$image.'" alt="election poster">');
</code>

Other content -- e.g. films, stimulus texts etc. -- can be integrated as HTML code in exactly the same way. In addition, see [[media|Media Files in Questionnaires]] for more information. 

It is best to enter HTML codes to integrate film and audio files (stimulus texts) as text elements in **Text Elements and Labels** ([[texts|Texts in Questionnaire]]). These text elements can be integrated using the function ''[[:en:create:functions:text|text()]]''. The equivalent to the code excerpt above would then look as follows:

<code php>
$number = value('​RG01'​);​

if ($number == 1) {
  text('stimulusA');
} elseif ($number == 2) {
  text('stimulusB');
}
</code>

**Note:** The examples above only show excerpts of PHP code that are required to show the stimulus. A random number still has to be drawn and sorted beforehand. (see above).

**Tip:** You can indeed combine multiple elements in a text element -- for instance, a picture with text next to it.

<code>
<table cellspacing="0" cellpadding="0" border="0">
<colgroup>
  <col width="400"> <!-- width of the picture in pixels -->
  <col>
<colgroup>
<tr>
  <td><img src="imageA.jpg" alt="election poster"></td>
  <td style="padding-left: 20px">
    <p>Max Müller supports the citizens' rights. He would like to achieve greater citizen participation and more efficient decision-making with a sustainable concept and substantiated ideas.  
  </td>
</tr>
</table>
</code>


==== Stimulus and Question Together ====

Do you require one question for one part of the stimuli and another question for the rest?

<code php>
$number = value('​RG01'​);​

if ($number == 1) {
  text('stimulusA');
  question('AB01');
} elseif ($number == 2) {
  text('stimulusB');
  question('AB01');
} elseif ($number == 3) {
  text('stimulusC');
  question('AB02');
} elseif ($number == 4) {
  text('stimulusD');
  question('AB02');
}
</code>


===== Randomization of Questions =====

Entire questions are randomized primarily in method experiments --- this is also easy to do with filters. In principle, the process is the same as when a stimulus is randomized: 

<code php>
$number = value('​RG01'​);​

// Display one question or another
if ($number == 1) {
  question('AB01');
} elseif ($number == 2) {
  question('AB02');
}
</code>

It gets a little more tricky if the questions should appear on different pages in the questionnaire. If this is the case, you have to filter in two places:

<code php>
$number = value('RG01');  // Retrieve the random number drawn by RG01

// Display one question or another
if ($number == 1) {
  question('AB01');  // assessment of politician
} else {
  question('AB02');  // assessment of party
}
</code>

<code php>
$number = value('RG01');

if ($number == 1) {
  question('AB02');  // assessment of party
} else {
  question('AB01');  // assessment of politician
}
</code>

In this example, either question AB01 will be shown first and then AB02 later at random -- or the other way round.

===== Randomization of Pages =====

If the page order should be more varied more complexly, then filters can quickly become confusing -- as shown in the example above. The PHP function ''[[:en:create:functions:setpageorder|setPageOrder()]]'' can help in this case. This function varies the sequence of pages in the questionnaire.

<code php>
$number = value('RG01');  // Must have drawn a random number with RG01

if ($number == 1) {
  setPageOrder('q1','q2','mainStart-mainEnd','q3');
} elseif ($number == 2) {
  setPageOrder('q1','mainStart-mainEnd','q2','q3');
} else {
  setPageOrder('q2','q1','mainStart-mainEnd','q3');
}
</code>

You can find further explanations and examples in the section ''[[:en:create:functions:setpageorder|setPageOrder()]]''.


==== Stimuli and Questions on different pages ====

If there is a distinct question for each stimulus variant, and both shall be presented on different pages, use a filter on both pages. As soon as a random number has been drawn once (e.g., as variable ''RG01''), it's available on any subsequent page via ''value()''. This means that a random generator or ''urnDraw()'' needs being placed on a single page, only. Usually immediately before the first filter.

<code php>
// PHP code in the page with the stimulus
$number = value('​RG01'​);​

if ($number == 1) {
  text('​stimulusA'​);​
} elseif ($number == 2) {
  text('​stimulusB'​);​
} elseif ($number == 3) {
  text('​stimulusC'​);​
} elseif ($number == 4) {
  text('​stimulusD'​);​
}
</​code>​

<code php>
// PHP code on a later page that displays the question
$number = value('​RG01'​);​

if ($number == 1) {
  question('​AB01'​);​
} elseif ($number == 2) {
  question('​AB01'​);​
} elseif ($number == 3) {
  question('​AB02'​);​
} elseif ($number == 4) {
  question('​AB02'​);​
}
</​code>​

**Note:​** This solution if, of course, __not__ required if the question is the same, independently from the stimulus.

**Tip:** This variable also allows the distribution of a stimulus (e.g., pages 1 to 3 of a newspaper article) on different pages.


===== Random Selection of Questions =====

Do you want to show 3 questions out of 10 at random, in order to distribute your stimulus across several participants? There are two ways to do so for random draws with and without replacement.

==== Selection with Replacement ====

If it does not matter which combination the questions are shown in __and__ if there the number of cases per question is big enough to cope with statistical fluctuations, then create a list (array) with all questions IDs, shuffle the list and then show the questions with the first three IDs. 

<code php>
// make sure page will not be redrawn when reloaded 
if (!isset($questions)) {
  // list of relevant questions
  $questions = array(
    'AB01', 'AB02', 'AB03', 'AB04', 'AB05',
    'BB01', 'BB02', 'BB03', 'CC01', 'CC02'
  );
  // shuffle list
  shuffle($questions);
  // and save variable for a new display of the page
  registerVariable('questions');
}
// show question, which ranks first after shuffling
question($questions[0]);
// and the questions in second and third place
question($questions[1]);
question($questions[2]);
</code>

**Tip:** If questions should be shown on separate pages, simply place the lines with ''question()'' on separate pages in the questionnaire. 

**Take care:** If you use several types of these selections in the questionnaire, then the line with ''isset()'' can cause trouble. In this instance, use different variables for ''$questions'', for example, ''$questions1'' and ''$questions2'' (of course, this must also be adjusted in ''registerVariable()'').

==== Selection without Replacement ====

If you have to make sure that all questions are shown equally often, you need an urn that contains the possible question IDs in combinations of three. You have to create these combinations beforehand, e.g. in Excel. 

<code>AB01, AB02, AB03
AB01, AB02, AB04
AB01, AB02, AB05
...
AB05, AB03, AB04
AB05, AB04, AB03
</code>

Indeed, there are 60 combinations possible with just 5 questions. If you have distinctly more combinations than participants then you have might have to remove a portion of the combinations systematically -- otherwise it is not guaranteed that the questions will be shown equally often.

In the questionnaire you now draw one of the combinations out of the urn and use the IDs drawn as they are in the ''question()'' function. Please note, in this instance you need 3 variables in the question ''IV01'' using the type "Internal Variables".    

<code php>
urnDraw('questions', 'IV01');
question(value('IV01_01'));
question(value('IV01_02'));
question(value('IV01_03'));
</code>

You can also distribute the ''question()'' functions here on different pages in the questionnaire.


==== Lots of Stimuli ====

If possible, you would like a greater number of objects to be evaluated. Instead of using an ''if'' construction, the ''switch'' construction is somewhat more convenient. Both the following codes have exactly the same effect:

<code php>
$number = value('RG01');  // Random number drawn by RG01
if ($number == 1) {
  $src = 'monkey.jpg';
} elseif ($number == 2) {
  $src = 'brontosaurus.jpg';
} elseif ($number == 3) {
  $src = 'chinchilla.jpg';
} elseif ($number == 4) {
  $src = 'dachshund.jpg';
} elseif ($number == 5) {
  $src = 'elephant.jpg';
} elseif ($number == 6) {
  $src = 'ferret.jpg';
} elseif ($number == 7) {
  $src = 'cheetah.jpg';
} elseif ($number == 8) {
  $src = 'hawk.jpg';
} elseif ($number == 9) {
  $src = 'hedgehog.jpg';
} elseif ($number == 10) {
  $src = 'jaguar.jpg';
}
html('
  <div style="margin: 30px 0px; text-align: center">
  <img src="'.$src.'" alt="animal photo">
  </div>
');
</code>

<code php>
urnDraw('images', 'AX01');
switch (value('AX01_01')) {
  case 1 : $src = 'monkey.jpg'; break;
  case 2 : $src = 'brontosaurus.jpg'; break;
  case 3 : $src = 'chinchilla.jpg'; break;
  case 4 : $src = 'dachshund.jpg'; break;
  case 5 : $src = 'elephant.jpg'; break;
  case 6 : $src = 'ferret.jpg'; break;
  case 7 : $src = 'cheetah.jpg'; break;
  case 8 : $src = 'hawk.jpg'; break;
  case 9 : $src = 'hedgehog.jpg'; break;
  case 10 : $src = 'jaguar.jpg'; break;
}
html('
  <div style="margin: 30px 0px; text-align: center">
  <img src="'.$src.'" alt="animal photo">
  </div>
');
</code>


===== Combinations =====

You are also able to draw an entire combination with an urn, not just a random number. This means it is easy to implement multi-factorial experiments or conjoint analyses. 

This example uses 3 internal variables (''IV01_01'' to ''IV01_03'', labeled as "price", "quality" and "delivery time") and a combination urn with the content below:

<code>
1, 1, 1
1, 1, 2
1, 2, 1
1, 2, 2
2, 1, 1
2, 1, 2
2, 2, 1
2, 2, 2
</code>

In this example, a combination of three is always drawn. Each of the three variables is denoted as either 1 or 2. By using an array, text is assigned to the numbers. In doing so, the value drawn (1 or 2) serves as a key -- this is indicated in square brackets, in order to select the respective element of the array. See [[:en:create:filter-items#arrays|Arrays]].   

<code php>
urnDraw('combi', 'IV01');
// the numbers program three features - text is assigned to them here
$price = array(
  1 => '5 euros',
  2 => '10 euros',
);
$quality = array(
  1 => 'normal',
  2 => 'premium'
);
$deliverytime = array(
  1 => 'quick',
  2 => 'slow'
);
html('
  <h1>Imagine the following basket:</h1> 
  <p>Price: '.$price[value('IV01_01')].'</p>
  <p>Quality: '.$quality[value('IV01_02')].'</p>
  <p>Delivery Time: '.$deliverytime[value('IV01_03')].'</p>
');
</code>

===== Draw Multiples out of Urns =====

**Important:​** If you would like to draw multiple options with an interview, but none of the options must be drawn twice, then use a [[:ene:​create:​questions:​random]] instead of an urn. Please also read the advice at the end of this section.

If you want to draw from different urns you also need several questions with the type "Internal Variables" -- in this example there are three of these types of question "IV01", "IV02" und "IV03".

<code php>
urnDraw('people', 'IV01', 'end');  // draw out first ballot from "people"
urnDraw('people', 'IV02', 'end');  // draw out second ballot from "people"
urnDraw('relationship','IV03', 'end');  // draw out third ballot from "relationship" 
// ballots will not stored until the participant
// reaches the end of the questionnaire - and so drop outs will not be counted in the draw

// now there is age, first name and sex in the "people" ballot
// this is merged as  "age (first name, sex)"
$description1 = value('IV01_01').' ('.value('IV01_02').', '.value('IV01_03').')';
$description2 = value('IV02_01').' ('.value('IV02_02').', '.value('IV02_03').')';
// now in the description there is
// e.g. "Andreas (25, m)" and "Berta (22, w)"
// now it states in the third ballot, what the relationship is
// between the two of them, and a description of the situation 
// is thus created like so:
$complete = $description1.' '.value('IV03_01').' '.$description2;
// e.g. "Andreas (25, m) lives with Berta (22, w)";
// of course, the text could also be integrated in the question via placeholder
html($complete);
</code>

Now onto an even more complicated example which shows how random numbers can be transformed in text elements. In the following example a 6x4 design was assumed -- correspondingly, the "award" urn contains 24 ballots:

<code>
11, 21
11, 22
11, 23
11, 24
12, 21
12, 22
...
16, 23
16, 24</code>

<code php>
// draw a combination out of the "award" urn and save as "A101",
// do not store ballot yet
urnDraw('Award','A101','man');
// values now saved under A101_01 and A101_02
// the first value can be 11-16, the second 21-24
// saves texts in variables $text1 and $text2 
switch (value('A101_01')) {
  case 11: $text1 = '500 euros'; break;
  case 12: $text1 = '1000 euros'; break;
  case 13: $text1 = '1500 euros'; break;
  case 14: $text1 = '2000 euros'; break;
  case 15: $text1 = '2500 euros'; break;
  case 16: $text1 = '3000 euros'; break;
  default: $text1 = 'invalid code: '.value('A101_01');
}
switch (value('A101_02')) {
  case 21: $text2 = 'a friend'; break;
  case 22: $text2 = 'a relative'; break;
  case 23: $text2 = 'a colleague'; break;
  case 24: $text2 = 'your boss'; break;
  default: $text1 = 'invalid code: '.value('A101_02');
}
$situation = $text2.' wants to from you '.$text1.' borrow';
// save in placeholder %situation% 
replace('%situation%', $situation);
// question regarding situation (with placeholder %situation%)
question('AL07');
</code>

When all relevant information has been requested the ballot will be stored on a later page:

<code php>
urnPutAway('A101');
// or in this case also simply just
urnPutAway();
</code>

**Note:** When drawing out of multiple urns, an equal distribution of the individual drawings is indeed guaranteed, but an equal distribution of the combinations is not. Several combinations may appear considerably more often than others. Use __one__ [[#urn_with_multiple_values_per_ballot|Urn with Multiple Values per Ballot]] to evenly distribute the combinations as well.

**Note:** If you draw out of the same urn twice, then you can get two of the same ballots in the process of doing so. To avoid this, only work with one of the urns that contains all the necessary combinations.

===== Urns for Subgroup I =====

It may be the case that you need to ensure equal distribution of experimental groups in two subgroups -- for instance, if you have 3 stimuli and both the women in the study, as well as the men, should be equally divided between all three conditions.

To do so, you require an internal variable and two urns (with the same content). The following example assumes that the sex was queried on an earlier page in the multiple-choice question SD02. Also, that you have set up two urns with the IDs "women" and "men", both of which contain the numbers 1 to 3 (each one on a separate line).

<code php>
if (value('SD02') == 1) {
  urnDraw('women', 'IV01', 'end');
} else {
  urnDraw('men', 'IV01', 'end');
}

// show stimulus
$z = value('IV01_01');
if ($z == 1) {
  text('stimulus1');
} elseif ($z == 2) {
  text('stimulus2');
} elseif ($z == 3) {
  text('stimulus3');
}
</code>


===== Urns for Subgroup II =====

If possible, the different subpopulations (e.g. men and women) should also get given different stimuli. A simple solution would be to put different numbers in the urns.  

For the following example, you need an "internal variables" question IV01, with one item and two urns with the IDs "women" (numbers 1 to 3, with each one in a separate line) and "men" (number 4 to 6). Additionally, the sex must have been prompted beforehand in the multiple-choice question SD02. 

Apart from that, the PHP code is largely identical with the previous example. 

<code php>
if (value('SD02') == 1) {
  urnDraw('women', 'IV01', 'end');
} else {
  urnDraw('men', 'IV01', 'end');
}

// show stimulus
$z = value('IV01_01');
if ($z == 1) {
  text('stimulusF1');
} elseif ($z == 2) {
  text('stimulusF2');
} elseif ($z == 3) {
  text('stimulusF3');
} elseif ($z == 4) {
  text('stimulusM1');
} elseif ($z == 5) {
  text('stimulusM2');
} elseif ($z == 6) {
  text('stimulusM3');
}
</code>