Skip to content

EyeTracker - add switch case to record a 'message' (tag) in the output #106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Sep 23, 2020
Merged

EyeTracker - add switch case to record a 'message' (tag) in the output #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
aced700
add draft of the code
marcobarilari Sep 23, 2020
ef1d712
mh fix
marcobarilari Sep 23, 2020
8c9b8e7
move up the code
marcobarilari Sep 23, 2020
54d5a35
add explanation
marcobarilari Sep 23, 2020
2b85087
add explanation pt2
marcobarilari Sep 23, 2020
c93313f
update documentation
marcobarilari Sep 23, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 27 additions & 26 deletions docs/10_functions_description.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@

This will initialize PsychToolBox.

It is pretty much necessary to use this function to set up the stage for using
It is pretty much necessary to use this function to set up the stage for using
any other functions of CPP_PTB.

- checks OS and PTB version
Expand All @@ -57,45 +57,46 @@ any other functions of CPP_PTB.

### 1.2. <a name='cleanUp'></a>cleanUp

A wrapper function to close all windows, ports, show mouse cursor, close keyboard
A wrapper function to close all windows, ports, show mouse cursor, close keyboard
queues and give you back access to the keyboards.

### 1.3. <a name='getExperimentStart'></a>getExperimentStart

Wrapper function that will show a fixation cross and collect a start timestamp
Wrapper function that will show a fixation cross and collect a start timestamp
in `cfg.experimentStart`

### 1.4. <a name='getExperimentEnd'></a>getExperimentEnd

Wrapper function that will show a fixation cross and display in the console
Wrapper function that will show a fixation cross and display in the console
the whole experiment's duration in minutes and seconds

### 1.5. <a name='degToPix'></a>degToPix

For a given field value in degrees of visual angle in the input `structure`,
this computes its value in pixel using the pixel per degree value of the `cfg`
this computes its value in pixel using the pixel per degree value of the `cfg`
structure and returns a structure with an additional field with Pix suffix holding that new value.

### 1.6. <a name='computeFOV'></a>computeFOV

Gives you the width of the field on view in degress of visual angle based on
Gives you the width of the field on view in degress of visual angle based on
the screen width and distance to the screen in cm (taken from the `cfg`)

### 1.7. <a name='eyeTracker'></a>eyeTracker

This will handle the Eye Tracker (EyeLink set up) and can be called to initialize
the connection and start the calibration, start/stop eye(s) movement recordings
This will handle the Eye Tracker (EyeLink set up) and can be called to initialize
the connection and start the calibration, start/stop eye(s) movement recordings
and save the `*.edf` file (named with BIDS specification from cpp-lln-lab/CPP_BIDS).

There are several actions to perform:

- Calibration: to initialize EyeLink and run calibration
- 'default calibration' (default) will run a calibration with 6 points
- 'custom calibration' (cfg.eyeTracker.defaultCalibration = 'false') will run
- 'custom calibration' (cfg.eyeTracker.defaultCalibration = 'false') will run
a calibration with 6 points but the experimenter can choose their position on the screen
- StartRecording: to start eye movements recording
- Message: will add a tag (e.g. 'Block_n1') in the ET output file, the tag is a string and it is input from `varargin`
- StopRecordings: to stop eye movements recornding
- Shutdown: to save the `.edf` file with BIDS compliant name, from cpp-lln-lab/CPP_BIDS,
- Shutdown: to save the `.edf` file with BIDS compliant name, from cpp-lln-lab/CPP_BIDS,
in the output folder and shut the connection between the stimulation computer and the EyeLink computer

### 1.8. <a name='standByScreen'></a>standByScreen
Expand All @@ -107,7 +108,7 @@ It shows a basic one-page instruction stored in `cfg.task.instruction` and wait
Counts a certain number of triggers coming from the mri/scanner before returning.
Requires number of triggers to wait for.

This can also be used if you want to let the scanner pace the experiment and you
This can also be used if you want to let the scanner pace the experiment and you
want to synch stimulus presentation to the scanner trigger.

### 1.10. <a name='waitFor'></a>waitFor
Expand All @@ -116,8 +117,8 @@ A generic function that you can use to for a certain amount of time or a number

### 1.11. <a name='readAndFilterLogfile'></a>readAndFilterLogfile

Displays in the command window part of the `*events.tsv` file filtered by an element
(e.g. 'trigger'). It can take the last output produced (through `cfg`) or any
Displays in the command window part of the `*events.tsv` file filtered by an element
(e.g. 'trigger'). It can take the last output produced (through `cfg`) or any
output BIDS compatible (through file path).

## 2. <a name='Keyboardfunctions:responsecollectionandabortingexperiment'></a>Keyboard functions: response collection and aborting experiment
Expand All @@ -130,7 +131,7 @@ If no key is pressed on the correct keyboard after the timeOut time this exits w

### 2.2. <a name='getResponse'></a>getResponse

It is wrapper function to use `KbQueue` which is definitely what you should use
It is wrapper function to use `KbQueue` which is definitely what you should use
to collect responses.

