For an introduction, see the introduction to online surveys.
| The survey scripting language is completely different from the experiment scripting language. If you want to embed an experiment in an online survey, you need to follow these instructions. |
Structure of questionnaire
Questionnaires are simple text files. Each line has a meaning. The computer reads the questionnaire line by line. The first character of each line typically has a special meaning.
-
Each questionnaire consists of multiple questions, coded as a simple text (which you can edit in your browser)
-
The questionnaire needs to be manually entered, line for line (examples below)
-
Each question consists of a couple of lines
-
Questions are separated from one another by one (or more) empty line
-
Each question, irrespective of type, has a simple basic structure (read more about the Question Structure)
-
Each questionnaire can have sections that randomize the order (read more about randomized order)
-
Each questionnaire can have comments on lines starting with the hashmark sign (#)
General structure of a question
-
Each question consists of a number of text lines.
-
Questions are separated from one another with an empty line
-
Each line (typically) starts with a letter followed by a colon. The letter describes an important features, such as the name of the question, or the type of question.
-
Each question has one or more items, each one starting with a minus sign
| The first line of a question starts with l:. The letter l stands for "label". Every question has a label, or a "name". This is for two reasons: 1) The computer needs a way of identifying a question, and it uses the label. 2) The user will need a way of identifying answers to questions, and the label is the easiest way to do this. |
| A label can only have letters (upper or lower case) and numbers, and the underscore character. |
| Each question needs to start with l:, but you do not necessarily need to give a label. In that case, the software will call the question "auto__" followed by a number. This is handy if you are not willing to label your questions. You can still identify them by the whole question. And for "jumps", the label typically is not necessary for users at all. |
l: MyQuestion1 <-- this is the label
t: radio <-- this is the type of question
q: What is your favourite movie? <-- this is text of the question the participant sees
- Toy Story <-- answer 1
- Spirited Away <-- answer 2
- Babe <-- answer 3
- Ratatouille <-- answer 4
<-- the empty line separating this question from the next
| Each question can show an image at the top. You need to upload the image file (png, bmp, gif, jpg, etc). See images. |
| You can use the option line o: random to randomize the order of the items. |
Comments for programmers
When you program your survey, you might sometimes want to make a comment that is just for you, and that the computer should ignore. You can use the hashmark for that.
| Unlike PsyToolkit experiment scripts, the comment symbol "#" must be at the beginning of a line. In other words, you cannot have comments starting later in a line. |
Formatting text
You can format text using standard HTML tags. The most common are those for bold, italic, and text color. The general screen color cannot be changed.
-
Everything between <b> and </b> will be presented in bold font.
-
Everything between <i> and </i> will be presented in italic font.
-
Everything between <font color='red'> and </font> will be presented in red, etc.
l: MyQuestion t: radio q: What is your <i>favourite</i> movie? - <b>Toy Story</b> - <font color='blue'>Spirited</font> Away - Babe - Ratatouille
Question types
There are the following types of questions:
-
radio One choice out of many options
-
check Multiple choices out of many options (check boxes)
-
experiment Embed an experiment
-
scales Likert type scales
-
range Let user enter a number range between two values (with slider)
-
text line Participant can enter exactly one line of text
-
text box Participant can enter multiple lines of text
-
multiradio Multiple one-choice items in one question
There are the following types that just present info and a continue button
There are various control items:
Radio: select one out of many
Use this when you want that only one possible answer is selected. The name "radio" comes from classic radios, which had a set of buttons of which maximally one could be pushed down.
l: MyQuestion1 t: radio q: What is your favourite movie? - Toy Story - Spirited Away - Babe - Ratatouille
| The "q:" statement is the only statement that can run over multiple lines. This can sometimes be handy to have longer questions, like the one in the example below, which uses HTML formatting. |
l: MyQuestion1 t: radio q: In the following question, we would like to which movie you like best. Make sure you understand the following: <ul> <li>This is only about movies <li>You are allowed to say that you are not sure. </ul> - Toy Story - Spirited Away - Babe - Ratatouille - I am not sure
| Instead of text, you can show an image. You need to upload the images (as for topimage) and then use the {image=filename} option. In view files, you can see which filenames you already have. Don’t use files with spaces. You must enter the whole filename including extension, such as jpg, png, bmp, or gif. This allows you to even upload little animations using animated gifs. |
l: MyQuestion1
t: radio
q: In the following question, we would like to which movie you like
best. Make sure you understand the following:
<ul>
<li>This is only about movies
<li>You are allowed to say that you are not sure.
</ul>
- {image=toystory.jpg}
- {image=spirited.jpg}
- {image=babe.png}
- {image=ratatouille.bmp}
- I am not sure
| The default scores of a radio question with three answer options would be 1, 2, and 3. You can change these to other scores using the method below using the {score=?} option, where ? needs to be a number. |
l: weather
t: radio
q: What is the weather like?
- {score=3} Very bad
- {score=2} It could be better
- {score=1} Very Sunny
Sometimes, you may want to have people to enter their own option, you can do this as follows:
l: my_question
t: radio
q: Where do you live?
- New York
- Chicago
- St. Louis
- San Diego
- {other} Some where else (fill in)
This is what it will look like:
| You can also set the size of the other box with length (or size), see example below: |
l: my_question
t: radio
q: Where do you live?
- New York
- Chicago
- St. Louis
- San Diego
- {other,size=30} Some where else (fill in)
| Frequently asked question. How to add an option "other" using a separate question. Check here. |
| You can allow people to completely skip the radio question using the option free. That is, people are free to skip the question. You do this as follows: |
l: example t: radio o: free q: What food do you like? - Potatoes - Rice - Bread
Drop: select one out of many using a dropdown menu
The drop type is exactly the same as radio, except that the answers are in a clickable dropdown menu. This is useful for longer lists or if you want to save some screen space. Also, there is no "other" option as in radio.
l: days t: drop q: What day of the week would like to play chess? - Monday - Tuesday - Wednesday - Thursday - Friday - Saturday - Sunday
Check: select one or more out of many
l: MyQuestion2 t: check q: Which of the following did you eat today? - Rice - Meat - Tofu - Fish - Beans - Soup
| You can randomize the order of the items in a radio question by setting the o: random options (see second example). |
| You can require that participans select at least one, or at least two, or at least n of the options, see example below. Only when people select at least two items, the continue button will become clickable. |
l: MyQuestion2 t: check o: require 2 q: Which of the following food do you like? Select at least 2 items. - Rice - Meat - Tofu - Fish - Beans - Soup
You can even set the maximum of options a participant can select with adding a second number to the o: require statement. The second number specifies the maximum number of items that can be selected. For example, if you want that people select at least 2 but no more than 3 items, you can do that as follows:
l: MyQuestion2 t: check o: require 2 3 q: Which of the following food do you like? Select at least 2 items, but no more than 3 items. - Rice - Meat - Tofu - Fish - Beans - Soup
You can ask for one or more other options, and you can set the size of the text box with the option length (or size).
l: MyQuestion2
t: check
o: require 2 3
q: Which of the following food do you like? Select at least 2 items, but no more than 3 items.
- Rice
- Meat
- {other,length=30} Fill in something else
| Frequently asked question. How to add an option "other" with a separate question. Check here. |
Rank: Rank or order items
l: my_question t: rank q: Order of the following foods, starting with the one you like most. - Rice - Meat - Tofu - Fish - Beans - Soup
| You can randomize the starting order of the items in a ranking question by setting the o: random options (see second example). |
l: my_question t: rank o: random q: Order of the following foods, starting with the one you like most. - Rice - Meat - Tofu - Fish - Beans - Soup
| The option o: numbers show a numbered ranking list |
l: my_question t: rank o: numbers q: Order of the following foods, starting with the one you like most. - Rice - Meat - Tofu - Fish - Beans - Soup
Non-listed option for radio and check items
A common question is if it is possible to have an "other" option and a line where people can given an alternative. This is possible for radio questions on one screen, but you can also easily set it up as follows:
l: MyQuestion t: radio q: What is your favourite movie? - Toy Story - Spirited Away - Babe - Ratatouille - Another movie not listed here l: t: jump - if $MyQuestion != 5 then goto MyNextQuestion l: OtherFavouriteMovie t: textline q: Type the name of your favourite movie - My most favourite movie is l: MyNextQuestion t: radio q: Did you do sports yesterday? - Yes - No
In the above example, the line "if $MyQuestion != 5 then goto MyNextQuestion" can be explained as follows:
-
$MyQuestion (the $ indicates that it is a variable) refers to the line number of the option selected. Thus, if someone selects "Toy Story", they get value 1, and Another move not listed here gets value 5 (the fifth line).
-
The != means in computerlanguage is not equal. Thus if the selected line is not equal to value 5, then people do not need to enter anything in text. They are ready to go on. But if they selected the fifth line, they will go on the the next question where they can enter a value.
info: Show basic information, message, etc
Sometimes you just want people to read something or give feedback without and question. For that you can use the type info. Like other types, you can present a top image above it. It has (currently) no lines starting with "-". You can use HTML to format the text and you can insert variables like in other questions types.
l: some_message t: info q: Hello<br> Here is some information without questions to answer.
l: some_message
i: some_image.png
t: info
q: Thank you. Here is some feedback.<br>
Your score was: {$score}
You can use the option end to show the information without a continue button. This can be useful if you want to end the survey only under certain conditions, for example as an exclusion.
l: some_message t: info o: end q: Sorry, the survey ends here. Please <a href='http://www.google.com'>click this link to leave</a>, or close the window.
Play a sound
For each question type, you can add one (or more) sound file(s). Below are two examples:
l: q1 a: horse.mp3 t: info q: Play the sound. Which animal do you hear? - Horse - Pig - Cow
| MP3 files are much smaller than WAV files, so you better use MP3, although you can use any sound file type. |
| Sound files take up much "bandwidth". If possible, put sound files on an external website and refer to it using http: prefix, like in the example below. |
l: q1 a: http://www.my_webpage.com/sounds/horse.wav t: info q: Play the sound. Which animal do you hear? - Horse - Pig - Cow
| You can use the option o: no_sound_replay to ensure that a sound can only be listened to once (example below) |
l: q1 a: horse.mp3 o: no_sound_replay t: info q: Play the sound. Which animal do you hear? - Horse - Pig - Cow
| You can add the option line o: loop to your question which will play the same audio again and again. |
Play a video
| Note you can also play videos from YouTube, check here. |
For each question type, you can add one (or more) video(s). Below are two examples.
| You cannot upload video files to the PsyToolkit server. You need to put them on your own server or, for example, on your Google drive. |
In Example 1, we simply play a video that is somewhere on a server:
l: newquestion1 t: radio v: https://www.w3schools.com/html/mov_bbb.mp4 q: Do you like this video clip? - Yes - No
For videos, you can specify special options in your question. There are two options available:
-
You can set the width of the video with the vdei_width option. The width should be given in pixels.
-
Sometimes, people want that people play a video only one time and do not replay. This can be done with the option no_video_replay
In Example 1, we play the same video, but now we show two special options at work.
l: newquestion1 t: radio o: video_width 800 o: no_video_replay v: https://www.w3schools.com/html/mov_bbb.mp4 q: Do you like this video clip? - Yes - No
| It is possible to have multiple videos on one screen. Just have the different URLs on the v: line separated by a space. Although this can be done, it is difficult to see how that can be useful. |
| You can add the option line o: loop to your question which will play the same video again and again. |
You can yourself upload video files to your Google Drive. In order to play them, you need to use a few tricks:
-
Upload your video file to your Google Drive.
-
Share it as a link and copy the link (there is a "Copy link" button on your Google drive in the share dialog)
-
Copy the link to your v: line
| For more information on this, check the https:/lessons/surveyaudiovideo.html[lesson about audio and video in surveys]. |
Youtube: show a video
You can embed a YouTube video. On the "-" option line, you need to enter the video’s code, which you can get from the URL. It is the bit that follows the word watch. Thus in the following line https://www.youtube.com/watch?v=m9WxvT-82Xg, it is the m9WxvT-82Xg
l: MyQuestion3 t: youtube q: Please watch the following video - m9WxvT-82Xg
Experiment: Embed a reaction time experiment
You can use the name of one of your experiments. Make sure it works before you embed it. Note that you do not need the "q:" line.
l: MyQuestion4 t: experiment - myexperiment
| You can add the optional {fullscreen} to request the experiment to run in fullscreen. Of course, it is up to the end user to do this, and it might not run in all browsers (but it does in Firefox and Chrome). |
l: MyQuestion4
t: experiment
- {fullscreen} myexperiment
| When using PsyToolkit in teaching you can use the showdata option. This shows the participants the actual data output. If you teach students, then you can run your survey and they can get their own data directly and use it for some sort of analysis. |
l: MyQuestion5 t: experiment o: showdata - myexperiment
| Surveys and experiments can "talk" to one another. There is a whole lesson about that topic. https:/lessons/var_in_out.html[Click here for that lesson]. |
Jump to a question (conditionally or unconditionally)
With jump items, you can jump through the questionnaire. Is is typically only necessary if you want to have some questions conditionally. For example, if you have a question for women only, there is practical to first ask the participant about their gender, and then depending on the answer jump to questions.
| Jump items do not necessarily need to have a label (although they should start with *l:), because the jumps themselves are not interesting for your analysis. |
| Jump questions with just one if-then line can also be put in a j: line (see example below). |
You will need to have at least one line starting with a "-". In the "-" line, you can have an "if" built up in the following ways. You can have an if (conditional) or just a goto (unconditional jump):
-
if <value> <comparator> <value> then goto <label>
-
goto <label>
In the above, the value can be a $ character with a label or a number (see examples). The comparator can be one of the following:
| Comparator | Meaning |
|---|---|
== |
is equal? (just one "=" works too) |
!= |
is not equal? |
< |
is smaller than? |
> |
is larger than? |
<= |
is smaller than or equal to? |
>= |
is greater than or equal to? |
| In a jump question, you can have multiple if..then lines, and they are carried out one after another until the if condition applies. |
| It is necessary that you have spaces between items of the comparator part (thus write "if $q1 == 1", and not "if $q==1"). If you do not use spaces, it will not work. |
| The dollar sign in from of the label is important, it means that you are looking for the value of the answer to that question. After the goto statement, however, there is no dollarsign. |
| You can also compare the answers of two questions. This works only for radio questions. |
| You can also use and, or, and brackets to make complex if then rules, see examples below. |
l: sex t: radio q: What is your biological sex - Male - Female l: jump1 t: jump - if $sex == 1 then goto car l: birthcontrol t: radio q: Do you take birth control pills? - Yes - No l: car t: radio q: Do you have a car? - Yes - No l: birthcontrol t: radio q: What type of birthcontrol do you use? - pill - coil - condoms - do not wish to answer this question
| Sometimes you just want to jump from one location in the questionnaire to another. In the following example, the "blabla" question will never be carried out: |
l: somejump t: jump - goto myotherquestion l: blabla t: radio q: How are you? - Just normal - Fine l: myotherquestion t: radio q: What is the weather like? - Rain - Dry and overcast - Dry and sunny - Something different.
If all you want to do is an unconditional jump like in the example above, you can use the j: command with just the label you want to jump to:
j: myotherquestion l: blabla t: radio q: How are you? - Just normal - Fine l: myotherquestion t: radio q: What is the weather like? - Rain - Dry and overcast - Dry and sunny - Something different.
| Sometimes, you just want to end a survey. For this you can use the end instruction in an if statement. In the example below, the survey is not for men. If someone indicates to be a man, the survey ends. |
You can also use j: for jump questions with just one line, as you can also see in the example below.
l: sex t: radio q: What is your biological sex - Male - Female j: if $sex == 1 then end l: birthcontrol t: radio q: Do you take birth control pills? - Yes - No
Finally, in "check" questions, you can test whether a specific item of your list has been checked. Here is a common example:
l: food t: check q: What food did you just eat? - Bread - Rice - Noodles - No food, I only drank - Something else l: t: jump - if $food.4 == 0 or $food.5 == 0 then goto drinkquestion l: otherfood t: textline q: Please enter what food you ate - The name of the food l: drinkquestion t: radio q: What did you just drink? - Water - Fruit juice - Fizzy drink - Tea - Coffee - Alcoholic beverage
| The notation with the dot gets the value of a sub-item. The $food.4 can be 0 (not checked) or 1 (checked). Thus the checked sub-items always are 0 or 1. |
| This does, of course, not work for "radio" questions, in which can you should just check the value of $food (whether it is 4 or not). |
| For the unconditional, you also just do j: end to end the survey |
New since version 3.0.0 is the possibility to skip. Often, you want just have one extra question if people select a specific answer, in that case you can code it as follows:
l: food t: check q: What food did you just eat? - Bread - Rice - Noodles - No food, I only drank - Something else j: if $food.4 == 0 or $food.5 == 0 then skip next l: otherfood t: textline q: Please enter what food you ate - The name of the food l: drinkquestion t: radio q: What did you just drink? - Water - Fruit juice - Fizzy drink - Tea - Coffee - Alcoholic beverage
Note, you can also have different examples of how to use skip. If you just have "skip next", only one question will be skipped if the condition is true. You can also write, for example, skip 1, skip 2, whereby the number is the number of questions you want to skip.
Textline: Ask for a line of text
Sometimes, you want that a participant enter one line of text, such as their participant number, age, email address, or their name. You can use textline for this.
| Textline now has many different inline options. |
| inline option | meaning | example |
|---|---|---|
required |
forces people to fill in line |
- {required} Enter name |
min |
Enter a number of at least this value |
- {min=18} Enter your age (adults only) |
max |
Enter a number of at least this value |
- {min=18,max=65} Enter your age (working age please |
minchar |
minimal number of characters to be typed |
- {min=5} Enter at least 5 characters |
maxchar |
maximal number of characters to be typed |
- {max=10} Enter at most 10 characters |
size |
how big the textline appears on screen |
- {max=10} Enter at most 10 characters |
length |
does same as size |
- {length=5} This is a short text entry box |
l: MyQuestion6 t: textline q: Please enter your first name and surname - First name - Surname
l: MyQuestion6
t: textline
q: Please enter your first name and surname
- First name
- {require} Surname
You can force the shown line length to have certain number of characters with the {length=X} option, whereby X is a whole number:
l: MyQuestion6
t: textline
q: Please enter your first name and surname
- First name
- {length=10} Surname
You can force people to enter a number between two values. To do so, you must specify min and max, and then the survey will force user to enter a number.
l: MyQuestion6
t: textline
q: Please enter your first name and surname
- First name
- {length=10} Surname
- {min=10,max=100} Type your age (must be numerical)
You can force people to enter an email address (optional or not). The {email} tells the software to make sure people enter a valid email address.
l: MyQuestion6
t: textline
q: We need your email address.
- {email} Please enter a valid email address
| Sometimes, you just want to have the main question and no text for the line starting with "-". This can be done, see example below. |
l: MyQuestion6 t: textline q: Please enter your name -
l: test
t: textline
q: Enter text
- {minchar=5,maxchar=10,size=30} Enter text between 5 and 10 characters
- {minchar=10,maxchar=10,size=30} Enter text of exactly 10 characters
- {minchar=10,size=50} Enter text of at least 10 characters
- {maxchar=10} Enter text of maximally 10 characters
- Enter text of any sizeTIP: Aligning text input can sometimes be tricky, here is an example of how it can be done (using HTML tags). The plan is to make this easier in future versions.
l: myquestion t: textline q: Name - <pre style="display:inline">First Name :</pre> - <pre style="display:inline">Middle Name:</pre> - <pre style="display:inline">Last Name :</pre> - <pre style="display:inline">Test :</pre>
You can use the entered number later in the survey in conditional statements, such as this one:
l: age
t: textline
q: xxx
- {number} How old are you?
j: if $x.1 < 18 then end
Textbox: Ask for one or more lines of text
Sometimes, you want that a participant enters some more text, such as feedback on the survey.
l: MyQuestion6 t: textline q: Please enter your feedback and (optionally) your name and address - Feedback - Name and address
While textline has the option "length", the textbox has width and height, which can be set in different ways; see example:
l: MyQuestion6
t: textbox
q: Please enter your feedback
- Your first comment (note: no with or height provided)
- {w=100,h=5} Your second comment (here we have 100 characters width and 5 lines high
- {width=100,height=5} Options spelled out in full works too
As for textline, the "require" option can be used.
Range: Use a slider
Sometimes you want to enter a numerical value, such as age or the value on a (Likert) scale. With "range" you will get a slider, and you see the number in a yellow-hightlighted box on the right of the slider. Participants can use mouse or arrow keys to change the number.
| There are lots of options with the range type. Scroll down for a list of options. You can watch this short tutorial about all these options in the range type here. TO DO |
The range allows you for great setups, with an optional number indicator, with the option to request people to at least have the slider clicked once (to reduce likelihood they just use default value) and left and right labels.
In the example image below, you see this, including the slider turned green for sliders that already have been clicked and the continue button still being greyed out because not yet used.
l: drinks
t: range
q: Use the slider to indicate how much you like each drink
- {min=0,max=10,start=5,left=Not at all,right=Very much} How much do you like tea?
- {min=0,max=10,start=5,left=Not at all,right=Very much} How much do you like coffee?
- {min=0,max=10,start=5,left=Not at all,right=Very much} How much do you like orange juice?
- {min=0,max=10,start=5,left=Not at all,right=Very much} How much do you like milk?
| You can specify the minimum and maximum value with min and max as shown below. If not, the scale runs from 0 to 100. |
| Some researchers do not like sliders and want that people can just enter a number with the keyboard. That can be done: You can use the textline instead and request a number. See text line. |
l: age
t: range
q: What is your age?
- {min=18,max=100}
l: agefamily
t: range
q: How old are you parents if alive
- {min=18,max=120} Father
- {min=18,max=120} Mother
l: odd
t: range
q: Which number is your favorite?
- {min=1,max=100,by=2} Favorit odd number
- {min=2,max=100,by=2} Favorit even number
l: smallnumber
t: range
q: Choose a number between 0 and 1
- {min=0,max=1,by=0.1} Number between zero and one
| You can use the question option "free" (see example below). As with scale, that way people can skip the slider altogether. |
l: age
t: range
o: free
q: What is your age?
- {min=18,max=100}
There are a number of other options you can specify in the "elements" of the range question:
-
left and right specify text left and right of the slider
-
start specifies a start value
-
reverse takes the reverse score
Example of reverse: If you have a scale from 1 to 7, and it the reverse option for an item is set, then if a participants selects 6, the score will be 2. This can be handy for reverse score items, which is fairly common in psychological questionnaires to prevent a response bias (e.g., a participant might tend to always score the maximum value).
l: coffee
t: range
q: How much do you like coffee?
- {min=1,max=7,left=not at all,right=very much,start=4}
| It is possible to switch off the numerical value right of the slider. For this you can use the option no_number as in example below. Some users might find this useful. |
l: coffee
t: range
q: How much do you like coffee?
- {no_number,min=1,max=7}
All the in-item options of sliders:
| Option | What it does |
|---|---|
no_number: |
Do not show a numerical value next to slider |
name |
The name of the slider |
min |
The lowest possible value |
max |
The highest possible value |
by |
The smallest increase when slider is moved |
start |
Where the slider points to at start |
left |
Label shown on the left of slider |
right |
Label shown on the right of slider |
leftimage |
Image shown on left of slider (needs to be uploaded) |
rightimage |
Image shown on right of slider (needs to be uploaded) |
Scale: Likert style scales
A common type is the Likert type of scale. For this, you need to make sure you first define a scale, which you can then use in one or more questions.
Just have a look at an example, it explains the basics best:
scale: agree - Disagree - Neither agree nor disagree - Agree l: my_question q: How much do you agree with each of the following t: scale agree - I see myself as Extraverted, enthusiastic - I see myself as Critical, quarrelsome - I see myself as Dependable, self-disciplined - I see myself as Anxious, easily upset
Which will look like this for the participants:
| It is important to note that in order to use Likert scales, you need two different elements, namely the scale and the scale question type. The scale needs to be described only once and can, in principle, be used in many different questions. |
The scale description gives a name to the scale and then you can list each of the scale-points, such as "Disagree" to "Agree" in the above example. Each of those scale-points starts with the "-" character (followed by a space). Once defined, you can use this scale in as many questions as you want (see examples below).
Now that you know the basics, let’s go into some of the details:
-
You need to describe each scale you use only once. The idea is that if you want, you can reuse a scale over and over in as many questions as you want. A common mistake is that users think that the scale itself need to be described multiple times.
-
You can use many different scales and use them in different questions. An example is below (multiple scales).
-
If you wish, You can randomize the order of the items in a scale question by setting the o: random options (see example below).
| In the example below, you see that you only need to define a scale once, and that you can use that scale in different questions. Further, it is shown that you can define more than one scale. I find it often useful to have the scale descriptions at the top of my survey script, which I have here. |
scale: agree - Disagree strongly - Disagree moderately - Disagree a little - Neither agree nor disagree - Agree a little - Agree moderately - Agree strongly scale: like - Do not like - Like a bit - Like very much l: tipi q: I see myself as ... t: scale agree - I see myself as Extraverted, enthusiastic - I see myself as Critical, quarrelsome - I see myself as Dependable, self-disciplined - I see myself as Anxious, easily upset - I see myself as Open to new experiences, complex - I see myself as Reserved, quiet - I see myself as Sympathetic, warm - I see myself as Disorganized, careless - I see myself as Calm, emotionally stable - I see myself as Conventional, uncreative l: socmedia q: How much do you like the following social media? t: scale like - Facetube - Tweeter - Tinderbook - Flopflix l: people t: scale agree q: How much do you agree the following people? - Gwendolyn - Peter - Greg - Lisa
| In the example below, we set the score values. Although in the example, the score values are the default ones, you could set them to different values. Further, you can even overrule the scoring of individual scale question elements (see example). In that case, you must have the different scores separated by commas, and there must be exactly as many as in the scale (in this example 7). |
scale: agree
- {score=1} Disagree strongly
- {score=2} Disagree moderately
- {score=3} Disagree a little
- {score=4} Neither agree nor disagree
- {score=5} Agree a little
- {score=6} Agree moderately
- {score=7} Agree strongly
l: tipi
q: I see myself as ...
o: random
t: scale agree
- I see myself as Extraverted, enthusiastic
- I see myself as Critical, quarrelsome
- I see myself as Dependable, self-disciplined
- I see myself as Anxious, easily upset
- I see myself as Open to new experiences, complex
- I see myself as Reserved, quiet
- I see myself as Sympathetic, warm
- I see myself as Disorganized, careless
- I see myself as Calm, emotionally stable
- {reverse} I see myself as Conventional, uncreative
The scale question is shown as a "table" on the screen (i.e., there are rows and there are columns). There are different ways to control the way the table is being formatted:
-
Use linebreaks in the scale items (using the html <br>).
-
Use the option width. The parameter is the percentage of the scale table used for the item and the rest of the scale options will use the same width for each scale answer.
The example below has the line o: width 50%, which means that 50% is for the items text and the remaining for the 7 options. Each option will get the same 50/7=7.1% of the table.
scale: agree
- {score=1} Disagree strongly
- {score=2} Disagree moderately
- {score=3} Disagree a little
- {score=4} Neither agree nor disagree
- {score=5} Agree a little
- {score=6} Agree moderately
- {score=7} Agree strongly
l: tipi
q: I see myself as ...
o: width 50%
t: scale agree
- I see myself as Extraverted, enthusiastic
- I see myself as Critical, quarrelsome
- I see myself as Dependable, self-disciplined
- I see myself as Anxious, easily upset
- I see myself as Open to new experiences, complex
- I see myself as Reserved, quiet
- I see myself as Sympathetic, warm
- I see myself as Disorganized, careless
- I see myself as Calm, emotionally stable
- {reverse} I see myself as Conventional, uncreative
| In specifying the 50%, you the % sign is optional, just for readability. You can just put o: width 50, though. |
scale: agree
- {score=1} Disagree
- {score=2} Neutral
- {score=3} Agree
l: extroversion
q: I see myself as ...
t: scale agree
- I see myself as talkative
- I see myself as outgoing
- {reverse} I see myself as shy and quiet
The example below does exactly the same, but writes out the opposite scores.
scale: agree
- {score=1} Disagree
- {score=2} Neutral
- {score=3} Agree
l: extroversion
q: I see myself as ...
t: scale agree
- I see myself as talkative
- I see myself as outgoing
- {score=3/2/1} I see myself as shy and quiet
Finally, the scale item is by default called "item". Since version 2.5.3, this can differ from language to language, but the default is item. If you want to change that for a scale, you can do so as follows:
scale: agree
item: Question
- {score=1} Disagree
- {score=2} Neutral
- {score=3} Agree
| Use the o: boxes option for a nice layout. Try and see what happens. This option is also listed in the easymode survey editor. |
Custom scores
For each scale question, you can use custom scores that deviate from the standard scoring. This is often done in questionnaires that require reverse scoring for some quesitons to prevent answering bias.
In PsyToolkit, there are two ways to do that.
-
You can just use the reverse option (or the shorter rev).
-
You can specify the scores. Below are two examples of this that have exactly the same outcome. The reverse option can be used in scale and in range questions.
Scale with labels on both sides
Sometimes, you want a Likert scale that is more like a range between two extremes. For this, you can put labels on both sides. You do this with the scale question type, but now you use the o: 2 option (2 refers to the two sides).
For this, you can use an "empty" scale as in the example below. That might be more appropriate.
Important is that the part that is on the left and on the right side is separated by the | character (this symbol is known as the vertical line or pipe).
scale: empty
-
-
-
-
-
-
l: mathematics
t: scale empty
o: 2
q: Please indicate what applies to you.
- I don’t like mathematics at all | I like mathematics a lot
- Mathematics is boring | Mathematics is interesting
Multiradio: Have multiple one-choice items in one questions
The multiradio item is not so common in questionnaires, but you see it sometimes. Using this type of questionniare item, you can ask participants to choice between multiple pairs (or triplets, etc). The example explains what it does:
l: forcedchoices t: multiradio 2 q: For each pair of situations, pick the one you like best. - Going to the movies - Going to a concert - Eating icecream - Eating sorbet - Listening to Bach - Listening to Bieber - Drinking wine - Drinking whiskey
A full example can be viewed in the Narcissistic Personality Inventory demo.
| The number in the multiradio command shows how many lines are taken together. In this case, we have two lines taken together. |
| You can use the option random |
By default, the scores for each element in a pair starts with 1. You can set the scores using the option "scores".
l: forcedchoices t: multiradio 2 o: scores 0 1 o: random q: For each pair of activities, pick the one you like best. - Going to the movies - Going to a concert - Eating icecream - Eating hotdog - Listening to Bach - Listening to Bieber - Drinking water - Drinking wine
Images
Each question can show one or more images above the question. You can upload the images via the "files browse" button, followed by "save" under the questionnaire code. Make sure these images are not too big for a website. A good size if 400 by 300 pixels (note that standard images from cameras are way to big — you would need software to make them smaller).
Alternative to uploading, you can use the weblink of an image.
l: rorschach i: inkblot.png q: What do you see? t: textbox - Describe what do you see in the drawing above
The participant will see the following:
You can also show multiple questions next to one another.
l: preference i: food1.jpg food2.jpg q: Which picture do you like better? t: radio - The food in the left picture - The food in the right picture
l: preference i: https://www.psytoolkit.org/surveys.png q: What does this image represent? t: radio - A survey - A type of cheese - None of the above
And finally, there you can add the options 'center'. This will center the image.
l: preference
i: {center} food1.jpg
q: Do you like this?
t: radio
- Yes
- No
Change the text of the button
You can not only change the language on the buttons, you can also change the text of the continue button for every question, if you wish. You do this with the b: operator, see the example below.
l: food t: radio b: Can you please press the button to go to the next question? q: What food did you just eat? - Bread - Rice - Potatoes
Randomize question order
Sometimes, people want to randomize the questions of a part of the survey. This can be done easily in PsyToolkit. You need to put the items in your survey that you want in a random order each time the survey is being run between between random: begin and random: end.
| You can have as many sections as you want between random: begin and random: end. |
| Within a randomized-order section, you can enforce certain questions to always follow other questions (read here). |
| Make sure you have a space following the word random:, otherwise it will not work. Also, before and after the random: statement must be empty lines. |
| In a section of your survey that is being randomized, you typically should not have jump items. This because jump items assume a specific order of questions. |
In the example survey below, the first and last question always are at the beginning and the end. In contrast, the questions food, drink and movie will come in a random order for each participant.
l: age
t: textline
q: How old are you?
- {min=18,max=100} Enter your age:
random: begin
l: food
t: radio
q: What food did you just eat?
- Bread
- Rice
- Potatoes
- Something else
l: drink
t: radio
q: What drink did you just have
- Tea
- Coffee
- Something else
l: movie
t: radio
q: What movie did you just watch
- Spiderman
- Citizen Kane
- The Orphan
- Something else
random: end
l: finalquestion
t: radio
q: Did you enjoy the questionniare
- yes
- no
You can use random: begin and random:end as often you like.
l: age
t: textline
q: How old are you?
- {min=18,max=100} Enter your age:
random: begin
l: food
t: radio
q: What food did you just eat?
- Bread
- Rice
- Potatoes
- Something else
l: drink
t: radio
q: What drink did you just have
- Tea
- Coffee
- Something else
random: end
l: internetquestion
t: radio
q: Are you ready to go on with some questions about the internet?
- Yes
- No
random: begin
l: visits
t: check
q: Which of the following websites have you recently visited?
- Google
- YouTube
- Twitter
- BBC News
l: computertype
t: check
q: Which of the following devices do you use to browse?
- Mobile phone
- Tablet
- Laptop
- Desktop
random: end
l: finalquestion
t: radio
q: Did you enjoy the questionniare
- yes
- no
You can enforce certain questions to follow up on preceding questions. This makes sometimes sense, for example when three questions follow up on one another logically. If you want this, add the o: link option to that question, and that way it will always follow the question just before. This way you can link as many questions as you want. In the example below, there is a series of questions that will be randomized for each participant, but still, the question labeled "visits" will always follow the question "internetquestion". They are "linked".
l: age
t: textline
q: How old are you?
- {min=18,max=100} Enter your age:
random: begin
l: food
t: radio
q: What food did you just eat?
- Bread
- Rice
- Potatoes
- Something else
l: drink
t: radio
q: What drink did you just have
- Tea
- Coffee
- Something else
l: internetquestion
t: radio
q: Are you ready to go on with some questions about the internet?
- Yes
- No
l: visits
t: check
o: link
q: Which of the following websites have you recently visited?
- Google
- YouTube
- Twitter
- BBC News
l: computertype
t: check
q: Which of the following devices do you use to browse?
- Mobile phone
- Tablet
- Laptop
- Desktop
random: end
l: finalquestion
t: radio
q: Did you enjoy the questionniare
- yes
- no
Scoring when running questionnaire using "set"
Sometimes, you might want to calculate a score. For example, if you are running a depression inventory, you might want to calculate a an score and save that to the datafile, or based on that score ask further questions. That is all possible. For this, there is a special questionnaire item named "set".
In summary:
-
set is a questionnaire item and must have a label
-
set can calculate take the answers and scores of other questions and add these, average these, etc.
-
set will set the label to the value and this can be used in conditional jumps, etc.
-
set can calculate the mean, sum, mean, max of several questions or subquestions
-
set can set random numbers or random letter/number strings
-
set can do conditional coding
-
set can set custom calculations (with your own formula)
-
set can count the number of items checked in a check question
-
set can also simply copy a variable (that is give it a different name)
l: food t: radio q: How much did you like the FOOD you had before? - disliked it very much - disliked it - neither liked nor disliked - liked it - liked it very much l: drink t: radio q: How much did you like the DRINK you had before? - disliked it very much - disliked it - neither liked nor disliked - liked it - liked it very much l: satisfactionscore t: set - sum $food $drink l: t: jump - if $satisfactionscore > 2 then goto endquestion l: why_dislike t: textbox q: We are sorry you did not like the food. If you wish, please leave a comment here - Please leave a comment about why you were not so happy with the dinner l: endquestion t: textline q: If you wish, please leave your contact number - Contact phone number
Sometimes, you want to sum all the questions starting with MyItems. In the following, there are three questions in MyScale and there is a simple way of referring to them using a placeholder character. In the example below, the set adds the answers of all the questions starting with MyItems. There are some extensive examples of this available in the survey library.
| You can only use the placeholder as the last character, like in the examples below. |
l: MyItems1 t: radio q: How do you feel today? - good - neutral - not so good l: MyItems2 t: radio q: How did you feel yesterday? - good - neutral - not so good l: MyItems3 t: radio q: How do you feel last week? - good - neutral - not so good l: myscore t: set - sum $MyItems* l: score1and2 t: set - sum $MyItems1 $MyItems2
You can also use a different type of function than "sum", namely "mean":
l: myscore t: set - mean $MyItems*
You can also use "calc" to use more complex calculations:
l: myscore t: set - calc ( $MyItems1 + $MyItems2 ) / 2.0
| If you have questions with scale items, you can get the score of a dot notation. Look for an advanced example of this in https:/survey-library/political-conservatism.html[this survey in the library]. |
| You can calculate the modulo of a number using the modulo operator, this can be useful for testing if, for example, a number is odd or even. See the example below. |
l: some_question
t: radio
q: Click one of the numbers below
- Number 1 (odd)
- Number 2 (even)
- Number 3 (odd)
l: check_it
t: set
- calc $some_question modulo 2
l:
t: jump
- if $check_it = 0 then goto report_even
- if $check_it != 0 then goto report_odd
j: endquestion
l: report_odd
t: info
q: You selected value {$some_question}. That is an odd number!
j: endquestion
l: report_even
t: info
q: You selected value {$some_question}. That is an even number!
l: endquestion
t: info
o: end
q: The end. You can now close the browser (tab).
There are a couple of rules that you need to stick to when using "calc":
-
All operators need to use spaces between them (like in the example above)
-
If you want to make sure that things are not rounded too much in a division like the one above, you need to make sure that you use numbers decimal point (2.0 instead of just 2).
You can count the number of items checked in a check question:
l: food
t: check
q: Please check the types of foods eaten today
- Rice
- Bread
- Tomatoes
l: count_foods
t: set
- count $food
l: feedback
t: info
q: The number of foods you ate: {$count_foods}
| You can also use set to create a random letter/number string. This can be useful to provide users with a "unique" code they can later use. You can get such a code at the end of the survey, but you can also do it earlier this way. The code will be entirely different from the end code. Like the end code, the string will be made of small and capital leters (excluding i,I,o,O) and numbers (excluding 0). The excluded letters numbers can look too similar and are therefore not used, improving readability. |
l: some_random_code
t: set
- random string
l: feedback
t: info
q: Your code is {$some_random_code}
l: some_random_code
t: set
- random string 20
l: feedback
t: info
q: Your 20-digit code is {$some_random_code}
l: age t: textline - Enter your age l: age_copy t: set q: $age
You can set values conditionally. This is only sometimes of value. But it makes it possible to do things that would otherwise be practically impossible. A good example survey using this technique https:/survey-library/mhc-sf.html[can be found here].
In short, using "if..then" rules, you can set the value to specific values. If the "if..then" rule cannot be satisfied, the value will be zero.
l: my_first_question t: radio q: How much do you like bread? - Not at all - A little bit - I like it - I like it very much - There is nothing I like more l: likes_bread_very_much t: set - if $my_first_question < 4 then 0 - if $my_first_question >= 4 then 1
Using this example, you can basically categorically score something, in this case, if a person has a score of 1 for "likes_bread_very_much" then he has a score of 4 or higher. This is somewhat of an advanced option.
Running different sections of questionniare for different participants
Some participants want to make sure that different people who click the same questionnaire/survey link actually do different questionnaires. This is sort of a random assignment of participants to a condition. This can be done. These are the steps to take:
-
Decide how many different versions you want? Two, or maybe even more?
-
Choose a random number
-
Jump to a section of the questionnaire depending on that random number.
Below are two examples, one for just a survey, and second a way to use this for counterbalancing groups of participants doing an experiment.
In the following example, the questionnaire sets a random item (chooserandom) to 1 or 2, and based on that, the questionnaire jumps to the appropriate part of the questionniare.
l: chooserandom t: set - random 1 2 l: t: jump - if $chooserandom == 1 then goto drink_set1 - if $chooserandom == 2 then goto food_set2 ## survey 1 about drinks ######################## l: drink_set t: radio q: Do you like cola? - Yes - No l: drink2 t: radio q: Do you like fanta? - Yes - No l: t: jump - goto endquestion ## survey 2 about food ######################## l: food_set t: radio q: Do you like bread? - Yes - No l: drink2 t: radio q: Do you like pancakes? - Yes - No l: endquestion q: Did you like this survey? - Yes - No
Counterbalancing
| Counterbalancing is an important feature of carrying out psychological experiments. In short, it means that different participants carry out different elements of an experiment in a different order. |
There are different ways you can counterbalance in PsyToolkit:
-
By using two (or more) blockorders in your experiment. The computer will randomly choose one of the blockorders to be used. This is the ideal and easiest way of counterbalancing in PsyToolkit. Check the experiment syntax here.
-
By choosing different experiments within the survey. An example of how this can be done is shown below.
For this example, we will have two different experiments, experiment_order1 and experiment_order2. We will randomly assign participants to one of these conditions.
l: choose_a_number t: set - random 1 2 l: t: jump - if $choose_a_number == 1 then goto Group1 - if $choose_a_number == 2 then goto Group2 l: Group1 t: experiment - experiment_order1 l: alwaysjump t: jump - goto GoOn l: Group2 t: experiment - experiment_order2 l: GoOn t: radio q: How did you like the experiment - I liked it - I did not like it
You can also use random differently, choosing numbers from a set of numbers:
l: choose_a_number t: set - random from 1 2 4 5
Timed questions — maxtime
Sometimes you want to give people only a limited amount of time for a question. You can do this with the "maxtime" option. Specify the the maxtime in milliseconds (e.g., 1000), seconds (e.g., 1s), or minutes (e.g., 5m).
You can optionally show the countdown time in the continue button
l: sports t: textbox o: maxtime 2m q: Write in short why you like sports, or why you do not. You have maximally 2 minutes. - Why I do or do not like sports:
You can hide the countdown
l: sports t: textbox o: maxtime 30s hide q: Write 3 reasons why you like tea. You have maximally 30 seconds. - Why I do or do not like sports:
You can show a counting up
l: sports t: textbox o: maxtime 30s up q: Write 3 reasons why you like tea. You have maximally 30 seconds. - Why I do or do not like sports:
You can 'lock' the question until time has passed (this way, participant has to wait for the time to have passed; this is a rarely needed feature).
l: sports t: textbox o: maxtime 30s lock q: Write 3 reasons why you like tea. You have maximally 30 seconds. - Why I do or do not like sports:
You can 'lock' and count up if that is what you want.
l: sports t: textbox o: maxtime 30s up lock q: Write 3 reasons why you like tea. You have maximally 30 seconds. - Why I do or do not like sports:
Timed questions — mintime
Sometimes you want that people spend at least some time on a question without them able to press the continue button. For this, we have the option mintime. It is almost identical to the maxtime.
You can optionally show the countdown time in the continue button
l: sports t: textbox o: mintime 2m q: Write in short why you like sports, or why you do not. You have to spend at least 2 minutes on it and you will only be able to continue after 2 minutes - Why I do or do not like sports:
You can hide the countdown
l: sports t: textbox o: mintime 30s hide q: Write 3 reasons why you like tea. You should spend at least 30 seconds on this question. - Why I do or do not like sports:
You can show a counting up
l: sports t: textbox o: mintime 30s up q: Write 3 reasons why you like tea. You should spend at least 30 seconds on this question. - Why I do or do not like sports:
Hiding / commenting questions out
Sometimes you want to test a survey without going through a certain question or experiment. You can comment it out, but it is quicker to hide it, just add the option o: hide as follows:
l: sports t: textbox o: hide o: mintime 30s up q: Write 3 reasons why you like tea. You should spend at least 30 seconds on this question. - Why I do or do not like sports:
Storing data anonymously and still getting people’s email or personal data
Here are some common situations:
-
You want to ask people’s emails so they can take part in a price draw, but at the same time, you want to keep the email separate fromthe other questions.
-
You want to ask only one question that can potentially identify a person, even though that is not your intention (e.g., asking for the size of their home)
You can solve this using the option o: sep (or click that option in the easy mode under general options).
For questions with the o: sep (sep stands for separate) option, each answer with identifying information will be stored in a completely separate file which can in no way be linked to the other data files.
The separate answers are stored in files starting with sep_ followed by the label followed by a random number which is different from other random numbers in the survey.
l: email
t: textline
o: sep
q: If you like, please enter your email below
- {email} Enter your email
In that case, in the person’s data file, the answer will always be "…".
sep_email_49c4c523-fc06-4ca9-bff3-410d8fbeb79f.txt
You can later use those datafiles. The data will not be put in a spreadsheet, you need to open the files starting with sep_ yourself and use the information as you like.
| All the files with starting with sep_ will have the same 2005 timestamp. This ensures that you cannot determine the corresponding data file based on the order of the file creation dates. |
Multiple question on one page
You can show put multiple questions of different types together if you want to.
You can put page: begin to start a multi-question page and page: end to end it (make sure there is a space between page: and the begin or end. Make sure that you have an empty line following the page instruction.
| You can also do this with easymode. Instead of adding a question, you can select begin or end a new set of multiple questions. |
In the survey script, you see that the questions between the lines page: begin and page: end will be shown together on one web page. In the easy mode, you see it clearly in the overview.
| In the survey options, you can choose how the different questions on one page are separated from one another (there are currently three different options): A horizontal line, separate boxes for each question, or a rounded box around each question. |
Important things to be aware of
-
You cannot put the types experiment, jump, and set in the multiple question section.
-
If you refer to the value of an earlier answered question, this will only work if that answer has already given before (in a different screen). Otherwise, the value 0 will be shown.
-
If you put too many questions on one screen, it might get a bit overwhelming for participants. Think carefully about the best way of presenting your questions.
-
mintime and maxtime options can be used, but you should set it for only one of the questions that are together. You can choose any of those, it can be the first, butthat is not necessary.
| It is important to realize that having one question per screen has many advantages. |
Advantages of one question per screen
-
You get the time it takes participants to make a decision for each question separately
-
People do not need to scroll down
-
You do not overwhelm participants with information
Advantages of multiple questions per screen
-
It might take less time to fill in a questionnaire if similar questions are together
-
Sometimes it is just easier to read for participants (e.g., a question about gender/age/race demographics)
page: begin
l: gender
t: radio
q: How would you best describe yourself
- Man
- Woman
- Other
l: age
t: textline
q: How old are you (enter a round number)
- {number} Enter your age in years
page: end
l: drink
t: radio
q: What do you like to drink?
- Water
- Tea
- Juice
| The question types set, jump, and experiment are not allowed within a multi-page part of your survey. If you do, you will get an error message when compiling. |
The reason that you cannot have set, jump, and experiment in a multi-page part is because that would make no sense. You can only set or jump meaningfully directly after a participant has answered. An experiment takes a lot of screen space and is not really suitable for the multi-page part.
| If you simply want all questions all on one page, you can, in principle, just have page: begin at the start of your survey script and you do then not need to have page: end at the bottom. |