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.
Group size. groupSize The number of participants per group.
Number of stages. numStages The number of stages of the study.
Conditions. conditions The array of all possible conditions in a study (not the participant’s specific condition).
Roles. roles The array of all possible roles in a study (not the participant’s specific role).
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.