====== randomUse() ======

''void **randomUse**(string //Fragekennung//, [array //Zettel//])''

Der [[:de:create:questions:random|Zufallsgenerator]] kann u.a. für eine gleichverteilte Ziehung zum Zeitpunkt der Ziehung oder bei Interview-Abschluss sorgen. Die Funktion ''randomUse()'' erlaubt eine differenzierte Steuerung, welche Zettel wann als gültige Ziehung gewertet werden.

  * //Fragekennung// -- Die Kennung des Zufallsgenerators
  * //Zettel// -- (optional) Liste von Zetteln, die abzulegen ist (Nummern der Zettel, nicht gezogene Codes)

**Wichtig:** Die Funktion ''randomUse()'' funktioniert nur dann, wenn im Zufallsgenerator für die //Art der Ziehung// die "Gleichverteilung in abgeschlossenen Fragebögen (Ziehen ohne Zurücklegen)" eingestellt ist.


===== Funktion =====

Mit der Funktion ''randomUse()'' kann genau festgelegt werden, ...

  * zu welchem Zeitpunkt im Interview die gezogenen Zettel als //bisher gezogen// gewertet werden und
  * welche der gezogenen Zettel als //bisher gezogen// gewertet werden sollen, falls pro Interview mehrere Zettel gezogen werden.

Die Funktion kann erst aufgerufen werden, nachdem die Ziehung erfolgte, d.h., unter dem Zufallsgenerator oder auf einer späteren Seite im Fragebogen.

**Tipp:** Die Funktion ''randomUse()'' kann innerhalb eines Interviews mehrfach, auch mit unterschiedlichen //Zettel//-Listen aufgerufen werden. Es werden jeweils nur die Zettel als //gezogen// gezählt, die vorher noch nicht gezählt wurden.


===== Anwendungsbeispiel =====

Jedem Teilnehmer sollen aus einem Pool von 500 Items zufällig 20 Items zur Bewertung vorgelegt werden. Dafür kommt ein Zufallsgenerator ("RG01") zum Einsatz, der 500 Zettel enthält und pro Interview 20 Zettel zieht.

Um die Bewertungen jeweils in einer eigenen Datenzeile zu speichern, kommt eine [[:de:create:multilevel]] zum Einsatz: Es gibt einen Fragebogen für die Zufallsziehung und weitere Merkmale auf Teilnehmer-Ebene ("top") und einen weiteren für die Bewertung der Items ("sub").

Die Funktion ''randomUse()'' wird benötigt, weil Teilnehmer die Möglichkeit haben, einzelne Items zu überspringen. Dafür wird im untergeordneten Fragebogen ("sub") eine Auswahlfrage ("CH01") angezeigt, ob man das Item bewerten möchte oder nicht.

Der übergeordnete Fragebogen ("top") enthält zunächst den Zufallsgenerator. Anschließend werden 2 Seiten mittels ''[[:de:create:functions:looptopage]]'' 20-mal wiederholt. Dafür kommt folgender PHP-Code zum Einsatz.

<code php>
$codes = array_values(valueList('RG01'));
$i = loopToPage('loopEnd', count($codes));
multiLevelDown('sub', $codes[$i]);
// Festlegen, dass die Zettel nicht automatisch abgelegt werden
randomUse('RG01', array());
</code>

Hier wird ''randomUse()'' erstmals aufgerufen -- aber mit einer leeren Liste. Dadurch wird sichergestellt, dass die Zettel am Ende des Interviews nicht automatisch abgelegt werden, wenn ''randomUse()'' zwischenzeitlich nicht aufgerufen wurde, weil der Teilnehmer keine einzige Frage beantworten wollte.

Der Code des zu bewertenden Items wird als zweiter Parameter in der Funktion ''multiLevelDown()'' übergeben. So weiß der untergeordnete Fragebogen ("sub"), welches Item bewertet werden soll. Das kann z.B. eine eindeutige ID sein, zu der in der [[:de:create:databank]] weitere Informationen (z.B. ein Text oder der Dateiname eines Bildes) vorliegen.

Im  untergeordneten Fragebogen ("sub") wird das Item angezeigt und die Frage gestellt, ob es bewertet werden soll. Außerdem wird die ID des Items in eine interne Variable IV01_01 gespeichert, damit sie in der Auswertung zur Verfügung steht.

<code php>
// Item-ID vom übergeordneten Fragebogen entgegennehmen
$itemID = multiLevelData();
// Weiter Daten aus dem Datenbank für Inhalte abrufen und z.B. ein Bild anzeigen
$data = dbGet('i'.$itemID);
$image = $data[0];
html('<div><img src="'.$image.'" alt=""></div>');
// ID in eine interne Variable speichern (wichtig)
put('IV01_01', $itemID);
// Auswahlfrage, ob man das Item bewerten will
question('CH01');
</code>

Falls man das Item nicht bewerten will, sorgt ein PHP-Filter ganz oben auf der folgenden Seite dafür, dass man direkt zum übergeordneten Fragebogen zurückkehrt. Ansonsten werden auf der folgenden Seite die Fragen zur Bewertung angezeigt.

<code php>
if (value('CH01') == 2) {
  multiLevelReturn(2);
}
</code>

Auf einer zusätzlichen Seite wird mittels ''multiLevelReturn()'' der Code 1 an den übergeordneten Fragebogen zurückgegeben, wenn das Item bewertet wurde:

<code php>
multiLevelReturn(1);
</code>

Der übergeordnete Fragebogen ("top") enthält nach der Seite mit dem ''multiLevelDown()'' nun eine weitere Seite, welche die [[:de:glossary#seitenkennung|Seitenkennung]] "loopEnd" enthält. Das ist die Kennung die auf der vorigen Seite in ''loopToPage()'' angegeben wurde.

Außerdem kommt auf dieser Seite nun ''randomUse()'' zum Einsatz. Und zwar soll der erste gezogene Zettel (Nr. 1) nur dann abgelegt werden, wenn der Teilnehmer die Frage auch beantwortet hat. Ansonsten geht es einfach weiter mit dem nächsten Item.

<code php>
$data = multiLevelResponse();
// Hat der Teilnehmer die Frage beantwortet (Code 1)?
if ($data == 1) {
  $i = loopIndex();  // Wiederholung 0, 1, ...
  $num = $i + 1;     // Nummer des gezogenen Zettels 1, 2, ...
  randomUse('RG01', array($num));
}
</code>

Um welchen Zettel es in der jeweiligen Wiederholung geht, verrät ''loopIndex()''.

**Vorsicht:** Die Funktion ''loopIndex()'' beginnt bei der Zählung mit 0, während der erste Zettel eines Zufallsgenerators die Nummer 1 trägt.

**Wichtig:** In der Liste der abzulegenden Zettel wird die Nummer des Zettels (1, 2, 3, ...) innerhalb des Zufallsgenerators angegeben (nicht der gezogene Code). Wenn im Interview 20 Zettel gezogen werden, können nur die Nummern 1 bis 20 angegeben werden.

**Wichtig:** Dieses Anwendungsbeispiel hat zur Folge, dass nicht bewertete Items in der Lostrommel des Zufallsgenerators verbleiben und nachfolgenden Teilnehmern wieder vorgelegt werden. Wenn keiner der Teilnehmer ein oder mehrere Items bewerten möchte, dann werden nach einer Weile nur noch diese Items gezogen. Es ist daher notwendig, die erhobenen Daten während der Erhebung regelmäßig zu kontrollieren und entsprechende Zettel ggf. aus dem Zufallsgenerator zur entfernen.