Differences

This shows you the differences between two versions of the page.

--- en:create:randomization [06.06.2017 12:52] – [Drawing of a Random Number] admin
+++ en:create:randomization [19.12.2018 11:07] – [Urns for Subgroup II] freekgille
@@ Line 6: / Line 6: @@
 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>
+= Control Group
+= Positive Exemplars
+= 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 =====
@@ Line 16: / Line 75: @@
   * 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.
@@ Line 42: / Line 103: @@
 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>
@@ Line 50: / Line 151: @@
 <code php>
+$number = value('RG01');
 // enter complete HTML code every time
 if ($number == 1) {
@@ Line 58: / Line 161: @@
 </code>
-<code>
+<code php>
+$number = value('RG01');
 // only determine the image's name in the filter ...
 if ($number == 1) {
@@ Line 74: / Line 179: @@
 <code php>
+$number = value('RG01');
 if ($number == 1) {
   text('stimulusA');
@@ Line 106: / Line 213: @@
 <code php>
+$number = value('RG01');
 if ($number == 1) {
   text('stimulusA');
@@ Line 127: / Line 236: @@
 <code php>
+$number = value('RG01');
+// Display one question or another
 if ($number == 1) {
   question('AB01');
@@ Line 137: / Line 249: @@
 <code php>
-// show the one or the other question
 $number = value('RG01');  // Retrieve the random number drawn by RG01
+// Display one question or another
 if ($number == 1) {
   question('AB01');  // assessment of politician
@@ Line 148: / Line 261: @@
 <code php>
 $number = value('RG01');
 if ($number == 1) {
   question('AB02');  // assessment of party
@@ Line 163: / Line 277: @@
 <code php>
 $number = value('RG01');  // Must have drawn a random number with RG01
 if ($number == 1) {
   setPageOrder('q1','q2','mainStart-mainEnd','q3');
@@ Line 173: / Line 288: @@
 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.
@@ Line 332: / Line 486: @@
 ===== 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".
@@ Line 416: / Line 572: @@
 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 2 (each one on a separate line).
+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>
@@ Line 441: / Line 597: @@
 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 IVO1, 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.
+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.