Skip to content
This repository was archived by the owner on Nov 22, 2022. It is now read-only.

Commit 835cb43

Browse files
Revise second step of the code-based study building tutorial
1 parent 045acf9 commit 835cb43

File tree

1 file changed

+27
-90
lines changed

1 file changed

+27
-90
lines changed

docs/learn/code/study.rst

Lines changed: 27 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,6 @@
11
Building a working study
22
========================
33

4-
.. note::
5-
**This documentation page is currently under development. Sorry for that!**
6-
7-
We're actively working on this, so there might be parts that are missing or
8-
incomplete. Please be invited to start with the tutorial nonetheless,
9-
the additional parts are coming very soon.
10-
11-
If you find something awry or missing content, please don't hesitate to send
12-
us a line or two, we're happy to explain things further or to give you a
13-
personal tutorial via Skype/Hangouts/etc. or in person.
14-
15-
Sorry for the trouble!
16-
174
.. raw:: html
185

196
<style>
@@ -36,140 +23,90 @@ Building a working study
3623
:align: right
3724
:class: screenshot
3825

39-
**This is where we build our first working study!** Specifically, we're going to
40-
create an experiment that demonstrates the *Stroop effect*. This effect
41-
describes the interference between a written word's content and its visual
42-
characteristics: `John Ridley Stroop <https://en.wikipedia.org/wiki/John_Ridley_Stroop>`_
43-
demonstrated that naming the color of a word is harder (takes longer) when the
44-
word denotes a different color. An example for such an *incongruent* display
45-
might be the word :blue:`red`. Conversely, in the word and color can correspond
46-
(be *congruent*), which makes the task easier.
26+
**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 <https://en.wikipedia.org/wiki/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 :blue:`red`. Conversely, if the word and color correspond (are *congruent*), participants can perform the task faster.
27+
28+
.. contents:: Contents
29+
:local:
30+
:depth: 1
31+
32+
----
4733

4834
Picking back up
4935
---------------
5036

51-
This section builds on the previous one, in which you `downloaded the starter
52-
kit <https://github.com/FelixHenninger/lab.js/releases>`_ and took at first look
53-
how a minimal 'experiment' was constructed from individual components. You also
54-
made the code run by adding or uncommenting ``experiment.run()``. We'll build
55-
upon the same code, so please make sure you have the files and an editor handy.
37+
This section builds on the previous one, in which you `downloaded the starter kit <https://github.com/FelixHenninger/lab.js/releases>`_ and took at first look how a minimal 'experiment' was constructed from individual components. You also kicked off the study by adding or uncommenting ``study.run()``. We'll build upon the same code, so please make sure you have the files and a text editor handy.
5638

57-
If didn't go through the initial steps and don't feel confident looking at the
58-
starter kit code, please go back and take a quick look. You're always welcome to
59-
`reach out if you need help <https://github.com/FelixHenninger/lab.js#find-help>`_
60-
right now or in any of the following steps.
39+
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 <https://lab.js.org/resources/support/>`_ right now or in any of the following steps.
6140

6241
With that, let's get going!
6342

43+
----
44+
6445
Thinking about a study's structure
6546
----------------------------------
6647

67-
**When we build our studies, we'll think about them in a particular way: As a
68-
sequence of individual building blocks. What does that mean?**
48+
**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?**
6949

70-
Every *component* performs a particular function -- it might show some
71-
information onscreen, play a sound, or do some processing in the background.
72-
Each component *prepares*, often at the beginning of the experiment, readying
73-
for its task, and will *run* later, to perform its main function.
50+
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.
7451

7552
.. figure:: study/2-component-timeline.svg
7653
:alt: Individual component timeline
7754
:figwidth: 100%
7855
:width: 100%
7956
:align: center
8057

81-
As just noted, every component's moment in the spotlight is when it runs. This
82-
will very often mean showing some information, and then waiting for a response.
83-
A typical experiment will consist of many such components strung together like
84-
this:
58+
As we just discussed, every component's moment in the spotlight is when it runs. This will very often mean showing some information for a fixed amount of time, or waiting for the participants' response. A typical experiment will often consist of many such components strung together, for example like this:
8559

8660
.. figure:: study/3-multiple-components.svg
8761
:alt: Multiple components in sequence
8862
:figwidth: 100%
8963
:width: 100%
9064
:align: center
9165

92-
When we build experiments, components will not only be responsible for
93-
presenting stimuli and collecting responses. We will use different components to
94-
tie the structure of our experiment together. For example, the stimuli above are
95-
shown sequentially, and therefore together constitute a *sequence*.
96-
Accordingly, we'll use a *sequence component* to group them together.
66+
When we build experiments, components will not only be responsible for presenting stimuli and collecting responses: We will also 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.
9767

