Wertezuweisung

Benutzerdefinierte Variablen gehören weder zu einer Frage noch zu einem Sample/Panel. Sie sind nur verfügbar innerhalb der Umfrage, in der sie angelegt wurden. Zum Anlegen benötigt man eine Wertezuweisung, die über “Inhalt hinzufügen” in die Umfrage eingefügt wird. Bei den Einstellungen auf der rechten Seite klickt man auf “Variable erstellen”. Es öffnet sich eine Box, wo man den Namen der Variable vergibt und den Datentyp festlegt.

Möchte man eine Variable mit einem berechneten Wert füllen, können die Grundrechenarten ganz einfach eingesetzt werden:

• Addition: +
• Subtraktion: –
• Multiplikation: *
• Division: /

Mithilfe von Klammern ( ) kann dabei der Vorrang einer Teilberechnung definiert werden.

Beispiel automatische Summe

Der Teilnehmer soll die Umsätze in den einzelnen Regionen erfassen. Die Gesamtsumme wird automatisch berechnet.

Die Abfrage erfolgt in einer Matrixfrage (mit dem Variablen-Namen “turnover”). Die Matrix hat 1 Spalte (Dateneingabe “Text”). Der Text hat den Datentyp “Ganze Zahl”. Für jede der 4 Regionen ist eine Zeile angelegt. Zusätzlich gibt es eine 5. Zeile für die Summe. Da die Summe unmittelbar berechnet werden soll, muss die Wertezuweisung die Ausführen-Option “jederzeit” gesetzt haben. Die Position der Wertezuweisung ist bei Ausführung “jederzeit” egal. Es empfiehlt sich, die Wertezuweisung am Anfang oder direkt nach der Seite mit der Matrixfrage zu platzieren.

** autosum (anytime execution)
turnover_5_1 = turnover_1_1 + turnover_2_1 + turnover_3_1 + turnover_4_1
** read only setting
setSurveyFieldsReadOnly(turnover_5_1)

Die Wertezuweisung hat keine Variable ausgewählt. Anstelle dessen wird in der ersten Zeile zunächst die Zielvariable turnover_5_1 genannt. Nach dem Gleichheitszeichen wird die zu berechnende Summe notiert. Da der Teilnehmer das Summenfeld nicht ausfüllen soll und darf, setzt man mit der Funktion setSurveyFieldsReadOnly() das Feld, auf das sich die Variable bezieht, in den “nur lesen” Modus. Wenn nicht klar ist, wie die Variablen genau heissen, schaut man am besten in den Codeplan eines Rohdaten-Export Files, das man auf der Analysieren-Seite erstellen lassen kann.

Neben den Grundrechenarten können weitere numerische Funktionen eingesetzt werden. Die folgenden Beispiele zeigen häufig genutzte weitere Funktionen:

• quadrieren (potenzieren)
• Wurzel ziehen
• runden auf Nachkommastellen
• Modulo (Rest nach Division)

** auxiliary variable
a = 5
** square and root
integer1 = a^2
real1 = sqrt(a)
** round to … decimal
real2 = round(real1,2)
** modulus (remainder after division by …)
integer2 = a%2

Die berechneten Variablenwerte (in einem Textblock ausgegeben) sehen wie folgt aus:

Darüber hinaus gibt es numerische Funktionen, die mehrere Variablen verarbeiten, wie z.B. die Zufallsauswahl oder statistische Berechnungen. Die nachfolgenden Beispiele zeigen:

• Randomisierung und Zufallszahl
• arithmetisches Mittel
• arithmetisches Mittel, das “keine Angabe” Antworten und Missings ausschliesst

** auxiliary variables
a1 = 2
a2 = 3
a3 = 5
a4 = null
min = 2
max = 5
** randomization and random number
integer3 = pickRandom([a1,a2,a3])
integer4 = randomInt(min,max)
** arithmetic mean
real3 = mean(a1,a2,a3)
** arithmetic mean recognizing N/A answers and missings
naFilter(x) = x!=0 and x!=null
real3 = mean(filter([a1,a2,a3,a4],naFilter))

