Documentation
LabSEE.com is the first world wide service for implementing interactive experiments online. It does not require installation any software on subject's computer, tablet or smartphone. Subjects can participate experiments using their web browsers without special settings. Experiment desingers do all their work online using contemporary web standards: HTML + CSS and JavaScript. Yes! That's all. Moreover, LabSEE.com users can share their experiments desings to the public library so anybody can use it according to their needs, even without any technical skills.
Basic ideas
Experiment structure
Every user can create multiple experiments. Each experiment has a strict structure, that is a sequence of treatments (independent making decisions schemes). Each treatment is a sequence of points (decision making screen and calculations).
Experiment
|
+ Welcome message (HTML, JavaScript)
|
+ Treatment (A)
| |
| + Point (1) Decision screen (HTML, JavaScript)
| + Point (1) Waiting screen (HTML, JavaScript)
| + Point (1) Calculations (JavaScript)
| |
| + Point (2) Decision screen (HTML, JavaScript)
| + Point (2) Waiting screen (HTML, JavaScript)
| + Point (2) Calculations (JavaScript)
| |
| ...
|
+ Treatment (B)
| |
| + Point (1) Decision screen (HTML, JavaScript)
| + Point (1) Waiting screen (HTML, JavaScript)
| + Point (1) Calculations (JavaScript)
| |
| + Point (2) Decision screen (HTML, JavaScript)
| + Point (2) Waiting screen (HTML, JavaScript)
| + Point (2) Calculations (JavaScript)
| |
| ...
|
...
|
+ Goodbye message (HTML, JavaScript)
Sessions
In order to run an experiment you need to craete a new session. You can have multiple sessions for one experiment. Each session has a unique link, which needs to be sent to subjects. Subjects using this link can log in and participate in the experiment.
In the session manager you can see subjects current state, what treatement they currently play an in what point they are making decisions. You can also monitor each subject connection status, so you can see if subject has a fast or slow connection, which of subjects disconnected or lost connection. You can even switch to a particular subject session (by clicking on its name) and play the experiment on behalf of such a subject.
Subjects
Once you created a session, sent a session link to subjects and subjects logged in to an experiment you can manage your session. In the session manager you have a list of all subjects and you can start and stop an experiment or chat with participants.
Each subject is a record of it's related variables. As an experiment designer you can assign your own variables to subjects. This is the list of reserved variables:
- ID - subject id
- IDSEC - subject security random string
- Name - subject login name
- Password - subject login password
- TreatmentID - current subject treatment
- PointID - current subject point
- PeriodType - current period type (trial or payment)
- PeriodNo - currnet period number
- PeriodTotal - current treatment periods number
- Profit - subject profit for current period
- ProfitTotal - subject profit for current treatment
- Payment - subject payment for current period
- PaymentTotal - subject payment for an experiment
- Reply - states if a subject replied for its last decision screen
- ActionName - subject decision name (TIMEOUT on time end for current decision screen)
- ActionTime - subject making decision time (in miliseconds)
- Group - subject current group name
- Role - subject current role name
- Alert - message to be sent to subject
- PointStartTime - timestamp for starting currnet point
General settings
When editing an experiment, on the left part of a screen you have the list of all treatments and their points. By clicikng on the selected name on this list you will open its editor on the right part of a screen. By double clicing on the list item name you will be able to change the name. By clicikng the experiment name on the left side list you will open general settings.
Synchronization
There are four types of playing experiment.
- All - all subjects are synchronized, it means that before going to the next point of a treatement all subjects must wait until the last one makes a decision
- Group - sbujects are synchronized in groups, it means that each group goes independently from other groups, and subjects in a group wait only for the last member of a group
- Subject - all subjects play independently, at their own pace
- Survey - all subjects play independently and participants can join an experiment at any time after starting an experiment
Fullscreen
By checking this option, subjects will be playing in fullscreen mode.
Chat with supervisor
This setting makes chat window visible for subjects during the whole experiment, so participants can chat wich supervisor.
Globals (variables)
By default all subject variables are cleared after each treament. Here you can put variable names (one name per line) which are not to be cleared.
Groups matching
Before starting an experiment subjects are matched into groups and roles according to a given settings. There are two ways of grouping and naming groups.
One way is to use groups names that you provide (one name per line). Given names will be assinged sequentially. For example there are three names (A, B, C) and 8 subjects. Participants will be assigned to the following names (groups): A, B, C, A, B, C, A, B. In this case there will be 3 subjects in the group A, 3 in the group B and 2 in the group C.
Other way of matching participants is setting the number of groups and optionally providing groups names prefix. For 8 participants, setting three groups and "G-" prefix is producing the following groups: 3 subjects in the group G-1, 3 subjects in the group G-2 and 2 subjects in the group G-3.
You can also assign subjects roles in their group (one role name per line). The roles are distributed sequentially in the same way as groups names. Setting three groups (A, B, C) and two roles (1st, 2nd) will produce the following sequence of 8 subjects:
| Subject | Group | Role |
|---|---|---|
| 1 | A | 1st |
| 2 | A | 2nd |
| 3 | A | 1st |
| 4 | B | 1st |
| 5 | B | 2nd |
| 6 | B | 1st |
| 7 | C | 1st |
| 8 | C | 2nd |
Login settings
Subjects must login before they can participate in an experiment. Each subject needs to have a unique name. The following options of logging users are available:
- Anonymous autologin - subject is logged in with randomly generated name
- Asking for name (not required) - subject is asked to enter its name, if they leave the name field empty then random name will be generated
- Asking for name (required) - subject is asked to enter its name and it can not be empty
- Asking for name (required) and password (not required) - subject is asked to enter its name and it can not be empty; at the same time subject can also set a password
- Having list of allowed names and related passwords - subject must provide name and/or related password that is present on your list (one name and a password - you can ommit a password - per line in the following CSV format: name,password)
The default login name and password labels in the login form can be changed to suit your own needs. You can also set some info on top of the login page.
Welcome and goodbye message
Welcome message is the message presented to participants after they login and before you start the experiment. We typically place here some info about an experiment and ask participants to wait for all to be ready.
Goodbye message is presented to participants after they end an experiment. Usually we place here subject profit info.
CSS
If you plan to use some default theme modifications you can put here your CSS classes definitions. The content of decision screens is placed in the container with id="screen-content". Please refer to this container all your CSS classes. Example:
#screen-content {
color: black;
font-size: 14px;
line-height: 1.5em;
font-weight: normal;
text-decoration: italics;
text-align: justify;
padding: 10% 20% 10% 20%;
}
#screen-content > p {
margin: 5px 0 5px 0;
}
Treatments
Periods, profits and payments
Each treatment can be repeated many times. You can set how many payment adn trial perdiods will be. The difference between trial and payment periods is that in trial periods the system calculates only profits (paymants remain unchanged) whereas in payment periods, both profits and payments, are calulated by the system.
There are four variables related to profits and payments:
- Profit - this is set by an experiment designer as a result of the current period (for each subject separately)
- ProfitTotal - this is autocalculated value as a sum of all periods profits in the current treatment
- Payment - this is autocalulated payment for the current period based on the current profit (payment = profit / exchange rate)
- PaymentTotal - this is autocalculated value as a sum of all periods payments (during the whole experiment)
When a new treatment starts, variables Profit, ProfitTotal and Payment are set to zero wheras PaymentTotal persists between treatments.
Start condition
If a treatment requires subjects count to be multiplication of some number, you can specify it. In such case an experiment will not start until subjects count satisfies all treatments requirements.
Chat settings
To enable subjects communication you need to set the chat on. There are two main gorup of chat communiction options: subjects can chat with all other subjects or their communication can be limited to groups (possible modes are: chat with selected person, broadcast all or both). Additionally you can set to clear communication history between treatments and/or periods.
Matching
Matching settings works the same way as matching in general settings. In this case the matching process is done before treatment starts. Additionally you can set to repeat matching after trial periods or after each period.
Treatment init code
Sometimes there is a need to do some non standard settings before treatment starts. You can code them as a treatment init code.
Top and bottom of a screen
If you plan to have some info that is supposed to be repeated at every screen of a treatment you can define it in a treatment top or bottom info settings (eg. current period number).
Decision and waiting screens
Processing conditions
Timer
Screens
Calculations
HTML screen elements
<p>Text - paragraph</p>
<u>underline text</u>
<i>italic text</i>
<b>bold text</b>
<ul>
<li>1st unorderd (bulleted) list item</li>
<li>2nd unorderd (bulleted) list item</li>
<li>3rd unorderd (bulleted) list item</li>
</ul>
<ol>
<li>1st orderd list item</li>
<li>2nd orderd list item</li>
<li>3rd orderd list item</li>
</ol>
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<thead>
<tr>
<th>1st column name</th>
<th>2nd column name</th>
<th>3rd column name</th>
</tr>
</thead>
<tbody>
<tr>
<td>1st column value</td>
<td>2nd column value</td>
<td>3rd column value</td>
</tr>
<tr>
<td>1st column value</td>
<td>2nd column value</td>
<td>3rd column value</td>
</tr>
</tbody>
</table>
<input type=”text” name=”” required checkif=”” error=””>
<input type=”radio” name=”” value=”” required checkif=”” error=””>
<input type=”radio” name=”” value=””>
<input type=”radio” name=”” value=””>
<input type=”checkbox” name=”” value=”” minimum=”” maximum=”” required checkif=”” error=””>
<input type=”checkbox” name=”” value=””>
<input type=”checkbox” name=”” value=””>
<select name=”” value=”” range minimum=”0” maximum=”100” step=”1” required checkif=”” error=””>
<input type=”numbers” name=”” minimum=”” maximum=”” decimals=”” required checkif=”” error=””>
<input type=”sliders” name=”” value=”” minimum=”0” maximum=”100” step=”1” required checkif=”” error=”” width=”250”>
<div slideshow shuffle size=”0” repeat=”1” action=”” steptime=”0” transition-effect=”fold” transition-time=”400”>
<img src=”” repeat=”1”>
<img src=”” repeat=”1”>
</div>
<button submit action="USER">OK</button>
Screen Variables
<var name="Profit"></var>
<b var="Group"></b>
<div showif="this.Group=='A'">This content will be only visible if subject 'Group' value is 'A'</div>
value-var="A"
minimum-var="3"
maximum-var="33"
step-var="3"
repeat-var="3"
JavaScript extensions
var Subject = History[ History.length - 1 ];
var counter = new Timer(
time_ms_total,
time_ms_step,
on_step_cb(instance, time_ms_left),
on_complete_cb(instance)
);
counter.start();
counter.stop();
counter.restart();
counter.timeleft(); /* returns an object: {seconds, minutes, hours} */
ScreenAction(dom_element_with_action_attribute /* eg.: $('<button action="USER">OK</button>') */ )
update="JSFunctionName" /* JSFunctionName(element, subject, pointNo, isWaiting) */
Coding JavaScript calculations
Code functions
ALL /* array of all subjects */
GROUPS /* array of all groups - group is an array of all group subjects */
SUBJECT /* subject on behalf of which code is executed */
SESSION /* global object that can be used to store data */
GROUPS.Each( function(group) {
/** your code for each group */
group.Sum('invest');
group.Avg('Profit');
group.Each( function(subj) {
/** your code for each subject */
subj.Get(name, default = null);
subj.Int(name, default = 0);
subj.Float(name, default = 0.0, decimals = null);
});
});
ALL.Each( function(subj) {
/** your code for each subject */
subj.Get(name, default = null);
subj.Int(name, default = 0);
subj.Float(name, default = 0.0, decimals = null);
});
Round(value, decimals = 0);
Random(min = 0, max = 1, decimals = 6);
Array.Size(); Size(array);
Array.Each(cb(element)); Each(cb(element), array);
Array.Shuffle(); Shuffle(array);
Array.SortNum(name); SortNum(name, array);
Array.SortText(name); SortText(name, array);
Array.SortTextCase(name); SortTextCase(name, array);
Array.Filter(name, value); Filter(name, value, array);
Array.GroupBy(name); GroupBy(name, array);
Array.Set(name, value); Set(name, value, array);
Array.SetRandom(min = 0, max = 1, decimals = 6, name = 'Random'); SetRandom(min = 0, max = 1, decimals = 6, name = 'Random', array);
Array.Sum(name); Sum(name, array);
Array.Avg(name); Avg(name, array);
/** treatment init special function - variables defined in treatment init code are also visible in that treatment's codes (points) */
function execute() {
/** your code to be executed once before periods starts */
}
/** point code only functions - variables defined in point code are only visible in that code */
RepeatPoint();
NextPoint();
NextPeriod();
NextTreatment();
PeriodTotal();
ChatUpdateContacts();