9868
.. figure:: study/4-sequence.svg
9969
:alt: Components nested in a sequence
10070
:figwidth: 100%
10171
:width: 100%
10272
:align: center
10373

104-
In many ways, a sequence component behaves exactly as a standard component
105-
would: It prepares by signaling all nested components to prepare themselves,
106-
and it runs by running them in sequence.
74+
In many ways, a sequence component behaves exactly as a standard component would: It prepares by signaling to all nested components to get ready themselves, and it runs by running them in sequence.
10775

108-
A sequence differs from a stimulus component in that it does not provide any new
109-
information to the viewers. Instead, it is in charge of *flow control*: It makes
110-
sure that other components run when they are supposed to. These *nested
111-
components* can then do the actual work of presenting information, or they might
112-
themselves organize the flow of yet another set of components.
76+
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.
11377

114-
We'll always combine both types, presentational components and flow control
115-
components, to build studies.
78+
We'll always combine both types, presentational components and flow control components, to build studies.
11679

11780
Building a Stroop screen
11881
------------------------
11982

120-
**Knowing what you now know, what might be a good component to start building
121-
a Stroop experiment?** We're going to start with the main stimulus display
122-
itself, the part that displays the word and color, and collects the response.
83+
**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.
12384

124-
First, let's think about how to design the stimulus. For the purposes of this
125-
tutorial, we'll use ``HTML`` to tell the browser what we'd like to show
126-
onscreen [#f1]_. We'd like to show a word, and give it a color. The syntax
127-
required to do this will probably look somewhat like the following:
85+
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 [#f1]_. 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:
12886

12987
.. code-block:: html
13088

13189
<div style="color: red">
13290
blue
13391
</div>
13492

135-
Given this content, let's build a component that will make it visible to the
136-
participants by inserting the ``HTML`` syntax into the page. This is the purpose
137-
of the :js:class:`html.Screen` component that you may have noticed in the
138-
starter kit code. By extending our earlier 'hello world' example, we might
139-
create the following snippet::
93+
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 of the :js:class:`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::
14094

14195
new lab.html.Screen({
14296
content: '<div style="color: red"> blue </div>',
14397
})
14498

145-
This creates a new :js:class:`html.Screen` with our content. When it runs, the
146-
short ``HTML`` code will be inserted into the page, specifically into the
147-
element whose ``data-labjs-section`` attribute is ``main`` (this default can be
148-
changed).
149-
150-
There are a few details to note here: First, the screen is constructed using
151-
options which are supplied in brackets -- and not only regular ones, but also
152-
curly braces. This is because the options are defined by a dictionary (you
153-
might also use the term object) which has pairs of keys and values, separated by
154-
a colon. Right now, only one option is provided: The content in form of our
155-
``HTML`` text. If we were to add further options, we would need to insert commas
156-
between them, a fact that is hinted at by the comma behind the option. Second,
157-
it's worth noting that the the quotation marks around and with the ``HTML`` code
158-
are different. This is because the simple quotation marks denote the beginning
159-
and the end of the string, whereas the double quotation marks are part of its
160-
content. Using single quotation marks within the ``HTML`` code would end the
161-
string prematurely and cause an error.
99+
This creates a new :js:class:`html.Screen` with our content. When it runs, the short ``HTML`` code will be inserted into the page, specifically into the element whose ``data-labjs-section`` attribute is ``main`` (this default can be changed).
100+
101+
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`` string, enclosed in quotation marks to indicate that the browser should treat it as literal text rather than as a command. 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 content option.
102+
Second, it's worth noting briefly that the the quotation marks around and within the ``HTML`` code 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 -- that's something to look out for.
162103

163104
If you've changed the code to correspond to the above example and reloaded the
164105
page in your browser, you should see the word blue on the screen, written in red.
165106
It's not (yet) as pretty as it could be, but it'll do for the moment: We'll get
166107
around to :ref:`styling our study <tutorial/style>` later!
167108

168109
.. [#f1] This is not the only way to design the display. If you're used to
169-
writing code that draws shapes and text at exact screen coordinates, don't
170-
worry: That is also possible using :ref:`canvas-based displays
171-
<reference/canvas>`.
110+
writing code that draws shapes and text at exact screen coordinates, don't worry: That is also possible using :ref:`canvas-based displays <reference/canvas>`.
172111
173-
Both approaches have their advantages and disadvantages: We'll discuss these
174-
at a later point. For now, we decided to give up some control over the precise
175-
display in return for a simpler method of stimulus construction.
112+
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.

0 commit comments

Comments
 (0)