Die Randomisierung sortiert zufällig eine vorgegebene Liste an Variablen. Mit der Funktion pickRandom() wird das erste Element der zufällig sortierten Liste ausgegeben. Die Zufallszahl, die mit der Funktion randomInt() erzeugt wird, ist dagegen eine zufällig ausgewählte ganze Zahl zwischen einem minimalen und einem maximalen Wert (Minimum eingeschlossen und Maximum ausgeschlossen). Die Funktion mean() steht beispielhaft für typische statistische Berechnungen. Sollte es Missings in den Antworten geben, müssen diese noch herausgefiltert werden. Das macht die benutzerdefinierte Funktion naFilter. Die berechneten Variablenwerte (in einem Textblock ausgegeben) sehen wie folgt aus:

Die Wertezuweisungen können nicht nur für numerische Variableninhalte genutzt werden sondern auch für Textinhalte. Die wichtigsten Text-Funktionen sind:

• Texte verketten
• Teilzeichenfolgen finden
• Texte vergleichen

** auxiliary variables
postalcode = "CH-8005"
town = "Zürich"
** concatenation
text1 = concat(postalcode," ",town)
** substring verification
text2 = postalcode[4:7]
integer1 = indexOf(postalcode,"8005")
integer2 = indexOf(postalcode,"5008")
** text comparison
boolean1 = equals(town,"Zürich")
boolean2 = equals(town,"Utrecht")

Die Variablenwerte aus den Beispielen (in einem Textblock ausgegeben) sehen wie folgt aus:

Beim Verketten von Texten werden die einzelnen Textteile/Textvariablen kommagetrennt in die Funktion concat() eingesetzt. Um eine Teilzeichenfolge von und bis zu einer bestimmten Position zu extrahieren, werden Start- und Endposition mit Doppelpunkt getrennt in eckigen Klammern hinter die Textvariable geschrieben. Sucht man eine bestimmte Teilzeichenfolge, verwendet man die Funktion indexOf() und notiert die Textvariable sowie die gesuchte Teilzeichenfolge innerhalb der Klammern. Achtung, das erste Zeichen hat hier die Position 0. Kommt die gesuchte Teilzeichenfolge nicht vor, ist das Ergebnis -1. Das letzte Beispiel zeigt je einen erfolgreichen und einen fehlgeschlagenen Textvergleich. Das Ergebnis ist entweder “true” oder “false” (in jeder Interview-Sprache werden die englischen Ausdrücke zurück gegeben).

Der Textvergleich, wie er oben im Beispiel aufgezeigt wurde, ist der einzige Weg, eine Filterbedingung anzulegen, die die exakte Übereinstimmung der Inhalte zweier Textvariablen prüft.

Bei Datumsangaben, die noch im laufenden Interview geprüft werden sollen, ob sie sich innerhalb einer bestimmten Zeitspanne befinden, vor oder nach einem fixen Datum liegen oder eine maximale Abweichung zum aktuellen Datum nicht überschreiten, können Wertezuweisungen genutzt werden. Dazu wandelt man die Datumsangabe in einen Datums-Zeitstempel um, was nichts anderes als eine fortlaufende Zahl ist, die an einem fest definierten Zeitpunkt in der Vergangenheit mit 0 gestartet ist und praktisch ins Unendliche fortschreitet. Jedes Datum hat einen unverwechselbaren Zeitstempel. Die Differenz zwischen den Zeitstempeln zweier aufeinander folgender Tage ist immer gleich gross.

Mit der Funktion date2number() wird der Zeitstempel des angegebenen Datums (um 0 Uhr UTC) millisekundengenau ermittelt. Ein Tag hat 86 400 000 Millisekunden, sodass der Zeitstempel dividiert durch 86 400 000 die Anzahl Tage seit dem Startzeitpunkt in der Vergangenheit bedeutet. Möchte man ein angegebenes Datum mit dem aktuellen Tag des Interviews vergleichen, dann kann man mit der Funktion today() den Zeitstempel des Interview-Datums ermitteln und anschliessend die Differenz bilden. In der Wertezuweisung würde es so aussehen:

