Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- de:create:functions:put [27.05.2016 15:05] – Neues Beispiel: Array-Ränge speichern admin
+++ de:create:functions:put [15.12.2023 12:11] (aktuell) – admin
@@ Zeile 1: / Zeile 1: @@
 ====== put() ======
-''void **put**(string //Variable//, mixed //Wert//)''
+''void **put**(string //Variable//, mixed //Wert//, [boolean //JedeVariable//])''
 Mit der Funktion ''put()'' können Sie einen einzelnen Wert im Datensatz abspeichern. ''put()'' wird verwendet, wenn der Fragebogen einen Wert berechnet oder würfelt -- und man diesen Wert in der Auswertung benötigt. Wird beispielsweise der Stimulus einer Frage zufällig variiert, dann muss man für die Auswertung wissen, wozu der Befragte sich geäußert hat.
@@ Zeile 7: / Zeile 7: @@
   * //Variable//\\ Die Kennung der internen Variable (s. unten), in welcher der //Wert// gespeichert werden soll. Die Kennung wird als String in Anführungszeichen angegeben, z.B. '''IV01_01'''.
   * //Wert//\\ Eine Zahl oder ein Text (String), welche%%(r)%% in der Variable abgelegt werden soll. Für gewöhnlich wird als zweiter Parameter eine Variable mit dem entsprechenden Wert angegeben.
+  * //JedeVariable// (optional)\\ Normalerweise speichert ''put()'' ausschließlich in [[de:create:questions:internal|interne Variablen]]. In Ausnahmefällen kann es sinnvoll sein, den Wert einer anderen Variable zu überschreiben. In diesem Fall kann ein dritter Parameter ''true'' angegeben werden.
+**Warnung:** Verwenden Sie den dritten Parameter //JedeVariable// nur dann, wenn Sie genau wissen, was Sie tun und eine interne Variable nicht verwendet werden kann. Das Verändern von Antwortcodes kann die Validität des Datensatzes gefährden. Für die meisten Fälle sind die Funktionen ''[[:de:create:functions:preset]]'' und ''[[:de:create:functions:dropvalue]]'' deutlich besser geeignet.
+**Tipp:** Wenn Sie nicht nur einen einzelnen Wert, sondern ein ganzes Array im Datensatz abspeichern möchten, verwenden Sie ''[[putlist]]''.
@@ Zeile 16: / Zeile 21: @@
-===== Beispiel: Randomisierung I =====
-Falls Sie bei einer [[:de:create:randomization|Randomisierung]] mit dem Befehl ''[[:de:create:functions:random|random()]]'' arbeiten, müssen Sie die gewürftelte Zufallszahl im Datensatz abspeichern.
+===== Berechnungen =====
-Das folgende Beispiel geht davon aus, dass Sie eine interne Variable mit der Kennung "IV01_01" angelegt haben.
+Das folgenden Beispiel geht davon aus, dass ein Konstrukt in zwei Skalen mit den Frage-Kennungen AB01 und AB02 erhoben wird -- und dass eine interne Variable AB03_01 angelegt wurde, um den [[:de:general:indices|Skalenindex]] (Summenwert aller Items) zu speichern.
 <code php>
-// Eine ganze Zahl zwischen 1 und 2 würfeln
+$sum01 = valueSum('AB01');
-$zahl = random(1,2);
+$sum02 = valueSum('AB02');
-// Die gewürfelte Zahl im Datensatz abspeichern
+$index = $sum01 + $sum02;
-put('IV01_01', $zahl);
+put('AB03_01', $index);
-// Und davon abhängig Textbaustein "text1" oder "text2" anzeigen
+</code>
-if ($zahl == 1) {
-  text('text1');
+Die Ermittlung eines Skalenindex schon während der Befragung ist natürlich vor allem dann sinnvoll, wenn man dem Teilnehmer das Ergebnis mitteilen möchte oder wenn man es für einen Filter benötigt:
+<code php>
+if (value('AB03_01') > 100) {
+  question('FU03');  // Frage für Personen mit hoher Ausprägung beim Konstrukt
+} elseif (value('AB03_01') > 50) { {
+  question('FU02');  // Frage für Personen mit mittlerer Ausprägung beim Konstrukt
 } else {
-  text('text2');
+  question('FU01');  // Frage für Personen mit geringer Ausprägung beim Konstrukt
 }
 </code>
-===== Beispiel: Randomisierung II =====
+===== Antworten umkodieren =====
+Das Umkodieren von Werten erfolgt typischerweise in der Datenauswertung, wenn Sie im Interview (z.B. in einem [[:de:create:php-filters]]) bereits die umkodierten Werte benötigen, können Sie das aber auch direkt in SoSci Survey erledigen.
+Wenn Sie beispielsweise die offene Texteingabe für das Alter aus der Variable "SD02_01" in die Kategorien <25 (1), 25-40 (2) und 40+ (3) umkodieren möchten, würden Sie auf der Seite nach der Altersfrage folgenden PHP-Code verwenden.
+<code php>
+$alter = (int)value('SD02_01');
+if ($alter < 0) {
+  put('IV01_01', -1);  // Fehlercode für ungültige Altersangaben
+} elseif ($alter < 25) {
+  put('IV01_01', 1);
+} elseif ($alter <= 40) {
+  put('IV01_01', 2);
+} else {
+  put('IV01_01', 3);
+}
+</code>
+Das ''(int)'' wandelt die offene Eingabe in eine ganze Zahl um. Die interne Variable "IV01_01" im Beispiel muss voram im Fragenkatalog erstellt werden.
+===== Codes transformieren =====
+SoSci Survey speichert für Skalen jeweils positive Antwortcodes ([[:de:results:values]]). Sollten Sie im Datensatz für eine fünfstufige Skala den Wertebereich von -2 bis +2 benötigen, können Sie einzelne Variablen wie folgt umkodieren.
+**Hinweis:** In der Praxis ist das Umkodieren bzw. transformieren von Werten meist Teil der Auswertung und wird daher in der Statistik-Software vorgenommen. Es sind daher nur sehr spezielle Fälle, in denen eine solche Transformation schon bei der Erhebung sinnvoll ist.
+**Hinweis:** Um einzelne Items einer Skala zu "drehen" (das heißt z.B. für "trifft nicht zu" eine 5 statt einer 1 zu speichern, wie bei den anderen Items), wählen Sie das Item links im **Fragenkatalog** aus und aktivieren die Option //Antwortcodes für dieses Item invertieren//.
+Der folgende Code transformiert die Antworten für das Skalenitem SK01_01 vom Wertebereich 1 bis 5 in den Bereich -2 bis +2. Falls für das Skalenitem keine gültige Antwort gegeben wurde (Item ausgelassen oder eine Ausweichoption gewählt), wird im Datensatz kein Wert gespeichert. Der PHP-Code wird auf der Seite nach Frage SK01 platziert (vgl. Hinweise zu ''[[:de:create:functions:value]]'').
+Voraussetzung ist, dass vorab eine interne Variable SK02_01 angelegt wurde (s. [[#interne_variablen|oben]]).
+<code php>
+$original = value('SK01_01');
+// Nur gültige Werte (>0) speichern
+if ($original > 0) {
+  put('SK02_01', $original - 3);
+} else {
+  put('SK02_01', false);
+}
+</code>
+Der PHP-Code lässt sich auch kürzer (aber weniger übersichtlich) formulieren:
+<code php>
+$org = value('SK01_01');
+put('SK02_01', ($org > 0) ? $org - 3 : false);
+</code>
+Falls diese Transformation für alle Items der Skala SK01 vorgenommen werden sollen (und hinreichend interne Variablen in SK02 angelegt wurden), erledigt folgende [[:de:create:filter-itemcount#schleifen|Schleife]] diese Aufgabe. Der "innere" Teil des PHP-Codes ist fast identisch zum obigen PHP-Code. Die Funktion ''[[:de:create:functions:id|id()]]'' erstellt lediglich die Kennungen SK01_01 bis SK01_10 (bei z.B. 10 Items).
+<code php>
+$items = getItems('SK01');
+foreach ($items as $item) {
+  $original = value(id('SK01', $item));
+  if ($original > 0) {
+    put(id('SK02', $item), $original - 3);
+  } else {
+    put(id('SK02', $item), false);
+  }
+}
+</code>
+===== Komplexer Filter =====
+Das folgende Beispiel ist einem Fragebogen entnommen, der an mehreren Stellen unterschiedliche Fragen für Neukunden und Bestandskunden zeigt. Ein Neukunde zeichnet sich dadurch aus, dass er früher noch nichts gekauft hat (Antwort 1 bei Auswahlfrage "KD01") __und__ dass die aktuelle Bestellung noch nicht ausgeliefert wurde (Antwort 1 bis 3 bei Auswahlfrage "KD02").
+Natürlich könnte man den [[:de:create:filters|Filter]] auf jeder Seite mit unterschiedlichen Fragen wiederholen -- aber das ist einerseits unnötig kompliziert, andererseits wird die Trennung in Neu- und Bestandskunden bei der Auswertung ohnehin gebraucht. Daher soll sie in die interne Variable "KD03_01" gespeichert werden.
+<code php>
+if ((value('KD01') == 1) and (value('KD02') <= 3)) {
+  put('KD03_01', 1);  // Code 1 für Neukunden
+} else {
+  put('KD03_01', 2);  // Code 2 für Bestandskunden
+}
+</code>
+Den gespeicherten Code kann man auf späteren Seiten unproblematisch für Filter verwenden.
+<code php>
+if (value('KD03_01') == 1) {
+  question('SU02', '1-3,5');  // In Frage SU02 die Items 1, 2, 3 und 5 anzeigen
+} else {
+  question('SU02', '1,2,5-7');  // In Frage SU02 die Items 1, 2 und 5, 6, 7 anzeigen
+}
+</code>
+===== Randomisierung I =====
-Wenn Sie mittels ''shuffle()'' eine zufällig gemischte Liste erstellen, wird diese zunächst nicht gespeichert. Mittels ''put()'' lässt sie entweder die gemischte Liste -- oder die Rangfolge der Elemente speichern. Je nachdem, was für die Auswertung benötigt wird.
+Wenn Sie mittels ''shuffle()'' eine zufällig gemischte Liste erstellen, wird diese zunächst nicht gespeichert. Mittels ''put()'' lässt sich entweder die gemischte Liste -- oder die Rangfolge der Elemente speichern. Je nachdem, was für die Auswertung benötigt wird.
 Folgender PHP-Code ordnet etwa die Wert von 1 bis 10 zufällig:
@@ Zeile 62: / Zeile 164: @@
 for ($i=0; $i<count($elements); $i++) {
   // Kennung der internen Variable aus Frage-Kennung plus Index erstellen
-  $id = 'IV01_'.sprintf('%02d', $i + 1);
+  $id = id('IV01', $i + 1);
   // Hier den Wert aus dem Array speichern
   put($id, $elements[$i]);
@@ Zeile 68: / Zeile 170: @@
 </code>
-Der Befehl ''sprintf()'' mit dem ersten Parameter '''%02d''' sorgt einfach dafür, dass aus der Zahl eine zweistellige Zahl mit führender Null erstellt wird, also z.B. '''03''' aus ''3''. Der Punkt (''.'') verknüpft die Kennung der Frage mit dieser zweistelligen Zahl, also z.B. '''IV01_03''. Zum Index ''$i'' wird noch eins addiert, weil die Indizes von Arrays bei 0 zu zählen beginnen, die internen Variablen aber bei 1.
+Zum Index ''$i'' wird in der Zeile mit ''[[:de:create:functions:id]]'' der Wert eins addiert, weil die Indizes von Arrays bei 0 zu zählen beginnen, die internen Variablen aber bei 1.
 Oftmals ist es sinnvoller, die Ränge der Elemente zu speichern. Etwa wenn ''shuffle()'' eingesetzt wird, um Texte, Bilder oder Seiten im Fragebogen zufällig zu mischen. Die Ränge der Elemente speichern Sie mit folgendem PHP-Code.
@@ Zeile 75: / Zeile 177: @@
 for ($i=0; $i<count($elements); $i++) {
   // Kennung der internen Variable aus Frage-Kennung plus Inhalt des Elements (!) erstellen
-  $id = 'IV01_'.sprintf('%02d', $elements[$i]);
+  $id = id('IV01', $elements[$i]);
   // Hier den Rang speichern
   put($id, $i + 1);
@@ Zeile 92: / Zeile 194: @@
 for ($i=0; $i<count($indices); $i++) {
   // Rang speichern wie oben
-  $id = 'IV01_'.sprintf('%02d', $indices[$i] + 1);
+  $id = id('IV01', $indices[$i] + 1);
   put($id, $i + 1);
   // Seite in der Abfolge speichern
@@ Zeile 98: / Zeile 200: @@
 }
 // Neue Seitenabfolge setzen
-setPageOrder($random);
+// Nach der letzten Seite soll es auf Seite "demography" weitergehen
+setPageOrder($random, 'demography');
 </code>
+===== Randomisierung II =====
-===== Beispiel: Berechnungen =====
+Falls Sie bei einer [[:de:create:randomization|Randomisierung]] mit dem Befehl ''[[:de:create:functions:random|random()]]'' arbeiten, müssen Sie die gewürftelte Zufallszahl im Datensatz abspeichern.
-Das folgenden Beispiel geht davon aus, dass ein Konstrukt in zwei Skalen mit den Frage-Kennungen AB01 und AB02 erhoben wird -- und dass eine interne Variable AB03_01 angelegt wurde, um den [[:de:general:indices|Skalenindex]] (Summenwert aller Items) zu speichern.
+**Wichtig:** Wir raten davon ab, die Funktion ''[[:de:create:functions:random|random()]]'' im Rahmen von Experimenten zu verwenden. Ein [[:de:create:questions:random]] löst diese Aufgabe in aller Regel deutlich besser, s. auch das Kapitel [[:de:create:randomization]].
-<code php>
+Das folgende Beispiel geht davon aus, dass Sie eine interne Variable mit der Kennung "IV01_01" angelegt haben.
-$sum01 = valueSum('AB01');
-$sum02 = valueSum('AB02');
-$index = $sum01 + $sum02;
-put('AB03_01', $index);
-</code>
-Die Ermittlung eines Skalenindex schon während der Befragung ist natürlich vor allem dann sinnvoll, wenn man dem Teilnehmer das Ergebnis mitteilen möchte oder wenn man es für einen Filter benötigt:
 <code php>
-if (value('AB03_01') > 100) {
+// Eine ganze Zahl zwischen 1 und 2 würfeln
-  question('FU03');  // Frage für Personen mit hoher Ausprägung beim Konstrukt
+$zahl = random(1,2);
-} elseif (value('AB03_01') > 50) { {
+// Die gewürfelte Zahl im Datensatz abspeichern
-  question('FU02');  // Frage für Personen mit mittlerer Ausprägung beim Konstrukt
+put('IV01_01', $zahl);
+// Und davon abhängig Textbaustein "text1" oder "text2" anzeigen
+if ($zahl == 1) {
+  text('text1');
 } else {
-  question('FU01');  // Frage für Personen mit geringer Ausprägung beim Konstrukt
+  text('text2');
-}
-</code>
-===== Beispiel: Komplexer Filter =====
-Das folgende Beispiel ist einem Fragebogen entnommen, der an mehreren Stellen unterschiedliche Fragen für Neukunden und Bestandskunden zeigt. Ein Neukunde zeichnet sich dadurch aus, dass er früher noch nichts gekauft hat (Antwort 1 bei Auswahlfrage "KD01") __und__ dass die aktuelle Bestellung noch nicht ausgeliefert wurde (Antwort 1 bis 3 bei Auswahlfrage "KD02").
-Natürlich könnte man den [[:de:create:filters|Filter]] auf jeder Seite mit unterschiedlichen Fragen wiederholen -- aber das ist einerseits unnötig kompliziert, andererseits wird die Trennung in Neu- und Bestandskunden bei der Auswertung ohnehin gebraucht. Daher soll sie in die interne Variable "KD03_01" gespeichert werden.
-<code php>
-if ((value('KD01') == 1) and (value('KD02') <= 3)) {
-  put('KD03_01', 1);  // Code 1 für Neukunden
-} else {
-  put('KD03_01', 2);  // Code 2 für Bestandskunden
-}
-</code>
-Den gespeicherten Code kann man auf späteren Seiten unproblematisch für Filter verwenden.
-<code php>
-if (value('KD03_01') == 1) {
-  question('SU02', '1-3,5');  // In Frage SU02 die Items 1, 2, 3 und 5 anzeigen
-} else {
-  question('SU02', '1,2,5-7');  // In Frage SU02 die Items 1, 2 und 5, 6, 7 anzeigen
 }
 </code>