====== randomUse() ========
''void **randomUse**(string //questionID//, [array //ballot//])''
The [[:en:create:questions:random|Random generator]] can, among other things, provide for an equally distributed drawing at the time of the drawing or at the end of the interview. The function ''randomUse()'' allows a differentiated control over which ballots are counted as a valid drawing and when.
//questionID// -- The identification of the random generator
//ballot// -- (optional) List of ballots to be stored (ballot numbers, not codes drawn)
**Important:** The function ''randomUse()'' only works if the //type of drawing// for the random generator is set to "Equal distribution in finished interviews (draw without returning)".
===== Function ======
With the function ''randomUse()'' you can specify exactly, ...
* at which time in the interview the drawn notes are considered //drawn yet// and
* which of the drawn ballots should be considered as drawn, if more than one ballots are drawn per interview
The function can only be used after the drawing has taken place, i.e. under the random number generator or on a later page in the questionnaire.
**Tip:** The function ''randomUse()'' can be called several times within an interview, even with different //ballot//-lists. Only those notes are counted as //drawn// which have not been counted before.
====== Example of use ======
Each participant shall be randomly presented with 20 items from a pool of 500 items for rating. For this a random generator ("RG01") is used, which contains 500 ballots and draws 20 ballots per interview.
In order to store the ratings in a separate data line, a [[:en:create:multilevel]] is used: There is a questionnaire for the random drawing and other characteristics at the participant level ("top") and another for the rating of the items ("sub").
The function ''randomUse()'' is needed because participants are able to skip individual items. To do this, a selection question ("CH01") is displayed in the subordinate questionnaire ("sub") to indicate whether the item is to be rated or not.
The superior questionnaire ("top") first contains the random generator. Then 2 pages are repeated 20 times using ''[[:en:create:functions:looptopage]]''. The following PHP code is used for this.
$codes = array_values(valueList('RG01'));
$i = loopToPage('loopEnd', count($codes));
multiLevelDown('sub', $codes[$i]);
// Specify that the ballots are not automatically stored.
randomUse('RG01', array());
Here ''randomUse()'' is used for the first time -- but with an empty list. This ensures that the notes are not automatically stored at the end of the interview if ''randomUse()'' has not been called in the meantime because the participant did not want to answer a single question.
The code of the item to be rated is passed on as a second parameter in the function ''multiLevelDown()''. Thus the subordinate questionnaire ("sub") knows which item is to be rated. This can be, for example, a unique ID for which further information (e.g. a text or the file name of an image) is available in the [[:en:create:databank]].
In the subordinate questionnaire ("sub") the item is displayed and the question is asked whether it should be rated. In addition, the ID of the item is stored in an internal variable IV01_01 so that it is available in the analysis.
// Receive item ID from higher-level questionnaire
$itemID = multiLevelData();
// Retrieve more data from the database for contents and e.g. display an image
$data = dbGet('i'.$itemID);
$image = $data[0];
html('');
// Store ID in an internal variable (important)
put('IV01_01', $itemID);
// Selection question, if participant wants to rate the item
question('CH01');
If the participant doesn't want to rate the item, a PHP filter at the top of the following page ensures that the participant returns directly to the parent questionnaire. Otherwise, the following page shows the questions for the rating.
if (value('CH01') == 2) {
multiLevelReturn(2);
}
On an additional page, ''multiLevelReturn()'' returns the code 1 to the parent questionnaire if the item was evaluated:
multiLevelReturn(1);
After the page with the ''multiLevelDown()'', the higher-level questionnaire ("top") now contains another page with the [[:en:glossary#page_ids|page id]] "loopEnd". This is the identifier specified on the previous page in ''loopToPage()''.
Furthermore, ''randomUse()'' is now used on this page. The first ballot drawn (no. 1) should only be stored if the participant has answered the question. Otherwise it simply goes on with the next item.
$data = multiLevelResponse();
// Did the participant answer the question (code 1)?
if ($data == 1) {
$i = loopIndex(); // repetition 0, 1, ...
$num = $i + 1; // number of the ballot 1, 2, ...
randomUse('RG01', array($num));
}
The ''loopIndex()'' reveals which paper the respective repetition is about.
**Caution:** The function ''loopIndex()'' starts with 0, while the first ballot of a random generator has the number 1.
**Important:** In the list of ballots to be stored, the number of the ballot (1, 2, 3, ...) within the random generator is specified (not the code drawn). If 20 ballots are drawn in the interview, only numbers 1 to 20 can be given.
**Important:** This application example results in unrated items remaining in the pool of the random generator and being presented again to subsequent participants. If none of the participants wants to rate one or more items, only these items will be drawn after a while. It is therefore necessary to check the collected data regularly during the survey and to remove corresponding ballots from the random generator if necessary.
');
// Store ID in an internal variable (important)
put('IV01_01', $itemID);
// Selection question, if participant wants to rate the item
question('CH01');