You can easily collect responses while running some other code at the same time.
Expand All @@ -146,15 +147,15 @@ If you want to know more on how to use it check its help section and the `CPP_ge

In brief, there are several actions you can execute with this function.

- init: initialize the buffer for key presses on a given device (you can also
- init: initialize the buffer for key presses on a given device (you can also
specify the keys of interest that should be listened to).
- start: start listening to the key presses (carefully insert into your script -
- start: start listening to the key presses (carefully insert into your script -
where do you want to start buffering the responses).
- check: till that point, it will check the buffer for all key presses.
- It only reports presses on the keys of interest mentioned at initialization.
- It **can** also check for presses on the escape key and abort if the escape
- It **can** also check for presses on the escape key and abort if the escape
key is part of the keys of interest.
- flush: empties the buffer of key presses in case you want to discard any
- flush: empties the buffer of key presses in case you want to discard any
previous key presses.
- stop: stops buffering key presses. You can still restart by calling "start" again.
- release: closes the buffer for good.
Expand All @@ -163,13 +164,13 @@ previous key presses.

Use that to stop your script and only restart when the space bar is pressed.

This can be useful if as an experimenter you want to have one final check on
This can be useful if as an experimenter you want to have one final check on
some set up before giving the green light.

### checkAbort

A simple function that will quit your experiment if you press the key you have
defined in `cfg.keyboard.escapeKey`.
A simple function that will quit your experiment if you press the key you have
defined in `cfg.keyboard.escapeKey`.

## 3. <a name='Fixations'></a>Fixations

Expand All @@ -187,17 +188,17 @@ Functions that can be used to create random stimuli sequences.

### 6.1. <a name='shuffle'></a>shuffle

Is just there to replace the Shuffle function from PTB in case it is not in the
Is just there to replace the Shuffle function from PTB in case it is not in the
path. Can be useful for testing or for continuous integration.

### 6.2. <a name='setTargetPositionInSequence'></a>setTargetPositionInSequence

For a sequence of length `seqLength` where we want to insert `nbTarget` targets,
this will return `nbTarget` random position in that sequence and make sure that
For a sequence of length `seqLength` where we want to insert `nbTarget` targets,
this will return `nbTarget` random position in that sequence and make sure that
they are not in consecutive positions.

### 6.3. <a name='repeatShuffleConditions'></a>repeatShuffleConditions

Given `baseConditionVector`, a vector of conditions (coded as numbers), this will
create a longer vector made of `nbRepeats` of this base vector and make sure that
Given `baseConditionVector`, a vector of conditions (coded as numbers), this will
create a longer vector made of `nbRepeats` of this base vector and make sure that
a given condition is not repeated one after the other.
45 changes: 28 additions & 17 deletions src/eyeTracker.m
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
function [el, cfg] = eyeTracker(input, cfg)
% [el] = eyeTracker(input, cfg)
function [el, cfg] = eyeTracker(input, cfg, varargin)
% [el] = eyeTracker(input, cfg, varargin)
%
% Wrapper function that deals with all the necessery actions to implement
% Eye Tracker recording with eyelink.
Expand All @@ -12,6 +12,8 @@
% -- 'custom calibration' (cfg.eyeTracker.defaultCalibration = 'false') will run a
% calibration with 6 points but the experimenter can choose their position on the screen
% - StartRecording: to start eye movements recording
% - Message: will add a tag (e.g. 'Block_n1') in the ET output file, the tag is a string and it
% is input from `varargin`
% - StopRecordings: to stop eye movements recornding
% - Shutdown: to save the `.edf` file with BIDS compliant name, from cpp-lln-lab/CPP_BIDS, in
% the output folder and shut the connection between the stimulation computer and the EyeLink
Expand Down Expand Up @@ -102,21 +104,21 @@
Eyelink('Command', 'calibration_samples = 6');
Eyelink('Command', 'calibration_sequence = 0,1,2,3,4,5');
Eyelink('Command', 'calibration_targets = %d,%d %d,%d %d,%d %d,%d %d,%d', ...
640, 512, ... % width/2,height/2
640, 102, ... % width/2,height*0.1
640, 614, ... % width/2,height*0.6
128, 341, ... % width*0.1,height*1/3
1152, 341); % width-width*0.1,height*1/3
640, 512, ... % width/2,height/2
640, 102, ... % width/2,height*0.1
640, 614, ... % width/2,height*0.6
128, 341, ... % width*0.1,height*1/3
1152, 341); % width-width*0.1,height*1/3

% Validation target locations
Eyelink('Command', 'validation_samples = 5');
Eyelink('Command', 'validation_sequence = 0,1,2,3,4,5');
Eyelink('Command', 'validation_targets = %d,%d %d,%d %d,%d %d,%d %d,%d', ...
640, 512, ... % width/2,height/2
640, 102, ... % width/2,height*0.1
640, 614, ... % width/2,height*0.6
128, 341, ... % width*0.1,height*1/3
1152, 341); % width-width*0.1,height*1/3
640, 512, ... % width/2,height/2
640, 102, ... % width/2,height*0.1
640, 614, ... % width/2,height*0.6
128, 341, ... % width*0.1,height*1/3
1152, 341); % width-width*0.1,height*1/3

end

Expand Down Expand Up @@ -157,6 +159,15 @@
% Mark the beginning of the trial, here start the stimulation of the experiment.
Eyelink('Message', 'start_recording');

case 'Message'

%% Add tag during the recording (e.g. trial_type)

message = varargin;

% EyeLink Stop recording the block.
Eyelink('Message', message);

case 'StopRecordings'

%% Stop recording of eye-movements
Expand All @@ -177,9 +188,9 @@

% Set the edf file path + name.
edfFileName = fullfile( ...
cfg.dir.outputSubject, ...
cfg.fileName.modality, ...
cfg.fileName.eyetracker);
cfg.dir.outputSubject, ...
cfg.fileName.modality, ...
cfg.fileName.eyetracker);

Eyelink('Command', 'set_idle_mode');

Expand All @@ -203,8 +214,8 @@
if exist(edfFileName, 'file') == 2

fprintf('Data file ''%s'' can be found in ''%s''\n', ...
cfg.fileName.eyetracker, ...
fullfile(cfg.dir.outputSubject, 'eyetracker'));
cfg.fileName.eyetracker, ...
fullfile(cfg.dir.outputSubject, 'eyetracker'));

end

Expand Down