forked from MultiplEYE-COST/wg1-experiment-implementation
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.html
executable file
·104 lines (104 loc) · 9.11 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
<h1>MeRID: Experiment Implementation</h1>
<p>This repository contains the code for the <a href="https://www.cl.uzh.ch/en/research-groups/digital-linguistics/research/MeRID.html">MeRID</a> eye-tracking-while-reading experiment for multiple languages.</p>
<blockquote>
<p>:bangbang::bangbang::bangbang::bangbang:
<strong>Important</strong>: Please make sure to have the most recent version of the enviornment and the dependencies installed.
If you have created the env before December 19, 2024, please make sure to update the environment. It is best to just
create a new clean env and install all the dependencies again. You do not have to reinstall anaconda or so.</p>
</blockquote>
<h2>Contents</h2>
<ul>
<li><a href="#installation">Installation</a></li>
<li><a href="#run-the-dummy-experiment">Run the experiment without an eye-tracker</a></li>
<li><a href="#the-result-files">The result files</a></li>
<li><a href="#run-the-experiment-with-an-eye-tracker">Run the experiment with an eye-tracker</a></li>
</ul>
<h2>Installation</h2>
<p>In order to run the MultiplEYE experiment you will need to complete the following steps</p>
<ol>
<li>Please read the official MultiplEYE Data Collection Guidelines linked on this page: <a href="https://multipleye.eu/contribute/">MultiplEYE contribute</a></li>
<li>Download the experiment code from this repository. Either clone via git or download the zip file (see <a href="#download-the-experiment-code-as-zip-file">download as zip</a>).Please make sure to remove "-main" from the downloaded folder name. The folder should be named <code>MeRID-eye-tracking</code>!</li>
<li>Following the MultiplEYE Data Collection Guidelines, prepare the stimulus files which includes the creation of the images</li>
<li>Copy the stimulus files to the correct location in the experiment data folder: <code>experiment_implementation/data/[your stimulus folder]</code></li>
<li>Copy the files (3 Excel files) for the participant questionnaire the to the correct location in the experiment
data folder. You will have to create a folder for your language and country. The folder should be named as follows:
<code>experiment_implementation/data/participant_questionnaire_[LANGUAGE_CODE]_[COUNTRY_CODE]_[LAB_NUMBER]/</code></li>
<li>Optional: if you have created a translation of the interface, you can copy it to this location:
<code>experiment_implementation/ui_data/interface_language/[your language]</code>. The name of the file should be <code>experiment_interface_[your language].json</code>.</li>
<li>Prepare the environment for the experiment following the guidelines in <a href="guidelines/html/CONDA_ENVIRONMENT.html">CONDA_ENVIRONMENT.html</a></li>
<li>Install the necessary packages for your eye-tracker. For EyeLink eye-trackers
<a href="guidelines/html/INSTALL_PYLINK.html">INSTALL_PYLINK.html</a>. For Tobii eye-trackers, please see <a href="#develop-and-run-experiments-for-tobii">develop for Tobii</a> further below.</li>
<li><a href="#run-the-dummy-experiment">Run the dummy experiment</a> to check if everything is working correctly</li>
<li><a href="#run-the-experiment-with-an-eye-tracker">Run the experiment with an eye-tracker</a></li>
</ol>
<h3>Download the experiment code as zip file</h3>
<p>If you do not have git installed, you can download the code as a zip file from this website.
Click on the green button <code>Code</code> and then click on <code>Download ZIP</code>. Unzip the folder in our preferred location.</p>
<blockquote>
<p>Note: The repository contains a folder with toy stimuli to test the experiment. Sometimes you cannot unzip these files because the path gets too long.
In this case, you can either move the folder to a different location closer to the root or unzip and ignore the files
in the toy stimuli folder (i.e. skip the error message that pops up during unzipping). To use the
toy stimuli, please contact <a href="mailto:multipleye@cl.uzh.ch">multipleye@cl.uzh.ch</a> and we can provide them and you can
copy them to the correct location.</p>
</blockquote>
<p><img src="guidelines/images/download-as-zip.png" alt="Download" /></p>
<h2>Run the dummy experiment</h2>
<p>The experiment can be run in dummy mode which means that can be run without an actual eye-tracker.
If you'd like to run it, make sure you have completed the above steps, and you have your conda environment activated.</p>
<p>Activate the environment:</p>
<pre><code class="language-bash">conda activate merid3.10
</code></pre>
<p>Then you can navigate to the root folder of your local clone of the repository (your path should now end with
<code>MeRID-eye-tracking</code>. Please find instructions on how to navigate in a terminal in the
<a href="guidelines/html/CONDA_ENVIRONMENT.html">CONDA_ENVIRONMENT.html</a> in section 4). Run the following command to run the dummy experiment:</p>
<pre><code class="language-bash">python experiment_implementation/start_merid_session.py
</code></pre>
<p>In the GUI that will pop up you can tick the box <code>Dummy version</code> to run the experiment in dummy mode.</p>
<h2>The result files</h2>
<p>The experiment will write log and data files to a newly created results folder for your language and country
in the data folder (<code>data/eye_tracking_data...</code>).
In there it will create a folder depending on the experiment type. For example, if you run the core session,
it will create a folder called <code>core_dataset</code>. Within those
folders it will simply create a new folder for each participant. The folder name is the participant ID
(three-digit number) and information on the language etc. If you run the
script for the core dataset, it will prevent you from running the experiment twice for the same participant.
Note that if you run a test session, it will not warn you if you enter the same participant ID more than once. It will
just write the files to the same folder.</p>
<p>The naming scheme of the log files in the <code>log_files</code> folder is a follows:
<code>[log_file_type]_[session_id]_[participant_id]_[date]_[timestamp].txt</code>.</p>
<p>All logfiles are csv files. Note that the timestamps are relative to the start of the experiment. The experiment starts
at timestamp 0. Those log files are mainly used for debugging purposes.</p>
<p>The naming scheme of the edf files storing the eye-tracking data is as follows:
<code>[participant_id][language_code][lab_number]s[session_id]</code>.
It is different from the naming scheme of the MultiplEYE project, where the country codes are used instead of the
session_id because there are only one session per participant in MultiplEYE project, but in MeRID, there are multiple
sessions per participant.</p>
<h2>Run the experiment with an eye-tracker</h2>
<p>In order to run the experiment with an actual eye-tracker you can tick the respective box in the GUI in the lab settings
section. The box <code>Dummy version</code> should be <strong>un-ticked</strong>.</p>
<p>Depending on what eye-tracker you intend to use you need to install the software that comes with the eye-tracker. For
EyeLink and tobii you can download the software online for free.</p>
<p>If you use a display PC and an external monitor, please start the experiment on the external monitor and
close the display PC. Otherwise the resolution can be weird for some monitors.</p>
<h3>Run and develop experiments for EyeLink</h3>
<p>The code has been tested with EyeLink eye-trackers and mostly on a Windows presentation PC. However, MacOS should work
as well, but it has not been tested as thoroughly.
You will need to install <code>pylink</code> a package provided by SR Research if you use EyeLink eye-trackers.
Note that using pip to install pylink installs a different package although the names are the same! You have to follow
these step-by-step instructions
of how to install <code>pylink</code> can be found here: <a href="guidelines/html/INSTALL_PYLINK.html">INSTALL_PYLINK.html</a></p>
<blockquote>
<p>Note on pylink experiments: The pixel coordinates written to the edf and consequently asc file will be -1 on both axes due to the EyeLink setting described here: <a href="https://www.sr-research.com/support/thread-9129-post-35624.html#pid35624">SR Research Forum Thread</a> and is implemented here: <a href="https://github.com/theDebbister/PyGaze/blob/b5771a98d910ce5b29151fc9303c4852d6a62034/pygaze/_eyetracker/libeyelink.py#L217-L219">PyGaze</a>. pymovements will take care of this during preprocessing.</p>
</blockquote>
<h3>Develop and run experiments for other eye-trackers</h3>
<p>Depending on what is needed we can add more eye-trackers. There is also a team that is trying to set up experiment
using a webcam. Please contact <a href="mailto:multipleye@cl.uzh.ch">multipleye@cl.uzh.ch</a> for more information.</p>
<h2>Upload the data</h2>
<p>After you have run a MultiplEYE session, no matter if pilot or real experiment, please make sure to:</p>
<ol>
<li>Always save the entire <code>data</code> folder in a safe location locally as you do for other data collections.</li>
<li>Upload the <code>data</code> to the MultiplEYE server. When you preregistered, you should have
received a folder where to upload the data.</li>
<li>Whenever you collect data from a new participant, please upload the entire <code>data</code> folder to the server,
replacing the old one.</li>
</ol>