You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is a framework to analyse and visualize eye tracking data. It offers 2 designs of analysis:
26
26
***Experiment Design**: Analyse an entire experiment with 1 or more subjects/participants presented with 1 or more stimuli.
27
-
***Stand-alone Design**: Analyse a single stimulus for a single person.
27
+
***Stand-alone Design**: Analyse a single stimulus for a single person.
28
28
29
29
30
-
As of now, it supports data collected using SR Research EyeLink, SMI and Tobii eye trackers. The framework contains a *formatBridge* function that converts these files into a base format and then performs analysis on it.
30
+
As of now, it supports data collected using SR Research EyeLink, SMI and Tobii eye trackers. The framework contains a *formatBridge* function that converts these files into a base format and then performs analysis on it.
31
31
32
32
33
33
## Documentation
@@ -54,15 +54,15 @@ pip install PyTrack
54
54
55
55
## Running the tests
56
56
57
-
In order to test ***PyTrack***, some sample data files can be found [here](https://drive.google.com/open?id=1N9ZrTO6Bikx3aI7BKivSFAp3vrLxSCM6).
57
+
In order to test ***PyTrack***, some sample data files can be found [here](https://drive.google.com/open?id=1tWD69hurELVuVRFzizCbukWnr22RZrnp).
58
58
59
59
To get started, first you need to choose which design you want to run the framework in. If you wish to use the *Experiment Design*, see [this](#experiment-design). If you wish to use the *Stand-alone Design* see [this](#stand-alone-design).
60
60
61
-
### Experiment Design
61
+
### Experiment Design
62
62
63
63
#### Setup
64
64
65
-
Before running the framework, lets setup the folder so ***PyTrack*** can read and save all the generated figures in one central location and things are organised.
65
+
Before running the framework, lets setup the folder so ***PyTrack*** can read and save all the generated figures in one central location and things are organised.
66
66
67
67
Create a directory structure like the one shown below. It is essential for the listed directories to be present for the proper functioning of ***PyTrack***.
68
68
```
@@ -72,7 +72,7 @@ Create a directory structure like the one shown below. It is essential for the l
72
72
│ │ subject_001.[asc/txt/tsv/...]
73
73
│ │ subject_002.[asc/txt/tsv/...]
74
74
| |__ ......
75
-
│
75
+
│
76
76
└── Stimulus/
77
77
│ │ stim_1.[jpg/jpeg]
78
78
│ │ stim_2.[jpg/jpeg]
@@ -81,7 +81,7 @@ Create a directory structure like the one shown below. It is essential for the l
81
81
└── [Experiment-Name].json
82
82
83
83
```
84
-
*[Experiment-Name]* stands for the name of your experiment. Lets assume that your experiment name is "*NTU_Experiment*". The rest of the steps will use this alias as the *[Experiment-Name]* folder.
84
+
*[Experiment-Name]* stands for the name of your experiment. Lets assume that your experiment name is "*NTU_Experiment*". The rest of the steps will use this alias as the *[Experiment-Name]* folder.
85
85
86
86
Now, follow these steps:
87
87
@@ -93,14 +93,14 @@ Now, follow these steps:
93
93
94
94
eg. *stim_1.jpg* or *random_picture.png*
95
95
96
-
3. The last and final step to setup the experiment directory is to include the experiment description json file. This file should contain the essential details of your experiment. It contains specifications regarding your experiment suchas the stimuli you wish to analyse or the participants/subjects you wish to include. Mentioned below is the json file structure. The content below can be copied and pasted in a file called *NTU_Experiment*.json (basically the name of your experiment with a json extension).
97
-
96
+
3. The last and final step to setup the experiment directory is to include the experiment description json file. This file should contain the essential details of your experiment. It contains specifications regarding your experiment suchas the stimuli you wish to analyse or the participants/subjects you wish to include. Mentioned below is the json file structure. The content below can be copied and pasted in a file called *NTU_Experiment*.json (basically the name of your experiment with a json extension).
97
+
98
98
* "*Experiment_name*" should be the same name as the json file without the extension and "*Path*" should be the absolute path to your experiment directory without the final "/" at the end.
99
99
* The subjects should be added under the "*Subjects*" field. You may specify one or more groups of division for your subjects (recommended for aggregate between group statistical analysis). **There must be atleast 1 group**.
100
100
* The stimuli names should be added under the "*Stimuli*" field and again you may specify one or more types (recommended for aggregate between stimulus type statistical analysis). **There must be atleast 1 type**.
101
-
* The "*Control_Questions*" field is optional. In case you have some stimuli that should be used to standardise/normalise features extracted from all stimuli, sepcify the names here. **These stimuli must be present under the "*Stimuli*" field under one of the types**.
102
-
***The field marked "*Columns_of_interest*" should not be altered**.
103
-
* Under "*Analysis_Params*", just change the values of "Sampling_Freq", "Display_height" and "Display_width" to match the values of your experiment.
101
+
* The "*Control_Questions*" field is optional. In case you have some stimuli that should be used to standardise/normalise features extracted from all stimuli, sepcify the names here. **These stimuli must be present under the "*Stimuli*" field under one of the types**.
102
+
***The field marked "*Columns_of_interest*" should not be altered**.
103
+
* Under "*Analysis_Params*", just change the values of "Sampling_Freq", "Display_height" and "Display_width" to match the values of your experiment.
104
104
105
105
***Note***: If you wish to analyse only a subset of your stimuli or subjects, specify only the ones of interest in the json file. The analysis and visualization will be done only for the ones mentioned in the json file.
106
106
@@ -161,7 +161,7 @@ Now, follow these steps:
161
161
162
162
#### Using PyTrack
163
163
164
-
This involves less than 10 lines of python code. However, in case you want to do more detailed analysis, it may involve a few more lines.
164
+
This involves less than 10 lines of python code. However, in case you want to do more detailed analysis, it may involve a few more lines.
165
165
166
166
Using *formatBridge* majorly has 3 cases.:
167
167
@@ -176,7 +176,7 @@ Using *formatBridge* majorly has 3 cases.:
176
176
3.**Do not sepcify any stimulus order list**. In this case, the output of the statistical analysis will be inconclusive and the visualization of gaze will be on a black screen instead of the stimulus image. The *stim_list_mode* parameter in the *generateCompatibleFormat* function needs to be set as "NA". However, you can still extract the metadata and features extracted for each participant but the names will not make any sense. ***WE DO NOT RECOMMEND THIS***.
177
177
178
178
179
-
#### Example Use
179
+
#### Example Use
180
180
181
181
See [documentation](https://pytrack-ntu.readthedocs.io/en/latest/PyTrack.html) for a detailed understanding of each function.
182
182
@@ -187,10 +187,10 @@ from PyTrack.formatBridge import generateCompatibleFormat
187
187
188
188
# function to convert data to generate database in base format for experiment done using EyeLink on both eyes and the stimulus name specified in the message section
# Calling the function for the statistical analysis of the data
211
211
# file_creation=True. Hence, the output of the data used to run the tests and the output of the tests will be stored in in the 'Results' folder inside your experiment folder
@@ -239,7 +239,7 @@ The Experiment class contains a function called analyse() which is used to perfo
239
239
* For example if Gender is to be considered as an additional between group factor then in the json file, under "Subjects", for each subject, a corresponding dicitionary must be created where you mention the factor name and the corresponding value (eg: Subject_name: {"Gender" : "M"}). Please also note that the square brackets ('[', ']') after group type need to be changed to curly brackets ('{', '}').
240
240
* This must be similarly done for Stimuli, if any additional within group factor that describes the stimuli needs to be added. For example, if you are showing WORDS and PICTURES to elicit different responses from a user and you additonally have 2 different brightness levels ("High" and "Low") of the stimuli, you could consider Type1 and Type2 to be the PICTuRE and WORD gropus and mention Brightness as an additional within group factor.
241
241
242
-
The below code snippet just shows the changes that are to be done for Subject and Stimuli sections of the json file, the other sections remain the same.
242
+
The below code snippet just shows the changes that are to be done for Subject and Stimuli sections of the json file, the other sections remain the same.
243
243
244
244
```json
245
245
{
@@ -276,25 +276,25 @@ from PyTrack.Experiment import Experiment
# Calling the function for advanced statistical analysis of the data
282
+
# Calling the function for advanced statistical analysis of the data
283
283
# file_creation=True. Hence, the output of the data used to run the tests and the output of the tests will be stored in in the 'Results' folder inside your experiment folder
@@ -304,11 +304,11 @@ subject_name = "Sub_001" #specify your own subject's name (must be in json file)
304
304
stimulus_name ="Stim_1"#specify your own stimulus name (must be in json file)
305
305
306
306
# Access metadata dictionary for particular subject and stimulus
307
-
single_meta = exp.getMetaData(sub=subject_name,
307
+
single_meta = exp.getMetaData(sub=subject_name,
308
308
stim=stimulus_name)
309
309
310
310
# Access metadata dictionary for particular subject and averaged for stimulus types
311
-
agg_type_meta = exp.getMetaData(sub=subject_name,
311
+
agg_type_meta = exp.getMetaData(sub=subject_name,
312
312
stim=None)
313
313
314
314
```
@@ -329,10 +329,10 @@ import numpy as np
329
329
330
330
# function to convert data to generate csv file for data file recorded using EyeLink on both eyes and the stimulus name specified in the message section
To get started, first you need to choose which design you want to run
71
71
the framework in. If you wish to use the *Experiment Design*, see
@@ -94,7 +94,7 @@ for the listed directories to be present for the proper functioning of
94
94
│ │ subject_001.[asc/txt/tsv/...]
95
95
│ │ subject_002.[asc/txt/tsv/...]
96
96
| |__ ......
97
-
│
97
+
│
98
98
└── Stimulus/
99
99
│ │ stim_1.[jpg/jpeg]
100
100
│ │ stim_2.[jpg/jpeg]
@@ -272,10 +272,10 @@ for a detailed understanding of each function.
272
272
273
273
# function to convert data to generate database in base format for experiment done using EyeLink on both eyes and the stimulus name specified in the message section
# Calling the function for the statistical analysis of the data
295
295
# file_creation=True. Hence, the output of the data used to run the tests and the output of the tests will be stored in in the 'Results' folder inside your experiment folder
# Calling the function for advanced statistical analysis of the data
382
+
# Calling the function for advanced statistical analysis of the data
383
383
# file_creation=True. Hence, the output of the data used to run the tests and the output of the tests will be stored in in the 'Results' folder inside your experiment folder
stimulus_name ="Stim_1"#specify your own stimulus name (must be in json file)
405
405
406
406
# Access metadata dictionary for particular subject and stimulus
407
-
single_meta = exp.getMetaData(sub=subject_name,
407
+
single_meta = exp.getMetaData(sub=subject_name,
408
408
stim=stimulus_name)
409
409
410
410
# Access metadata dictionary for particular subject and averaged for stimulus types
411
-
agg_type_meta = exp.getMetaData(sub=subject_name,
411
+
agg_type_meta = exp.getMetaData(sub=subject_name,
412
412
stim=None)
413
413
414
414
Stand-alone Design
@@ -431,10 +431,10 @@ data for only 1 subject on a particular stimulus. If not, look at
431
431
432
432
# function to convert data to generate csv file for data file recorded using EyeLink on both eyes and the stimulus name specified in the message section
0 commit comments