-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathREADME.html
executable file
·120 lines (120 loc) · 10.5 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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
<h1>MultiplEYE WG1: Experiment Implementation</h1>
<p>This repository contains the code for a MultiplEYE eye-tracking-while-reading experiment for multiple languages.
After you have read this README make sure to read the relevant files in the guidelines folder. There exists a MARKDOWN
and a HTML version of the guidelines. Both are exactly the same. You can read whatever format you prefer. Also for this README,
there exist two versions.</p>
<p>If you would like to contribute, please read the following guidelines: <a href="guidelines/html/CONTRIBUTING.html">CONTRIBUTING.html</a> and
contact <a href="mailto:multipleye@cl.uzh.ch">multipleye@cl.uzh.ch</a>.</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 22, 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>wg1-experiment-implementation</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><strong>Mandatory</strong> also for test run: 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>
<blockquote>
<p>If you encounter any problems, please consult this <a href="guidelines/html/HANDLING_ERRORS.html">document</a>. If you cannot find your error, contact <a href="mailto:multipleye.project@gmail.com">multipleye.project@gmail.com</a>.</p>
</blockquote>
<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.project@gmail.com">multipleye.project@gmail.com</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 multipleye3.9
</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>wg1-experiment-implementation</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_multipleye_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>
<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>Run and develop experiments for Tobii</h3>
<p>An early version of the experiment has been tested with tobii eye-trackers. However, the code is not yet fully developed
and tested as the experiment as been developed further since then. If you want to use a tobii eye-tracker, you definitively
need to follow the following steps. Once those are completed, it will still be necessary to adjust the code in order to
work with the tobii eye-trackers:</p>
<ol>
<li>Install Tobii Pro SDK: <a href="https://connect.tobii.com/s/sdk-downloads?language=en_US">link</a></li>
<li>Download the SDK</li>
<li>Unzip the folder and copy all files from either the '32' or '64' folder to the experiment_implementation folder</li>
<li>Then you can pip install the package: <code>pip install tobii_research</code></li>
</ol>
<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.project@gmail.com">multipleye.project@gmail.com</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 participant/session folder to the MultiplEYE server. When you preregistered, you should have
received a folder where to upload the data. Add the participant/session folder to the eye-tracking-sessions folder. Also add the
session documentation file to the documentation folder in your respective folder. <strong>Please consult Section 14 of the
guidelines for more information on how to upload the data.</strong></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>