Creating a new experiment type

Creating new experiment types is one of the most common tasks for an experimenter. Using a simple example (i.e. a story completion experiment), we'll explain how this task can be achieved easily.

1. After clicking on "Create experiment" (on the landing page) you'll see an overview page that lists all currently existing experiment types. To create a new experiment type, click on the grey "Create a new experiment type" tile.

   

2. You will be redirected to the experiment creation interface, as displayed below:

   

   Here are the basic steps you need to follow:

   1. The first thing you have to do is choosing a name for your new experiment type. This name must consist only of alphanumeric characters and must be unique amongst all experiment types. We choose "DEMOStoryCompletion" to be our experiment type name.
   2. The next step is to set the overall experimental condition. Sometimes you want participants to see only one specific list you have, or you want to let them do as many as they want. This condition-handling functionality can be managed by choosing one of the available options that are displayed below the name input field. Since we do have only one list for our fictitious experiment, we can use the default value, which requires the participants to complete all items in this list.
   3. The final step in experiment creation is specifying your experimental materials, i.e. the data you need to store in the database. In our case, we have a string that represents the story that should be completed. Additionally, we want to store another string that contains some type information. Although the value of this variable shouldn't be displayed to the participant later on, it will still be stored. After the new experiment is configured, we can press the "Submit" button to store it.

Managing your newly created experiment type

There's still more to do in designing your experiment. In this section, we describe what to expect once you've generated the new experiment type. In a nutshell, you've created an empty experiment template with no user interface. Here we describe where to go to make your custom UI.

1. Now you've successfully created your new experiment type. That means LingoTurk creates some things internally that should correspond to the information you entered before. At this point, LingoTurk adds your new experiment type to the overview page and you are able to instantiate your new experiment type, as it is described here: Instantiating an experiment
2. When you view the instantiated experiment you will see something similar to the image below:

   

   As you can see, the data you specified when instantiating the experiment is loaded and displayed in a "raw" way automatically when the experiment page is viewed. (On the picture you see a javascript object that contains the data of a single item. Remember the variables we picked when creating the experiment type? Here they are.) The next step is to specify which parts of the data should be displayed to the participants and what they have to do in order to complete the experiment. This needs to be done by changing the automatically generated code at lingoturk/app/views/ExperimentRendering/YourExperiment/YourExperiment_render.scala.html. (Note: We are aware that the need of looking these files up and changing them directly is not optimal. That's why we plan to implement an interface that supports you while doing so) This file does contain code that is responsible for loading your experimental materials, submitting them back to the LingoTurk server, and also for the content displayed to the participants. The relevant part thereby is marked with @ and @ comments:

   

3. The {{question}} in the HTML is replaced with the content of the question variable. As we want to display only the story-field to the participants, we can replace complete that statement to be {{question.story}}. When reloading the experiment you'll notice that the content of the panel has been updated to something more meaningful, as shown below:

   

4. Since our main goal is to design a story completion experiment, we have to provide an input field for the particpants and we have to make sure that their results are tracked somewhere.

   

   Thus we add a simple input-element to our code. While the class form-control is just used for a prettier appearance, the ng-model="question.answer" attribute is much more meaningful. It takes care of tracking the user's results by storing them in the answer field of the question variable. Values in the answer-field will be sent back automatically to the server later on, which is why you should always store them there, unless you have some more advanced needs that require manual configuration.
   Note: answer-field values can also be of array or object type.
   

   Putting all that together, we get the following experiment:

   

5. In case we want to extract specific variables from our participants' answers, for instance condition or item number, we edit the automatically created file resultsQuery.sql in lingoturk/app/models/Questions/YourExperiment/. In our case, we may be not only interested in our participants' answers but also in the correspondent values of story and type (cf. step 2). To do so we change the content of resultsQuery.sql from
   SELECT * FROM DEMOStoryCompletionResults
   to
   SELECT DEMOStoryCompletionResults.*,DEMOStoryCompletion_story, DEMOStoryCompletion_type FROM DEMOStoryCompletionResults JOIN Questions USING (QuestionId)
6. Congratulations. We successfully implemented our story completion experiment. For common use cases such as the one described here we could also use one of the existing templates instead of creating the design from scratch. For more information about that you should take a look here: Experiment templates