Building a working study¶
This documentation page is currently under development. Sorry for that!
We’re actively working on this, so there might be parts that are missing or incomplete. Please be invited to start with the tutorial nonetheless, the additional parts are coming very soon.
If you find something awry or missing content, please don’t hesitate to send us a line or two, we’re happy to explain things further or to give you a personal tutorial via Skype/Hangouts/etc. or in person.
Sorry for the trouble!
This is where we build our first working study! Specifically, we’re going to create an experiment that demonstrates the Stroop effect. This effect describes the interference between a written word’s content and its visual characteristics: John Ridley Stroop demonstrated that naming the color of a word is harder (takes longer) when the word denotes a different color. An example for such an incongruent display might be the word red. Conversely, in the word and color can correspond (be congruent), which makes the task easier.
Picking back up¶
This section builds on the previous one, in which you downloaded the starter
kit and took at first look
how a minimal ‘experiment’ was constructed from individual components. You also
made the code run by adding or uncommenting
experiment.run(). We’ll build
upon the same code, so please make sure you have the files and an editor handy.
If didn’t go through the initial steps and don’t feel confident looking at the starter kit code, please go back and take a quick look. You’re always welcome to reach out if you need help right now or in any of the following steps.
With that, let’s get going!
Thinking about a study’s structure¶
When we build our studies, we’ll think about them in a particular way: As a sequence of individual building blocks. What does that mean?
Every component performs a particular function – it might show some information onscreen, play a sound, or do some processing in the background. Each component prepares, often at the beginning of the experiment, readying for its task, and will run later, to perform its main function.
As just noted, every component’s moment in the spotlight is when it runs. This will very often mean showing some information, and then waiting for a response. A typical experiment will consist of many such components strung together like this:
When we build experiments, components will not only be responsible for presenting stimuli and collecting responses. We will use different components to tie the structure of our experiment together. For example, the stimuli above are shown sequentially, and therefore together constitute a sequence. Accordingly, we’ll use a sequence component to group them together.
In many ways, a sequence component behaves exactly as a standard component would: It prepares by signaling all nested components to prepare themselves, and it runs by running them in sequence.
A sequence differs from a stimulus component in that it does not provide any new information to the viewers. Instead, it is in charge of flow control: It makes sure that other components run when they are supposed to. These nested components can then do the actual work of presenting information, or they might themselves organize the flow of yet another set of components.
We’ll always combine both types, presentational components and flow control components, to build studies.
Building a Stroop screen¶
Knowing what you now know, what might be a good component to start building a Stroop experiment? We’re going to start with the main stimulus display itself, the part that displays the word and color, and collects the response.
First, let’s think about how to design the stimulus. For the purposes of this
tutorial, we’ll use
HTML to tell the browser what we’d like to show
onscreen . We’d like to show a word, and give it a color. The syntax
required to do this will probably look somewhat like the following:
<div style="color: red">
Given this content, let’s build a component that will make it visible to the
participants by inserting the
HTML syntax into the page. This is the purpose
html.Screen() component that you may have noticed in the
starter kit code. By extending our earlier ‘hello world’ example, we might
create the following snippet:
content: '<div style="color: red"> blue </div>',
This creates a new
html.Screen() with our content. When it runs, the
HTML code will be inserted into the page, specifically into the
data-labjs-section attribute is
main (this default can be
There are a few details to note here: First, the screen is constructed using
options which are supplied in brackets – and not only regular ones, but also
curly braces. This is because the options are defined by a dictionary (you
might also use the term object) which has pairs of keys and values, separated by
a colon. Right now, only one option is provided: The content in form of our
HTML text. If we were to add further options, we would need to insert commas
between them, a fact that is hinted at by the comma behind the option. Second,
it’s worth noting that the the quotation marks around and with the
are different. This is because the simple quotation marks denote the beginning
and the end of the string, whereas the double quotation marks are part of its
content. Using single quotation marks within the
HTML code would end the
string prematurely and cause an error.
If you’ve changed the code to correspond to the above example and reloaded the page in your browser, you should see the word blue on the screen, written in red. It’s not (yet) as pretty as it could be, but it’ll do for the moment: We’ll get around to styling our study later!
This is not the only way to design the display. If you’re used to writing code that draws shapes and text at exact screen coordinates, don’t worry: That is also possible using canvas-based displays.
Both approaches have their advantages and disadvantages: We’ll discuss these at a later point. For now, we decided to give up some control over the precise display in return for a simpler method of stimulus construction.