Merge pull request #31 from marcobarilari/marco-readme

[WIP] readme for main folder and translational loc

Author: marcobarilari

README.md

@@ -1,19 +1,6 @@
-# motion_Visual-Localizer
-This repo collects the most common localizers in use to define hMT/V5
-
-
-## Installing dependencies
-
-All the dependencies needed to run this are listed in the [mpm-requirements.txt file](.mpm-requirements.txt). If those functions are not in the matlab path the scripts in this repository will not work.
+# Motion Visual-Localizer
 
-If you are using the [matlab package manager](https://github.com/mobeets/mpm), you can simply download the appropriate version of those dependencies and add them to your path by running the `getDependencies` function.
-
-```matlab
-getDependencies('update')
-```
-
-If you only already have the appropriate version but just want to add them to the matlab path, then run.
+This repo collects the most common localizers in use to define hMT/V5
 
-```matlab
-getDependencies()
-```
+1. Radial Motion
+2. [Translational motion](/Visual-loc_translational) (4 directions: up-, dowm-, left-, right-ward)

Visual-loc_translational/README.md

@@ -0,0 +1,97 @@
+# Translational Motion
+
+## Requirements
+
+Make sure that the following toolboxes are installed and added to the matlab / octave path.
+
+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.?        |
+
+## Installing dependencies
+
+All the dependencies needed to run this are listed in the [mpm-requirements.txt file](.mpm-requirements.txt). If those functions are not in the matlab path the scripts in this repository will not work.
+
+If you are using the [matlab package manager](https://github.com/mobeets/mpm), you can simply download the appropriate version of those dependencies and add them to your path by running the `getDependencies` function.
+
+```matlab
+getDependencies('update')
+```
+
+If you already have the appropriate version but just want to add them to the matlab path, then run.
+
+```matlab
+getDependencies()
+```
+## Structure and function details
+
+### visualLocTranslational
+
+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)
+
+By default it is run in `Debug mode` meaning that it does not run care about subjID, run n., fMRI triggers, Eye Tracker, etc..
+
+Any details of the experiment can be changed in `setParameters.m` (e.g., experiment mode, motion stimuli details, exp. design, etc.)
+
+### setParameters
+
+`setParameters.m` is the core engine of the experiment. It contains the following tweakable sections:
+
+- Debug mode setting
+- MRI settings
+- Engine parameters:
+  - Monitor parameters
+  - Monitor parameters for PsychToolBox
+- Keyboards
+- Experiment Design
+- Visual Stimulation
+- Task(s)
+  - Instructions
+  - Task #1 parameters
+
+### subfun/doDotMo
+
+#### 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
+
+#### Output:
+- Event `onset`
+- Event `duration`
+
+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
+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.
+
+#### EVENTS
+The `numEventsPerBlock` should be a multiple of the number of "base" listed in the `motionDirections` and `staticDirections` (4 at the moment).
+
+#### TARGETS:
+- 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
+
+#### Input:
+- `expParameters`: parameters returned by `setParameters`
+- `displayFigs`: a boolean to decide whether to show the basic design matrix of the design
+
+#### Output:
+- `expParameters.designBlockNames` is a cell array `(nr_blocks, 1)` with the name for each block
+- `expParameters.designDirections` is an array `(nr_blocks, numEventsPerBlock)` with the direction to present in a given block
+  - `0 90 180 270` indicate the angle
+  - `-1` indicates static
+- `expParameters.designSpeeds` is an array `(nr_blocks, numEventsPerBlock) * speedEvent`
+- `expParameters.designFixationTargets` is an array `(nr_blocks, numEventsPerBlock)` showing for each event if it should be accompanied by a target
+
+### subfun/eyeTracker
+Eyetracker script, still to be debugged. Will probably moved in the CPP_PTB package. It deals with the calibration (dufault or custom), eye movements recording and saving the files.
+
+### subfun/wait4Trigger
+Simple functions that counts the triggers sent by the MRI computer to the stimulation computer to sync brain volume recordings and stimulation.

Visual-loc_translational/setParameters.m

@@ -27,22 +27,6 @@
 cfg.numTriggers   = 4;
 cfg.eyeTracker    = false;      % Set to 'true' if you are testing in MRI and want to record ET data
 
-
-%% Keyboards
-
-% cfg.responseBox would be the device used by the participant to give his/her response:
-%   like the button box in the scanner or a separate keyboard for a behavioral experiment
-%
-% cfg.keyboard is the keyboard on which the experimenter will type or press the keys necessary
-%   to start or abort the experiment.
-%   The two can be different or the same.
-
-% Using empty vectors should work for linux and MacOS when to select the
-%   "main" keyboard. You might have to try some other values for Windows
-cfg.keyboard = [];
-cfg.responseBox = [];
-
-
 %% Engine parameters
 
 % Monitor parameters
@@ -61,11 +45,24 @@
 cfg.textSize         = 18;
 cfg.textStyle        = 1;
 
+%% Keyboards
+
+% cfg.responseBox would be the device used by the participant to give his/her response:
+%   like the button box in the scanner or a separate keyboard for a behavioral experiment
+%
+% cfg.keyboard is the keyboard on which the experimenter will type or press the keys necessary
+%   to start or abort the experiment.
+%   The two can be different or the same.
+
+% Using empty vectors should work for linux and MacOS when to select the
+%   "main" keyboard. You might have to try some other values for Windows
+cfg.keyboard = [];
+cfg.responseBox = [];
+
 % Keyboard
 cfg.escapeKey        = 'Escape';
 
 
-
 % The code below will help you decide which keyboard device to use for the partipant and the experimenter
 
 % Computer keyboard to quit if it is necessary
@@ -80,31 +77,31 @@
 
 
 switch lower(cfg.device)
-    
-    
+
+
     % this part might need to be adapted because the "default" device
     % number might be different for different OS or set up
-    
+
     case 'pc'
-        
+
         cfg.keyboard = [];
         cfg.responseBox = [];
-        
+
         if ismac
             cfg.keyboard = [];
             cfg.responseBox = [];
         end
-        
+
     case 'scanner'
-        
+
     otherwise
-        
+
         % Cfg.keyboard = max(Cfg.keyboardNumbers);
         % Cfg.responseBox = min(Cfg.keyboardNumbers);
-        
+
         cfg.keyboard = [];
         cfg.responseBox = [];
-        
+
 end
 
 %% Experiment Design
@@ -159,4 +156,4 @@
     fprintf('######################################## \n')
     fprintf('##  DEBUG MODE, NOT THE SCANNER CODE  ## \n')
     fprintf('######################################## \n\n')
-end
+end

Visual-loc_translational/subfun/doDotMo.m

@@ -5,12 +5,12 @@
 %  0=Right; 90=Up; 180=Left; 270=down
 %
 % Input:
-%   - Cfg: PTB/machine configurations returned by SetParameters and initPTB
-%   - ExpParameters: parameters returned by SetParameters
-%   - logFile: structur that stores the experiment logfile to be saved
+%   - cfg: PTB/machine configurations returned by setParameters and initPTB
+%   - expParameters: parameters returned by setParameters
+%   - logFile: structure that stores the experiment logfile to be saved
 %
 % Output:
-%     - 
+%     -
 %
 % 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
@@ -58,7 +58,7 @@
 % [1,1] is the bottom / right of the square that contains the square aperture
 xy = rand(ndots, 2);
 
-% Set a N x 2 matrix that gives jump size in pixels 
+% Set a N x 2 matrix that gives jump size in pixels
 %  pix/sec * sec/frame = pix / frame
 dxdy = repmat(...
     speed * 10/(diamAperture*10) * (3/cfg.monRefresh) ...
@@ -84,69 +84,69 @@
 onset = vbl;
 
 while continueShow
-    
+
     % L are the dots that will be moved
     L = rand(ndots,1) < coh;
-    
+
     % Move the selected dots
     xy(L,:) = xy(L,:) + dxdy(L,:);
-    
+
     % If not 100% coherence, we get new random locations for the other dots
     if sum(~L) > 0
         xy(~L,:) = rand(sum(~L),2);
     end
-    
+
     % Create a logical vector to detect any dot that has:
     % - an xy position inferior to 0
     % - an xy position superior to 1
     % - has exceeded its liftime
     N = any([xy > 1, xy < 0, dotTime > dotLifeTime], 2) ;
-    
+
     % If there is any such dot we relocate it to a new random position
     % and change its lifetime to 1
     if any(N)
         xy(N,:) = rand(sum(N), 2);
         dotTime(N, 1) = 1;
     end
-    
+
     % Convert the dot position to pixels
     xy_pix = floor( xy * diamAperturePix );
-    
+
     % This assumes that zero is at the top left, but we want it to be
     %  in the center, so shift the dots up and left, which just means
     %  adding half of the aperture size to both the x and y direction.
     xy_pix = (xy_pix - diamAperturePix/2)';
-    
+
     % NaN out-of-circle dots
     % We use Pythagore's theorem to figure out which dots are out of the
     % circle
     outCircle = sqrt(xy_pix(1,:).^2 + xy_pix(2,:).^2) + dotSizePix/2 > (diamAperturePix / 2);
     xy_pix(:, outCircle) = NaN;
-    
-    
+
+
     %% PTB draws the dots stimulation
-    
+
     % Draw the fixation cross
     color = expParameters.fixationCrossColor;
     % If this frame shows a target we change the color
     if GetSecs < (onset+targetDuration) && isTarget==1
         color = expParameters.fixationCrossColorTarget;
     end
     drawFixationCross(cfg, expParameters, color)
-    
+
     % Draw the dots
     Screen('DrawDots', cfg.win, xy_pix, dotSizePix, dotColor, cfg.center, 2);
-    
+
     Screen('DrawingFinished', cfg.win, dontClear );
-    
+
     vbl = Screen('Flip', cfg.win, vbl+cfg.ifi, dontClear );
-    
-    
+
+
     %% Update counters
 
     % Check for end of loop
     continueShow = continueShow - 1;
-    
+
     % Add one frame to the dot lifetime to each dot
     dotTime = dotTime + 1;