** date timestamp of participant answer stored in variable "date"
integer1 = date2number(date)/86400000
** date timestamp of today
integer2 = date2number(today())/86400000
** difference (number of days) between participant answer and today
integer3 = integer1 - integer2

Ein Beispiel für einen Berechnungsfilter mit numerischen Variablenwerten ist das Überprüfen einer konstanten Summe. Ausgangslage: Der Teilnehmer soll genau 100 Punkte oder 100% auf die aufgelisteten Optionen verteilen. Man fügt nun eine Validierung hinzu, die mithilfe eines Filters einen Validierungstext anzeigen soll, wenn die Summe nicht 100 ergibt. Der Filter vom Typ “Berechnung” nutzt die Basis-Funktionen der Grundrechenarten. Auf der linken Seite werden die Variablen der einzelnen Optionen aufsummiert. Auf der rechten Seite wird der Wert 100 eingetragen. Beide werden abgeglichen:

Ein Berechnungsfilter für Textvariablen, der überprüfen soll, ob zwei Variablen exakt denselben Inhalt haben, muss die Funktion equals() verwenden, die bei den Text-Funktionen aufgezeigt wurde. Die Eingabe auf der rechten Seite des Berechnungsfilters kann nicht unterscheiden, ob es sich um Text oder einen Variablennamen handelt. Es wird grundsätzlich von Text ausgegangen. Somit ist der Textvergleich über die genannte Funktion und mit den Werten “true” oder “false” aufzubauen:

Auch bei einem Vergleich zweier Daten benutzt man den Berechnungsfilter. Beide Datumsangaben werden – wie bei den Datums-Funktionen beschrieben – in numerische Zeitstempel umgewandelt, die dann einen Vergleich ermöglichen. Die zum Einsatz kommende Funktion date2number() kann sowohl links als auch rechts in der Filterbedingung notiert werden.

Um das Verhalten des Weiter-Buttons und des Zurück-Buttons zu steuern, gibt es die folgenden Funktionen:

• Weiter-Button erst nach einer bestimmten Anzahl Sekunden einblenden
• Weiter-Button nach einer bestimmten Anzahl Sekunden automatisch anklicken
• Weiter-Button ausblenden und nach einer bestimmten Anzahl Sekunden automatisch anklicken
• Zurück-Button ausblenden

** hide next button for 5 seconds
NextButton("hide",5)
** click next button automatically after 5 seconds
NextButton("click",5)
** hide next button and click automatically after 5 seconds
NextButton("hideandclick",5)
** hide back button
BackButton("hide")

Die Buttons erscheinen immer am Ende einer Seite. Eine Wertezuweisung erzeugt immer einen Seitenumbruch unmittelbar davor. Deshalb muss die Wertezuweisung mit den Button-Funktionen am Anfang der gewünschten Seite platziert werden. Gibt es noch weitere Wertezuweisungen an dieser Stelle in der Umfrage, sind diese vor der Wertezuweisung mit den Button-Funktionen zu platzieren. Als Ausführen-Option sollte die Standard-Option “jedes Mal” gewählt werden.

Es gibt Situationen, in denen die Daten in Variablen gespeichert sind, deren Datentypen ein weiteres Verarbeiten der Daten einschränkt und ein Konvertieren des Datentyps notwendig wird. Zumeist sind es Zahlen, die in einer Textvariable gespeichert sind. Oder andersrum hätte man gerne Zahlen (z.B. Jahreszahlen) fix formatiert ohne automatische Tausendertrennzeichen, sodass diese in einer Textvariable gespeichert sein sollten. Dies sind die wichtigsten Funktionen zum Konvertieren der Datentypen:

** conversion string to integer number
integer1 = parseNumber("12345")
** conversion string to real number
real1 = parseReal("12345.67")
** conversion real or integer number to string
text1 = convertToString(12345.670)

Ein Blick auf den Inhalt der neuen Variablen (in einem Textblock ausgegeben) zeigt die Zahlen, die zuvor als Text gespeichert waren, mit Zahlen-Layouts (Tausender- und Dezimaltrennzeichen sowie exakt 3 Nachkommastellen bei Bruchzahlen). Die vormalige Bruchzahl, die jetzt in einer Textvariable steht, hat kein Zahlen-Layout, und die letzte 0 (3. Nachkommastelle) wurde automatisch entfernt:

Wenn man eine Variable unterschiedlich füllen möchte in Abhängigkeit zum Inhalt einer anderen Variable, dann kann die Wenn-Dann-Sonst Funktion eingesetzt werden. Diese bedient sich einer besonderen Syntax, die exakt eingehalten werden muss:

Wenn-Bedingung ? Dann-Anweisung : Sonst-Anweisung

Der Doppelpunkt (Einleitung der Sonst-Anweisung) ist zwingend erforderlich. Es muss auch immer eine Anweisung folgen. die z.B. auch variableXY=variableXY lauten darf und keine Aktion auslöst. Kommt in der Wenn-Bedingung ein Ist-Gleich-Vergleich von Variablen und Werten vor, ist ein doppeltes Gleichheitszeichen zu verwenden. Das einfache Gleichheitszeichen ist immer eine Zuweisung, niemals ein Vergleich. Und wenn man mehrere Wenn-Dann-Sonst Funktionen ineinander verschachtelt, weil es mehr als nur 2 verschiedene Ausprägungen gibt, dann muss die oben genannte Syntax auf jeder Ebene der Verschachtelung exakt eingehalten werden. Es empfiehlt sich, der Übersicht halber mit Klammern zu arbeiten, die jedoch nicht verpflichtend sind.

** basic if-then-else clause example
integer1==2 ? integer2=5 : integer2=integer2
** nested if-then-else clause example
integer1==2 ? integer2=5 : (integer1==3 ? integer2=7 : integer2=11)

Die Listenfunktion ist eine Erleichterung beim Anlegen von Fragen, die immer die gleichen Antwortmöglichkeiten benutzen aber nur die in der ersten Frage als bekannt markierten anzeigen sollen. Mithilfe von Filtern, die für jede Antwortoption einzeln gesetzt werden müssen, kann man dies recht zeitaufwändig ganz ohne Wertezuweisungen umsetzen. Die hier gezeigte Funktion erspart dem Umfrage-Programmierer das Anlegen der vielen einzelnen Filter.

Die Ausgangslage für das Beispiel ist folgende: In einer ersten Frage mit dem Variablennamen “brand” wird eine lange Liste von z.B. Mineralwasser-Marken gezeigt. Der Teilnehmer soll in dieser Mehrfachauswahl-Frage alle bekannten Marken ankreuzen. In der Folgefrage (eine Einfachauswahl-Frage mit dem Variablennamen “bestbrand”) wird der Teilnehmer nach seiner Lieblingsmarke gefragt. Dabei sollen selbstverständlich nur die zuvor als bekannt gekennzeichneten Marken angezeigt werden. In der Wertezuweisung, die zwischen den beiden Fragen platziert wird, notiert man die visibility– und die setChoicesVisibility-Funktionen:

** function that returns true or false for each answer option of "brand" question
visibility(choice) = answer(concat('brand_',choice.code)) == 1 ? true : false
** setChoicesVisibility processes the visibility function for "bestbrand" question
setChoicesVisibility('bestbrand',visibility)

Um die Listenfunktion nutzen zu können, müssen einige Dinge beachtet werden:

• Die erste Frage muss eine Mehrfachauswahl-Frage sein. Jede Antwortmöglichkeit hat eine eigenständige Variable, die sich aus dem Variablennamen (“brand”), einem Unterstrich und dem Variablensuffix für die jeweilige Antwortmöglichkeit zusammensetzt. In der visibility-Funktion muss der Unterstrich hinter dem Variablennamen notiert werden, damit die concat() Funktion die korrekten Bezeichnungen ermittelt.
• Die Folgefragen müssen exakt dieselben Variablensuffixe (oder Werte bei Einfachauswahl-Fragen) für die Antwortmöglichkeiten verwenden, wie sie die erste Frage verwendet, da die Verknüpfung über diese Variablensuffixe stattfindet. Die Labels können durchaus unterschiedlich formuliert sein.
• Die Folgefragen können keine zusätzlichen Antwortmöglichkeiten ausserhalb der Liste enthalten. Einzig die “keine Angabe” Option ist zusätzlich möglich.
• Handelt es sich bei der Folgefrage um eine Matrix-Frage, dann wird die Listenfunktion auf die Zeilen angewendet. Die Variablensuffixe der Zeilen müssen dann mit den Variablensuffixen der Antwortmöglichkeiten aus der ersten Frage übereinstimmen.
• Die visibility-Funktion ist eine benutzerdefinierte Funktion. Sie kann somit auch einen anderen Namen haben. Man kann auch mehrere solche Funktionen mit unterschiedlichen Namen anlegen, sodass mehrere verschiedene Listen in einer Umfrage verwendet werden können.

