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:

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.

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:

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:

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();