Merge branch 'dev' into dev

Author: Remi-Gau

README.md

@@ -29,21 +29,19 @@
 
 # fMRI localizers for visual motion
 
-## Translational Motion
-
 ## Requirements
 
-Make sure that the following toolboxes are installed and added to the matlab / octave path.
+Make sure that the following toolboxes are installed and added to the matlab / octave path. See the next section on how to install the submodule toolboxes.
 
 For instructions see the following links:
 
-| Requirements                                             | Used version |
-| -------------------------------------------------------- | ------------ |
-| [CPP_BIDS](https://github.com/cpp-lln-lab/CPP_BIDS)      | ?            |
-| [CPP_PTB](https://github.com/cpp-lln-lab/CPP_PTB)        | ?            |
-| [PsychToolBox](http://psychtoolbox.org/)                 | >=3.0.14     |
-| [Matlab](https://www.mathworks.com/products/matlab.html) | >=2017       |
-| or [octave](https://www.gnu.org/software/octave/)        | >=4.?        |
+| Requirements                                                    | Used version |
+| --------------------------------------------------------------- | ------------ |
+| [CPP_BIDS](https://github.com/cpp-lln-lab/CPP_BIDS) (submodule) | 2.1.0        |
+| [CPP_PTB](https://github.com/cpp-lln-lab/CPP_PTB) (submodule)   | 1.2.0        |
+| [PsychToolBox](http://psychtoolbox.org/)                        | >=3.0.14     |
+| [Matlab](https://www.mathworks.com/products/matlab.html)        | >=2017       |
+| or [octave](https://www.gnu.org/software/octave/)               | >=4.?        |
 
 ## Installation
 
@@ -56,11 +54,11 @@ git clone --recurse-submodules https://github.com/cpp-lln-lab/localizer_visual_m
 
 ## Structure and function details
 
-### visualLocTranslational
+### visualMotionLocalizer
 
-Running this script will show blocks of motion dots (soon also moving gratings) and static dots. Motion blocks will show dots(/gratings) moving in one of four directions (up-, down-, left-, and right-ward)
+Running this script will show blocks of motion dots and static dots. Motion blocks will show dots moving in one of four directions (up-, down-, left-, and right-ward) (MT+ localizer) or dots moving inward and outward in the peripheral of the screen (MT/MST localizer).
 
-By default it is run in `Debug mode` meaning that it does not run care about subjID, run n., fMRI triggers, Eye Tracker, etc..
+Run in `Debug mode` (see `setParameters.m`) it does not care about subjID, run n., Eye Tracker (soon, at the moment it needs to be set off manually), etc..
 
 Any details of the experiment can be changed in `setParameters.m` (e.g., experiment mode, motion stimuli details, exp. design, etc.)
 
@@ -85,7 +83,7 @@ Any details of the experiment can be changed in `setParameters.m` (e.g., experim
 Set `cfg.pacedByTriggers.do` to `true` and you can then set all the details in this `if` block
 
 ```matlab
-% Time is here in in terms of number repetition time (i.e MRI volumes)
+% Time is here in terms of `repetition time (TR)` (i.e. MRI volumes)
 if cfg.pacedByTriggers.do
 
   cfg.pacedByTriggers.quietMode = true;
@@ -107,22 +105,27 @@ end
 
 ### subfun/doDotMo
 
+Wrapper function that present the dot stimulation (static or motion) per event.
+
 #### Input
 
-- `cfg`: PTB/machine configurations returned by `setParameters` and `initPTB`
-- `expParameters`: parameters returned by `setParameters`
-- `logFile`: structure that stores the experiment logfile to be saved
+- `cfg`: PTB/machine and experiment configurations returned by `setParameters` and `initPTB`
+- `thisEvent`: structure that stores information about the event to present regarding the dots (static or motion, direction, etc.)
+- `thisFixation`: structure that stores information about the fixation cross task to present
+- `dots`: [...]
+- `iEvent`: index of the event of the block at the moment of the presentation
 
 #### Output
 
 - Event `onset`
 - Event `duration`
+- `dots`: [...]
 
-The dots are drawn on a square that contains the round aperture, then any dots outside of the aperture is turned into a NaN so effectively the actual number of dots on the screen at any given time is not the one that you input but a smaller number (nDots / Area of aperture) on average.
+> NB: The dots are drawn on a square that contains the round aperture, then any dots outside of the aperture is turned into a NaN so effectively the actual number of dots on the screen at any given time is not the one that you input but a smaller number (nDots / Area of aperture) on average.
 
-### subfun/expDesign
+### subfun/expDesign(MtMst)
 
-Creates the sequence of blocks and the events in them. The conditions are consecutive static and motion blocks (Gives better results than randomised). It can be run as a stand alone without inputs to display a visual example of possible design.
+These functions, one per MT+ and one per MT/MST localizer, create the sequence of blocks and the events in them. The conditions are consecutive static and motion blocks (Gives better results than randomised). It can be run as a stand alone with input `cfg` from `setParamenters.m` to display a visual example of possible design.
 
 #### EVENTS
 

setParameters.m

@@ -4,7 +4,7 @@
 
     % VISUAL LOCALIZER
 
-    % Initialize the parameters and general configuration variables
+    % Initialize the general configuration variables structure
     cfg = struct();
 
     % by default the data will be stored in an output folder created where the
@@ -15,7 +15,7 @@
 
     %% Debug mode settings
 
-    cfg.debug.do = false; % To test the script out of the scanner, skip PTB sync
+    cfg.debug.do = true; % To test the script out of the scanner, skip PTB sync
     cfg.debug.smallWin = false; % To test on a part of the screen, change to 1
     cfg.debug.transpWin = false; % To test with trasparent full size screen
 
@@ -26,7 +26,7 @@
     %% Engine parameters
 
     cfg.testingDevice = 'mri';
-    cfg.eyeTracker.do = true;
+    cfg.eyeTracker.do = false;
     cfg.audio.do = false;
 
     cfg = setMonitor(cfg);
@@ -36,9 +36,9 @@
 
     % MRI settings
     cfg = setMRI(cfg);
-    cfg.suffix.acquisition = '0p75mmEvTr2p18';
+    %     cfg.suffix.acquisition = '';
 
-    cfg.pacedByTriggers.do = false;
+    cfg.pacedByTriggers.do = true;
 
     %% Experiment Design
 
@@ -49,14 +49,16 @@
     % side of the screen relative to the fixation
     %   - alternates fixaton left and fixation right
     cfg.design.localizer = 'MT';
-    % cfg.design.localizer = 'MT_MST';
+    %     cfg.design.localizer = 'MT_MST';
 
     cfg.design.motionType = 'translation';
     cfg.design.motionDirections = [0 0 180 180];
     cfg.design.names = {'static'; 'motion'};
 
-    cfg.design.nbRepetitions = 12;
-    cfg.design.nbEventsPerBlock = 12; % DO NOT CHANGE
+    % if you have static and motion and `nbRepetions` = 4, this will return 8 blocks (n blocks per
+    % hemifield in case of MT/MST localizer)
+    cfg.design.nbRepetitions = 10;
+    cfg.design.nbEventsPerBlock = 10;
 
     %% Timing
 
@@ -66,7 +68,7 @@
     % IBI
     % block length = (cfg.eventDuration + cfg.ISI) * cfg.design.nbEventsPerBlock
 
-    cfg.timing.eventDuration = 0.79; % second
+    cfg.timing.eventDuration = 0.30; % second
 
     % Time between blocs in secs
     cfg.timing.IBI = 0;
@@ -81,11 +83,13 @@
     if cfg.pacedByTriggers.do
 
         cfg.pacedByTriggers.quietMode = true;
-        cfg.pacedByTriggers.nbTriggers = 5;
+        cfg.pacedByTriggers.nbTriggers = 1;
 
         cfg.timing.eventDuration = cfg.mri.repetitionTime / 2 - 0.04; % second
 
-        % Time between blocs in secs
+        % Time between blocs in nb of triggers (remember to consider the nb trigger to wait + 1)
+        cfg.timing.triggerIBI = 4;
+        % Time between blocks in secs
         cfg.timing.IBI = 0;
         % Time between events in secs
         cfg.timing.ISI = 0;
@@ -214,12 +218,23 @@
         cfg.task.name = 'mt mst localizer';
 
         cfg.design.motionType = 'radial';
-        cfg.design.motionDirections = [666 666 -666 -666];
-        cfg.design.names = {'fixation_right'; 'fixation_left'};
+        cfg.design.motionDirections = [666 -666];
+        %         cfg.design.names = {'motion'};
+        cfg.design.names = {'static'; 'motion'};
+        cfg.design.fixationPosition = {'fixation_left'; 'fixation_right'};
+        %          cfg.design.fixationPosition = {'fixation_right'; 'fixation_left'};
         cfg.design.xDisplacementFixation = 7;
         cfg.design.xDisplacementAperture = 3;
 
-        cfg.timing.IBI = 3.6;
+        % here we double the repetions (2 hemifields)
+        cfg.design.nbRepetitions = cfg.design.nbRepetitions * length(cfg.design.fixationPosition);
+
+        % inward&outward are presented as separated event
+        cfg.design.nbEventsPerBlock = cfg.design.nbEventsPerBlock * 2;
+
+        cfg.timing.IBI = 4;
+
+        cfg.timing.changeFixationPosition = 10;
 
         % reexpress those in terms of repetition time
         if cfg.pacedByTriggers.do

subfun/assignConditions.m

@@ -9,9 +9,12 @@
     % Get the index of each condition
     nameCondition1 = 'static';
     nameCondition2 = 'motion';
+
     if isfield(cfg.design, 'localizer') && strcmpi(cfg.design.localizer, 'MT_MST')
-        nameCondition1 = 'fixation_right';
-        nameCondition2 = 'fixation_left';
+
+        nameCondition1 = 'static';
+        nameCondition2 = 'motion';
+
     end
 
     CONDITON1_INDEX = find(strcmp(conditionNamesVector, nameCondition1));

subfun/doDotMo.m

@@ -1,7 +1,7 @@
 % (C) Copyright 2018 Mohamed Rezk
 % (C) Copyright 2020 CPP visual motion localizer developpers
 
-function [onset, duration, dots] = doDotMo(cfg, thisEvent, thisFixation, dots)
+function [onset, duration, dots] = doDotMo(cfg, thisEvent, thisFixation, dots, iEvent)
     % Draws the stimulation of static/moving in 4 directions dots or static
     %
     % DIRECTIONS
@@ -42,7 +42,13 @@
 
         %% make textures
 
-        dotTexture('make', cfg, thisEvent);
+        if strcmp(cfg.design.localizer, 'MT_MST') && strcmpi(thisEvent.trial_type, 'static') && ~mod(iEvent, 2)
+
+        else
+
+            dotTexture('make', cfg, thisEvent);
+
+        end
 
         apertureTexture('make', cfg, thisEvent);
 

subfun/expDesignMtMst.m

@@ -0,0 +1,107 @@
+% (C) Copyright 2021 CPP visual motion localizer developpers
+
+function [cfg] = expDesignMtMst(cfg, displayFigs)
+
+    %% Check inputs
+
+    % Set to 1 for a visualtion of the trials design order
+    if nargin < 2 || isempty(displayFigs)
+        displayFigs = 0;
+    end
+
+    % Set variables here for a dummy test of this function
+    if nargin < 1 || isempty(cfg)
+        error('give me something to work with');
+    end
+
+    fprintf('\n\nCreating design.\n\n');
+
+    [NB_BLOCKS, NB_REPETITIONS, NB_EVENTS_PER_BLOCK, MAX_TARGET_PER_BLOCK] = getDesignInput(cfg);
+    [~, CONDITON1_INDEX, CONDITON2_INDEX] = assignConditions(cfg);
+
+    if mod(NB_REPETITIONS, MAX_TARGET_PER_BLOCK) ~= 0
+        error('number of repetitions must be a multiple of max number of targets');
+    end
+
+    RANGE_TARGETS = 1:MAX_TARGET_PER_BLOCK;
+    targetPerCondition = repmat(RANGE_TARGETS, 1, NB_REPETITIONS / MAX_TARGET_PER_BLOCK);
+
+    numTargetsForEachBlock = zeros(1, NB_BLOCKS);
+
+    if strcmpi(cfg.design.localizer, 'MT_MST') && length(cfg.design.names) == 2
+        numTargetsForEachBlock(CONDITON1_INDEX) = shuffle(targetPerCondition);
+    end
+
+    numTargetsForEachBlock(CONDITON2_INDEX) = shuffle(targetPerCondition);
+
+    %% Give the blocks the names with condition and design the task in each event
+    while 1
+
+        fixationTargets = zeros(NB_BLOCKS, NB_EVENTS_PER_BLOCK);
+
+        for iBlock = 1:NB_BLOCKS
+
+            % Set target
+            % - if there are 2 targets per block we make sure that they are at least
+            % 2 events apart
+            % - targets cannot be on the first or last event of a block
+            % - no more than 2 target in the same event order
+
+            nbTarget = numTargetsForEachBlock(iBlock);
+
+            chosenPosition = setTargetPositionInSequence( ...
+                                                         NB_EVENTS_PER_BLOCK, ...
+                                                         nbTarget, ...
+                                                         [1 NB_EVENTS_PER_BLOCK]);
+
+            fixationTargets(iBlock, chosenPosition) = 1;
+
+        end
+
+        % Check rule 3
+        if max(sum(fixationTargets)) < NB_REPETITIONS - 1
+            break
+        end
+
+    end
+
+    %% Now we do the easy stuff
+    cfg.design.blockNames = assignConditions(cfg);
+
+    if strcmpi(cfg.design.localizer, 'MT_MST')
+
+        if length(cfg.design.names) == 1
+
+            nbBlocksPerHemifield = (NB_REPETITIONS / 4) * ...
+                                                  length(cfg.design.fixationPosition);
+
+        else
+
+            nbBlocksPerHemifield = (NB_REPETITIONS / 2) * ...
+                length(cfg.design.fixationPosition);
+
+        end
+
+        cfg.design.blockFixationPosition = repmat(cfg.design.fixationPosition(1), ...
+                                                  nbBlocksPerHemifield, ...
+                                                  1);
+
+        if length(cfg.design.fixationPosition) == 2
+
+            cfg.design.blockFixationPosition = [cfg.design.blockFixationPosition; ...
+                                                repmat(cfg.design.fixationPosition(2), ...
+                                                       nbBlocksPerHemifield, ...
+                                                       1)];
+
+        end
+
+    end
+
+    cfg.design.nbBlocks = NB_BLOCKS;
+
+    cfg = setDirections(cfg);
+
+    speeds = ones(NB_BLOCKS, NB_EVENTS_PER_BLOCK) * cfg.dot.speedPixPerFrame;
+    cfg.design.speeds = speeds;
+
+    cfg.design.fixationTargets = fixationTargets;

subfun/getDirectionBaseVectors.m

@@ -12,6 +12,11 @@
     if isfield(cfg.design, 'localizer') && strcmpi(cfg.design.localizer, 'MT_MST')
         CONDITION1_DIRECTIONS = cfg.design.motionDirections;
         CONDITION2_DIRECTIONS = cfg.design.motionDirections;
+
+        if  length(cfg.design.names) == 2
+            CONDITION2_DIRECTIONS = repmat(-1, size(CONDITION1_DIRECTIONS)); % static
+        end
+
     end
 
 end

subfun/preTrialSetup.m

@@ -28,22 +28,28 @@
 
     thisEvent.dotCenterXPosPix = 0;
 
-    switch thisEvent.trial_type
-        case 'fixation_right'
-            cfg.aperture.xPosPix = -abs(cfg.aperture.xPosPix);
+    if isfield(cfg.design, 'localizer') && strcmpi(cfg.design.localizer, 'MT_MST')
 
-            thisEvent.dotCenterXPosPix = cfg.aperture.xPosPix;
+        thisEvent.fixationPosition = cfg.design.blockFixationPosition{iBlock};
 
-            thisFixation.fixation.xDisplacement = cfg.design.xDisplacementFixation;
-            thisFixation = initFixation(thisFixation);
+        switch thisEvent.fixationPosition
+            case 'fixation_right'
+                cfg.aperture.xPosPix = -abs(cfg.aperture.xPosPix);
 
-        case 'fixation_left'
-            cfg.aperture.xPosPix = +abs(cfg.aperture.xPosPix);
+                thisEvent.dotCenterXPosPix = cfg.aperture.xPosPix;
 
-            thisEvent.dotCenterXPosPix = cfg.aperture.xPosPix;
+                thisFixation.fixation.xDisplacement = cfg.design.xDisplacementFixation;
+                thisFixation = initFixation(thisFixation);
 
-            thisFixation.fixation.xDisplacement = -cfg.design.xDisplacementFixation;
-            thisFixation = initFixation(thisFixation);
+            case 'fixation_left'
+                cfg.aperture.xPosPix = +abs(cfg.aperture.xPosPix);
+
+                thisEvent.dotCenterXPosPix = cfg.aperture.xPosPix;
+
+                thisFixation.fixation.xDisplacement = -cfg.design.xDisplacementFixation;
+                thisFixation = initFixation(thisFixation);
+
+        end
 
     end