Mit bestimmten Funktionen kann man in Wertezuweisungen die Antworten aller bisherigen Teilnehmer der Umfrage zählen und im Interview verfügbar machen. Zum einen gibt es Funktionen, die alle Interviews im jeweiligen Status zählen (Beispiel 1). Zum anderen gibt es eine Funktion, bei der man die Zählbedingung selbst festlegen kann (Beispiel 2).

Das Beispiel 1 zeigt die Funktionen für das Auszählen aller beendeten und aller angefangenen Interviews dieser Umfrage. Das Interview des Teilnehmers gehört im Moment des Zählens zu den angefangenen Interviews. Ist das Interview beendet worden, wechselt es zu den abgeschlossenen Interviews.

** get the total of all started or completed interviews
counter1 = survey.count_started
counter2 = survey.count_completed

Die Ausgangslage für das Beispiel 2 ist folgende Situation. Eine Veranstaltung wird mehrmals angeboten zu verschiedenen Zeitpunkten, sodass jeder Teilnehmer, der sich anmelden möchte, seinen Termin frei wählen kann. Jedoch sind die Kapazitäten beschränkt. Ist ein Termin vollständig ausgebucht, muss er bei der Auswahl ausgeblendet werden. Dazu benötigt man die Information, wie viele Anmeldungen es für jeden einzelnen Termin schon gibt. Die Terminauswahl erfolgt über eine Einfachauswahl-Frage mit dem Variablennamen “eventtime”. Gezählt werden nur die abgeschlossenen Interviews. So würde die Wertezuweisung aussehen:

** get the total of each answer (only completed interviews)
counter1 = countInterviews(eventtime==1 and survey.State=='Completed')
counter2 = countInterviews(eventtime==2 and survey.State=='Completed')
counter3 = countInterviews(eventtime==3 and survey.State=='Completed')
counter4 = countInterviews(eventtime==4 and survey.State=='Completed')

Die Funktion countInterviews() kann im Prinzip jede beliebige Filterbedingung enthalten. Werden mehrere Variablen eingesetzt, können sie mit “and” oder “or” verknüpft werden. Es gelten die gleichen Vorrang-Regeln wie bei den Element-Filtern auch. Wenn der Interview-Status Teil der Filterbedingung sein soll, müssen die Bezeichnungen gewählt werden, die auch im Rohdaten-Export bei “Status” stehen (kein Unterschied in unterschiedlichen Interview-Sprachen).

Wenn man eine benutzerdefinierte Variable anlegt, hat man als Datentyp “Matrix” und “JSON” zur Auswahl. Das sind zwei spezielle Datentypen für besondere Funktionen, die im Rahmen einer kostenpflichtigen Schulung im Detail erklärt werden können. Nachfolgend gibt es je ein Beispiel dafür, wie eine Matrix-Variable und wie eine JSON-Variable gefüllt werden:

** matrix with 2 rows and 3 columns
matrix1 = [[1,-3,2],[1,2,7]]
** json with typical tree structure
json1 = toJSON({"tree":[{"branch1":[{"name":"new","leaves":12}]},{"branch2":[{"name":"old","leaves":null}]}]})

Mit einer Matrix können die üblichen Berechnungen wie Addition und Multiplikation ausgeführt werden. Eine JSON-Variable kann als umfangreiche Liste eingesetzt werden (z.B. Postleitzahlen und dazugehörende Ortsnamen), auf die man aus der Umfrage heraus zugreifen kann.