Web-experiment data storage

Help

On this page we have provided several resources to help you using the application.

This application provides safe storage for data collected from web-experiments. This guide will describe the process of using this application.

Definitions

Experiment server
We provide a server you can use to host your web-experiment
Webshare
To upload your experiment, we provide a so-called webshare you can mount on your PC

Step 1: Register your experiment

Make sure that your fellow researchers have logged in to this application at least once before registering your experiment, otherwise you won't be able to add them to your experiment.

On the 'My Experiments' page, click 'Create new experiment'. You will be asked for some information:

Title: The name of your experiment
Experiment folder: The name of the folder you want to hold your experiment on the server.
Researchers: everyone (including you) that should have access to the data and to the experiment web-share

If you do not intend to use our server to host your experiment, please contact us. This application will not accept data from experiments not hosted on an approved server.

Step 2: Approval

Once your experiment has been created, we need to create your webshare. This should take 1 to 2 working days, you will be notified when we have done so.

Step 3: Couple your experiment to this application

When your experiment has been created, you should be able to find the access key to your experiment on the details page.

If you are using an experiment provided by us, it should already contain the code necessary to upload the data. You only need to add the access key.

If not, you can find it in the block called '(Developer) Uploading data from JavaScript' below.

Step 4: Upload your experiment

You can now upload your experiment to the webshare. Details on how to mount the webshare can be found in the block below.

Make sure the HTML file is called index.html. Otherwise, the server cannot find which file should be displayed without explicitly adding it to the URL.

There might already be a file called index.html in your folder, as we place a placeholder page when creating new folders. It's safe to overwrite this file.

Step 5: Open your experiment

By default, all experiments are closed to new uploads. When you are ready to send your experiment to participants, you should open it by changing its status on the 'Edit experiment' page.

Step 6: Downloading your data

Once you've finished collecting data, you can download the data on the details page.

It's a good idea to close your experiment at this point, so no new data will be added.
Closing the experiment will not take your experiment offline. You should remove your experiment from the experiment server as well

Note: Some data might not be uploaded correctly, in which case the transforming said data to CSV will fail. When downloading all data, an export report will added to the zip file. This file will report for every datapoint if transforming it to CSV failed or succeeded.

Downloading the file as raw data should always work, allowing you to see the malformed data if needed.

To host your web-experiment, we provide a folder on our experiment server. To upload your experiment, you have to connect to the WebDav share for your experiment.

You can find the location of your share on the details page of your experiment. (Under 'location' in the sidebar, it should start with 'webdav')

