====== Randomization Using Urns ======

A random draw can be carried out without replacement by using the urn function -- this ensures, for example, that experimental groups remain even.

The chapter describes step by step how to create an urn and how to draw a ballot (e.g. a random number) out of the urn. The chapter [[randomization|randomization]] describes how the ballot drawn is used in randomization.

**Important:** A [[:en:create:questions:random]] is more appropritate than urns for most use cases. If your goal is to "just" sort respondents into experimental groups, and present questions, images or texts to them, then please read [[:en:create:randomization]].

**Important:** Urns are the best solution only for very few special ue cases. Please 
en sind nur für wenige spezielle Anwendungsfälle die beste Lösung. Please be sure to read the chapter on [[:en:create:randomization]], __before__ you continue reading here (if that should be necessary at all then).
==== Drawing without Replacement ====

A random draw "without replacement" can be likened to a draw from a lottery wheel ("urn"). The use of urns in SoSci Survey (like the the [[:de:create:questions:random]]) guarantees experimental groups of the same size. In the context of conjoint analysis, an urn ensures that predefined combinations are equally likely to be drawn. 

**Advice:** Entire questionnaires __cannot__ be randomized using urns. An urn cannot be used to "choose" between different questionnaires. In order to use an urn, all random conditions in the questionnaire have to be set using a filter (see [[:en:create:randomization]]).

**Note:** Be sure to carry out a technical test to check whether the drawing of lots in the urn are counted correctly, in particular, if you store the combinations manually.

The basic steps to draw from an urn are as follows:

  - Add a new question in the **List of Questions** using the type [[:de:create:questions:internal|Internal Variables]] (e.g. with ID ''IV01'')
  - In **Special Features** -> **Randomization Using Urns** -> //Create new urn//, e.g. with the //ID// ("group") and enter ballots 1, 2, 3, 4 (each number on a separate line)
  - [[php|PHP code]] is used to carry out the actual random draw.

<code php>
urnDraw('group', 'IV01');
</code>

**Note:** Only the question ID is entered as the second parameter in the function ''[[:en:create:functions:urndraw|urnDraw()]]'', and not the variable ID. This means SoSci Survey can decide, depending  on the content of the urn, if only one variable is used (if each ballot only contains one value) or several variables (if you are working with combinations of values).

**Note:** You can decide whether the ballot drawn should be stored immediately or not until later. Read the the reference to the PHP function ''[[:en:create:functions:urndraw|urnDraw()]]'' for more information.

**Note:** Normally the urn is re-filled after the last ballot is drawn and stored. If you do not want this to happen, you can prevent this happening directly with the drawing: see ''[[:en:create:functions:urndraw|urnDraw()]]''


===== Create an Urn =====

First of all, you need to create an urn. An urn contains multiple ballots -- and each ballot can have one value (normally a number) or a combination of several values.

  * Select **Special Features** in the menu and then -> **Randomization using Urns**.
  * Click on **Create new urn**. You will see form in which you can enter a //Name// (urn ID, e.g. "group") for the new urn, as well as its content (//combinations//). 
  * Enter the content (//combinations//) as follows: one line for every ballot -- if there is more than one value in the ballot, separate the values with a comma or tab (not with spaces!). **Tip:** when there are combinations, you can create a table in a spreadsheet programme of your choice (e.g. OpenOffice Calc or Excel), in which the different values (e.g. age, first name, sex) are written in individual columns and you can then enter the combinations in the rows. Select the cells (only those with content; no headings) and copy the content into the text input field for //combinations//.
  * The urn will be saved when you click on **Create new urn**. 
  * Note down the urn //ID//.

Most often, urns are used to divide participants into experimental groups. When this is the case, one number per line is recommended. If you have 4 groups, the content of the urn will look as follows:

<code>1
2
3
4</code>

You can get a weighting by writing a row multiple times in the urn. By using the following urn, twice as many participants will be placed in Group 1 than in Group 2 or 3:

<code>1
1
2
3</code>

If you have 3 groups, where a second factor should be varied within the third experimental group, the content of the urn would look as follows (on this occasion, the combinations change):

<code>1, 0
1, 0
2, 0
2, 0
3, 1
3, 2</code>

**Note:** In order to ensure that respondents cannot just choose any ballot they please, a ballot will only be drawn once per questionnaire. This means, that even if they try to update the page (F5 button in the browser, i.e. "reload page") during testing, they will __always get the same ballot__. In order to get a new ballot, you have to start a new questionnaire.

===== Create Internal Variables =====

The ballot, or combination, drawn has to be be saved in the data record. To do so, you need [[:en:create:variables|internal variables]]. 

  * Add a new question in the **List of Questions** with the //type// "Internal Variables".
  * Add one or multiple variables (items) in this question. 
  * For the //Description// (text) of the internal variables, enter the ID that the variables should have later in the data record, e.g. "group" or "random number".
  * If you only have one value in each ballot (only one column in the urn, like in the example above), you only need __one__ variable (one item).
    * If you are using combinations (multiple values per ballot, and so multiple columns in the urn), you need the same number of variables as the number of values the combinations have. For example, if you have 10 ballots with 3 values in your urn, you need to have 3 variables in the question.
    * Note down the question ID that you have just created (e.g. ''IV01''). 

**Important:** Please use this question of type "Internal Variables" for the urn exclusively. Although it is technically possible to create further variables in the question, do not store data there via ''put()''. If you need to store additional data, create another question. Drawing from the urn will not work if something is stored in __any__ variable of the question.  


===== Draw a Ballot from the Urn =====

[[php|PHP code]] is now used in the questionnaire to draw a ballot from the urn. The function ''[[:en:create:functions:urndraw|urnDraw()]]'' is available in order to do this. The content of the urn drawn (either an individual random number or a combination) is stored in the internal variables, which you set up beforehand. Subsequently, you can use the value(s) drawn in filters or placeholders (see [[randomization|randomization]]).

When using ''urnDraw()'', you need the IDs that you noted down above (urn ID, "internal variable" question ID). Additionally, you need to decide, when the ballot should be stored, Normally, (not specified or '''now''') the ballot is stored straight away. If the participants in a test group systematically drop out more frequently, then there are fewer complete questionnaires in this group. If you expect to encounter problems because of this, use '''end''' or '''man''' (see reference to ''[[:en:create:functions:urndraw|urnDraw()]]').

**Note:** If you want to manually store a ballot from an urn (third parameter '''man'''), make sure that you also employ the function ''[[:en:create:functions:urnputaway|urnPutAway()]]''.


<code php>
urnDraw('group', 'IV01');
</code>

For the uses of ballots (or combinations) drawn, please read the chapter [[randomization|randomization]].