Overview of basic concepts

Embedded data. Embedded data are variables and parameters defined (or calculated) in the Qualtrics Survey Flow. Embedded data serve several functions in SMARTRIQS: they define study parameters, store participant information, decisions and results of operations. Embedded data are highlighted in this documentation: sample embedded data. Whenever you see this format, it refers to embedded data.
 
Blocks. Blocks refer to survey blocks in Qualtrics, which you can edit in the survey editor and rearrange in the Survey Flow. SMARTRIQS uses survey blocks (and JavaScript within them) to establish communication between the respondents and the server. There are three blocks that are required in each interactive survey: MATCH, SEND, and GET. In addition to these three blocks, there are two optional blocks: COMPLETE and CHAT.
 
Study. Study refers to an experiment with specific study parameters (see below). When you modify any of these study parameters, you should also rename the study, and give it a new studyID. Otherwise, if you modify study parameters and try to run the modified study under the same studyID, you will receive an error message during matching.
 
Study parameters. These are the parameters that are the same for every participant in the experiment. In other words, these parameters are not determined on the individual level, but on the study level. Study parameters are the following: study name, group size, number of stages, conditions, roles, and some other technical parameters that define the time zone, maximum waiting times, etc.

Study name. studyID A unique string assigned to a study. ValuesMust contain only alphanumeric characters, dash, or underscore:
a-z, A-Z, 0-9, - , _

Group size. groupSize The number of participants per group. ValuesGroup size must be one of the following values: 2, 3, 4, 5, 6, 7, 8

Number of stages. numStages The number of stages of the study. ValuesNumber of stages must be a positive integer

Conditions. conditions The array of all possible conditions in a study (not the participant’s specific condition). ValuesMust contain only alphanumeric characters, dash, or underscore:
a-z, A-Z, 0-9, - , _

Conditions must be separated by comma, for example:
conditions = Condition_1,Condition_2,Condition_3

Roles. roles The array of all possible roles in a study (not the participant’s specific role). ValuesMust contain only alphanumeric characters, dash, or underscore:
a-z, A-Z, 0-9, - , _

Roles must be separated by comma, for example:
conditions = Role_A,Role_B,Role_C

 
Group. Refers to a group of  2-8 participants who are directly interacting with each other during the experiment. Groups in a study must have the same groupSize. In SMARTRIQS, group size is limited to 8 participants per group. Within each study, each group has a unique groupID, that reflects the chronological order in which groups were created: 1 = first group, 2 = second group, etc. groupID is assigned automatically in the MATCH block.
 
Stage. A stage refers to a part of the experiment during which 1) one participant makes a decision while others in the group are waiting, or 2) multiple participants are making decisions simultaneously. If participants are taking turns (decisions are sequential), each turn is treated as a separate stage. The total number of separates stages is the “number of stages” in an experiment: numStages 

 
Conditions (or treatments). Conditions are versions of an experiment with the same studyID, which means that the study parameters must be the same across conditions: conditions must have the same number of participants per group, the same roles, and the same number of stages. Conditions can differ in instructions, experimental stimuli, or parameters that are randomized at the individual level, so basically anything that does not affect group size, roles, and the number of stages. Conditions are optional: by default, there is only one “condition” in each SMARTRIQS survey.

 
Roles (or players). Roles refer to the participants’  roles within groups. Each participant must be assigned a unique role within the group, even if roles do not have any function in the experimental design (for example, when everyone within a group has the same task: public goods game, auction, competition, etc.). This is because unique roles within groups allow SMARTRIQS to identify participants and to submit or retrieve their data from the database. Recommended rolesIn experiments where roles do not have any function, the following formats are recommended (groups of 3):
roles = 1,2,3
roles = player_1,player_2,player_3

In experiments where participants' roles are important, use intuitive and short labels, for example:
roles = A,B,C
roles = dictator,recipient,third-party
roles = sender,receiver,observer

Note that these roles are not displayed to participants by default. You can decide whether to display these roles or not, or whether to re-label them in Qualtrics.