void randomUse(string questionID, [array ballot])

The 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)“.

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.

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 Multi-Level Structure 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 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 Database for Contents.

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('<div><img src="'.$image.'" alt=""></div>');
// 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 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.