On Windows

  1. Start file explorer
  2. Right-click Computer > Map Network Drive
  3. Select a drive letter (e.g. Y)
  4. Insert https://{the URL listed on your experiment page}
    (Do not forget to add the https://)
  5. Uncheck Reconnect at Logon
  6. Check Connect using different credentials
  7. Press Finish and insert Solis-ID credentials

You should now have access to your folder. Upload your experiment by copying the files to this folder. Make sure your experiment's main HTML file is called index.html!

On macOS

  1. Open "Finder" > "Connect to Server"
  2. Insert https://{the URL listed on your experiment page}
    (Do not forget to add the https://)
  3. Provide queried credentials (Solis-ID)

You should now have access to your folder. Upload your experiment by copying the files to this folder. Make sure your experiment's main HTML file is called index.html!

On Linux

KDE (Kubuntu, OpenSUSE)

  1. Open Dolphin (the file manager)
  2. Select the URI bar or press CTRL+L
  3. Insert webdavs://{the URL listed on your experiment page}
    (Do not forget to add the webdavs://)
  4. Provide queried credentials (Solis-ID)

You should now have access to your folder. Upload your experiment by copying the files to this folder. Make sure your experiment's main HTML file is called index.html!

GNOME (Ubuntu 18.04+, Fedora)

  1. Open Files
  2. Go to 'Other locations'
  3. Select the 'Connect to server' box
  4. Insert davs://{the URL listed on your experiment page}
    (Do not forget to add the davs://)
  5. Press connect and provide queried credentials (Solis-ID)

You should now have access to your folder. Upload your experiment by copying the files to this folder. Make sure your experiment's main HTML file is called index.html!

This page requires some changes to your JavaScript. Feel free to email us if you need assistance.

What are target groups?

Many experiments are designed to use multiple item lists, and assign participants randomly to those lists. There are currently two ways to achieve that with jsPsych:

  1. Simple randomization in your script
  2. Balanced randomization using the datastore server

Simple randomization requires little effort, and is already implemented in our templates. It relies on randomly generated numbers to evenly distribute participants between lists over time.

In some cases, you might want better control over the distribution of participants to lists. This is where target groups might be useful.

By adding target groups to your experiment, you can decide how many participants should be assigned per list, and the datastore server would take care to assign participants to lists in a balanced fashion. To do that, it keeps track of ongoing and completed runs of the experiment.

Each target group has a name that should correspond to the relevant list name, and a completion target, which indicates the number of completed runs that should be reached. When a target group has its completion target fulfilled, no new participants will be assigned to the corresponding list. You can also modify completion targets to dynamically control the number of participants while the experiment is running.

The next paragraphs outline how participant assignment works in somewhat finer detail. You can safely skip to Implementation and assume that participants are evenly distributed between groups, but it is provided here for reference. To simplify things we will describe the algorithm with just two lists—A and B—but it works for any number of groups.

Suppose that the server keeps track of the next group in turn using a variable called next_group, then:

  1. Whenever a new participant is about to start the experiment, assign them to next_group.
  2. If next_group is A, set it to B. Otherwise, set it to A.
  3. Whenever a participant completes the experiment, check which group has fewer completed sessions. Set next_group to that.
Steps 1 and 2 guarantee that an incoming stream of participants will be equally distributed between groups. But that is not enough, because some participants will not finish the experiment. So in step 3 we compensate for an uneven distribution in completed sessions. Whenever a group becomes full (because the target number of completed sesssions was reached) it is taken out of the rotation, and the server continues the process with the remaining open groups.

Implementation

If you would like to use target groups with one of our jsPsych templates, look for a section in main.js that starts with:
// Option 1: client side randomization:
and comment out the part below it. Then uncomment the section following:
// Option 2: server side balancing:
(Note: in older templates these sections are located in index.html instead.)

Make sure your experiment is set to Open for target groups to work.

The relevant code for interacting with the target groups feature is found in the uil.utils.session module.

How do I upload my web-experiment?

To upload your experiment, you need to upload your experiment to the web-share we have provided. See Access your experiment folder.

Why can't I change the name of my folder on the experiment server?

Any changes to the name requires the lab-staff to do some manual changes as well. Please contact us if you need to get the name changed.

I'm trying to upload data to the application, but nothing is being saved!

Make sure that the status of your experiment is set to 'Open'. The current status of your experiment is shown both on the main page as well as the details page.

You can change the status of your experiment on the edit page.

Why are my fellow researchers not listed when trying to add them to my experiment?

Make sure they have logged into the application at least once. Due to technical limitations, this application is not aware of anyone that has not logged in.

If you are a teacher in a course and want your students to use this application, it might be easier if all your students are already registered before the course starts. Please contact the lab staff, they will be able to do add your students to the application in bulk.

I just added a new researcher to my experiment, but they cannot access the experiment share.

Giving access to the experiment shares is a manual process. Please contact us to update the access configuration.

I closed my experiment in this application, but it's still available on the experiment server.

The data and experiment servers aren't linked directly for security reasons. Thus, we cannot take your experiment offline automatically when you close the experiment.

If you're using JSPsych, you can use our library to automatically redirect your participant to a generic 'closed' page. You can also manually query the status of your experiment if you're not using JSPsych.

If you are using one of our templates, chances are that this is already set up. Otherwise, please contact us for instructions on how to set this up.

Your question not listed here? Contact us!

This page requires some changes to your JavaScript. Feel free to email us if you need assistance.

JSPsych

If you are using one of our JSPsych boilerplates, we probably already have implemented this for you. Please see the documentation of your boilerplate for more information.

If you are building your own JSPsych experiment, you can use our library. This library is also used by our boilerplates, and is guaranteed to work with this application.

You can find out more about our JSPsych utilities library at GitHub

Generic implementation

To let your web-experiment upload data to this application, you will need to add a special function that uploads said data. Add the following function to your experiment's JavaScript. 

function saveData(data) {
  let access_key = "{YOUR ACCESS KEY HERE}"
  let xhr = new XMLHttpRequest();
  xhr.open('POST', 'https://experiment-datastore.lab.hum.uu.nl/api/' + access_key + '/upload/');
  xhr.setRequestHeader('Content-Type', 'text/plain'); // Don't change, server only accepts plain text
  xhr.send(data);
}

Remember to replace "{YOUR ACCESS KEY HERE}" with your key. This can be found on the details page of your experiment, under 'Access Key'

Finally, you need to call this function at the end of your experiment. This is done by calling `saveData` with the intended data: 

saveData(experiment_data);

It is recommended that your data is formatted as either a plain JavaScript object or a JSON string.