Merge pull request #105 from Remi-Gau/misc

[INFRA, DOC, REF] Misc

Author: Remi-Gau

.gitignore

@@ -5,9 +5,9 @@
 */logfiles/*
 */*/*/logfiles/*
 *.tsv
-*.mat
 
 output
+source
 
 ## virtual env
 env/

README.md

@@ -6,22 +6,19 @@
 - [fMRI localizers for visual motion](#fmri-localizers-for-visual-motion)
   - [Requirements](#requirements)
   - [Installation](#installation)
-  - [Structure and function details](#structure-and-function-details)
-    - [visualMotionLocalizer](#visualmotionlocalizer)
-    - [setParameters](#setparameters)
-      - [Let the scanner pace the experiment](#let-the-scanner-pace-the-experiment)
-    - [subfun/doDotMo](#subfundodotmo)
-      - [Input](#input)
-      - [Output](#output)
-    - [subfun/design/expDesign](#subfundesignexpdesign)
-      - [Events](#events)
-      - [Pseudorandomization rules:](#pseudorandomization-rules)
-      - [Input:](#input-1)
-      - [Output:](#output-1)
+  - [Set up and running](#set-up-and-running)
   - [Contributors ✨](#contributors-)
 
 # fMRI localizers for visual motion
 
+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).
+
 ## Requirements
 
 Make sure that the following toolboxes are installed and added to the matlab /
@@ -39,160 +36,45 @@ For instructions see the following links:
 
 ## Installation
 
-The CPP_BIDS and CPP_PTB dependencies are already set up as submodule to this
+The CPP_BIDS and CPP_PTB dependencies are already set up as submodules to this
 repository. You can install it all with git by doing.
 
 ```bash
 git clone --recurse-submodules https://github.com/cpp-lln-lab/localizer_visual_motion.git
 ```
 
-## Structure and function details
-
-### visualMotionLocalizer
-
-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).
-
-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.)
+## Set up and running
 
-### setParameters
+In the `main.m` script, you are meant
 
-`setParameters.m` is the core engine of the experiment. It contains the
-following tweakable sections:
+- to set your configuration (`cfg`)
+- call `initEnv()` to add the relevant folders to the MATLAB path
+- call `cfg = checkParameters(cfg)` to set up any default configuration you did
+  not set.
+- call `visualMotionLocalizer(cfg)` to run the localizer.
 
-- Debug mode setting
-- MRI settings
-- Engine parameters:
-  - Monitor parameters
-  - Monitor parameters for PsychToolBox
-- Keyboards
-- Experiment Design
-- Visual Stimulation
-- Task(s)
-  - Instructions
-  - Task #1 parameters
-
-#### Let the scanner pace the experiment
-
-Set `cfg.pacedByTriggers.do` to `true` and you can then set all the details in
-this `if` block
+The minimalist script would thus look like:
 
 ```matlab
-% Time is here in terms of `repetition time (TR)` (i.e. MRI volumes)
-if cfg.pacedByTriggers.do
+clc;
+clear;
 
-  cfg.pacedByTriggers.quietMode = true;
-  cfg.pacedByTriggers.nbTriggers = 1;
+%% Run MT+ localizer
 
-  cfg.timing.eventDuration = cfg.mri.repetitionTime / 2 - 0.04; % second
+cfg.design.localizer = 'MT';
+initEnv();
 
-  % Time between blocs in secs
-  cfg.timing.IBI = 0;
-  % Time between events in secs
-  cfg.timing.ISI = 0;
-  % Number of seconds before the motion stimuli are presented
-  cfg.timing.onsetDelay = 0;
-  % Number of seconds after the end all the stimuli before ending the run
-  cfg.timing.endDelay = 2;
+cfg = checkParameters(cfg);
 
-end
+% Run
+visualMotionLocalizer(cfg);
 ```
 
-### subfun/doDotMo
-
-Wrapper function that present the dot stimulation (static or motion) per event.
-
-#### Input
-
-- `cfg`: PTB/machine and experiment configurations returned by `setParameters`
-  and `initPTB`
-- `logFile`: structure that stores the experiment logfile to be saved
-- `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`: [...]
-
-> 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/design/expDesign
-
-This function and its companions creates the sequence of blocks (static/motion)
-and the events (the single directions) for MT+ and MT/MST localizers. The
-conditions are consecutive static and motion blocks (fixed in this order gives
-better results than randomised).
-
-It can be run as a stand alone without inputs and displays a visual example of
-the possible design. See `getMockConfig` to set up the mock configuration.
-
-It computes the directions to display and the task(s), at the moment:
-
-1. detection of change in the color of the fixation target
-2. detection of different speed of the moving dots [ W I P - if selected as a
-   task it will give the same null output as if not selected ie no difference in
-   speed]
-
-#### Events
-
-The `nbEventsPerBlock` should be a multiple of the number of motion directions
-requested in `motionDirections` (which should be more than 1) e.g.:
-
-- MT localizer:
-  `cfg.design.motionDirections = [ 0 90 180 270 ]; % right down left up`
-- MT_MST localizer: `cfg.design.motionDirections = [666 -666]; % outward inward`
-
-#### Pseudorandomization rules:
-
-- Directions:
-
-1. Directions are all presented in random orders in
-   `numEventsPerBlock/nDirections` consecutive chunks. This evenly distribute
-   the directions across the block.
-2. No same consecutive direction
-
-- Color change detection of the fixation cross:
-
-1. If there are 2 targets per block we make sure that they are at least 2 events
-   apart.
-2. Targets cannot be on the first or last event of a block.
-3. No less than 1 target per event position in the whole run
-
-#### Input:
-
-- `cfg`: parameters returned by setParameters
-- `displayFigs`: a boolean to decide whether to show the basic design matrix of
-  the design
-
-#### Output:
+Type `help checkParameters` and see the [README in docs](./docs/README.md) to
+get more information about the configuration options.
 
-- `cfg.design.blockNames`: cell array (nbBlocks, 1) with the condition name for
-  each block
-- `cfg.design.nbBlocks`: integer for th etotal number of blocks in the run
-- `cfg.design.directions`: array (nbBlocks, nbEventsPerBlock) with the direction
-  to present in a given event of a block.
-  - 0 90 180 270 indicate the angle for translational motion direction
-  - 666 -666 indicate in/out-ward direction in radial motion
-  - -1 indicates static
-- `cfg.design.speeds`: array (nbBlocks, nbEventsPerBlock) indicate the dots
-  speed in each event, the target is represented by a higher/lower value
-- `cfg.design.fixationTargets`: array (nbBlocks, numEventsPerBlock) showing for
-  each event if it should be accompanied by a target
+Run in debug mode (set `cfg.debug.do = true`) it does not care about subjID, run
+n., Eye Tracker...
 
 ## Contributors ✨
 

cfgMST.m

@@ -0,0 +1,13 @@
+function cfg = cfgMST(cfg)
+    %
+    % (C) Copyright 2020 CPP visual motion localizer developers
+
+    cfg.design.localizer = 'MT_MST';
+
+    cfg.design.nbRepetitions = 10;
+
+    cfg.design.nbEventsPerBlock = 10;
+
+    cfg.timing.eventDuration = 0.3; % 0.6 seconds
+
+end

cfgMT.m

@@ -0,0 +1,15 @@
+function cfg = cfgMT(cfg)
+    %
+    % (C) Copyright 2020 CPP visual motion localizer developers
+
+    cfg.design.localizer = 'MT';
+
+    cfg.pacedByTriggers.do = true;
+
+    cfg.mri.triggerNb = 0;
+
+    cfg.design.nbRepetitions = 15;
+
+    cfg.timing.eventDuration = 0.43; % .86 second
+
+end

docs/configurations.md

@@ -0,0 +1,133 @@
+# Configurations
+
+- [Configurations](#configurations)
+  - [For MT localiser](#for-mt-localiser)
+  - [Let the scanner pace the experiment](#let-the-scanner-pace-the-experiment)
+
+## For MT localiser
+
+These are all the options that can be tweaked.
+
+```matlab
+cfg.aperture.type =	'none';
+cfg.aperture.width =	[];
+cfg.aperture.xPos =	0.000000;
+cfg.audio.do =	0;
+cfg.bids.MRI.Instructions =	'1-Detect the RED fixation cross';
+cfg.bids.MRI.TaskDescription =	'';
+cfg.bids.mri.RepetitionTime =	[];
+cfg.color.background =	0.000000, 0.000000, 0.000000;
+cfg.color.black =	0.000000, 0.000000, 0.000000;
+cfg.color.blue =	0.000000, 255.000000, 0.000000;
+cfg.color.green =	0.000000, 0.000000, 255.000000;
+cfg.color.grey =	127.500000, 127.500000, 127.500000;
+cfg.color.red =	255.000000, 0.000000, 0.000000;
+cfg.color.white =	255.000000, 255.000000, 255.000000;
+cfg.debug.do =	1;
+cfg.debug.smallWin =	1;
+cfg.debug.transpWin =	1;
+cfg.design.localizer =	'MT';
+cfg.design.motionDirections =	0.000000, 0.000000, 180.000000, 180.000000;
+cfg.design.motionType =	'translation';
+cfg.design.names{1} =	'static';
+cfg.design.names{2} =	'motion';
+cfg.design.nbEventsPerBlock =	12.000000;
+cfg.design.nbRepetitions =	12.000000;
+cfg.dot.coherence =	1.000000;
+cfg.dot.color =	255.000000, 255.000000, 255.000000;
+cfg.dot.density =	1.000000;
+cfg.dot.lifeTime =	0.400000;
+cfg.dot.proportionKilledPerFrame =	0.000000;
+cfg.dot.size =	0.200000;
+cfg.dot.speed =	15.000000;
+cfg.dot.staticReSeed =	1;
+cfg.extraColumns{1} =	'direction';
+cfg.extraColumns{2} =	'speedDegVA';
+cfg.extraColumns{3} =	'target';
+cfg.extraColumns{4} =	'event';
+cfg.extraColumns{5} =	'block';
+cfg.extraColumns{6} =	'keyName';
+cfg.extraColumns{7} =	'fixationPosition';
+cfg.extraColumns{8} =	'aperturePosition';
+cfg.eyeTracker.do =	0;
+cfg.fixation.color =	255.000000, 255.000000, 255.000000;
+cfg.fixation.colorTarget =	255.000000, 0.000000, 0.000000;
+cfg.fixation.lineWidthPix =	3.000000;
+cfg.fixation.type =	'cross';
+cfg.fixation.width =	0.250000;
+cfg.fixation.xDisplacement =	0.000000;
+cfg.fixation.yDisplacement =	0.000000;
+cfg.hideCursor =	0;
+cfg.keyboard.escapeKey =	'ESCAPE';
+cfg.keyboard.keyboard =	[];
+cfg.keyboard.responseBox =	[];
+cfg.keyboard.responseKey{1} =	'r';
+cfg.keyboard.responseKey{2} =	'g';
+cfg.keyboard.responseKey{3} =	'y';
+cfg.keyboard.responseKey{4} =	'b';
+cfg.keyboard.responseKey{5} =	'd';
+cfg.keyboard.responseKey{6} =	'n';
+cfg.keyboard.responseKey{7} =	'z';
+cfg.keyboard.responseKey{8} =	'e';
+cfg.keyboard.responseKey{9} =	't';
+cfg.mri.repetitionTime =	1.800000;
+cfg.mri.triggerKey =	't';
+cfg.mri.triggerNb =	5.000000;
+cfg.pacedByTriggers.do =	0;
+cfg.screen.monitorDistance =	95.000000;
+cfg.screen.monitorWidth =	25.000000;
+cfg.screen.resolution{1} =	[];
+cfg.screen.resolution{2} =	[];
+cfg.screen.resolution{3} =	[];
+cfg.skipSyncTests =	1.000000;
+cfg.suffix.acquisition =	'';
+cfg.target.duration =	0.100000;
+cfg.target.maxNbPerBlock =	1.000000;
+cfg.target.type =	'fixation_cross';
+cfg.task.instruction =	'1-Detect the RED fixation cross';
+cfg.task.name =	'visual localizer';
+cfg.task.taskDescription =	'';
+cfg.testingDevice =	'mri';
+cfg.text.color =	255.000000, 255.000000, 255.000000;
+cfg.text.font =	'Courier New';
+cfg.text.size =	18.000000;
+cfg.text.style =	1.000000;
+cfg.timing.IBI =	4.000000;
+cfg.timing.ISI =	0.100000;
+cfg.timing.endDelay =	5.000000;
+cfg.timing.eventDuration =	0.300000;
+cfg.timing.onsetDelay =	5.000000;
+cfg.verbose =	1.000000;
+```
+
+##
+
+Type help `expDesign` to get information on how to tweak your experiment design.
+
+## Let the scanner pace the experiment
+
+<!-- TODO check that this is still valid -->
+
+Set `cfg.pacedByTriggers.do` to `true` and you can then set all the details in
+this `if` block
+
+```matlab
+% Time is here in terms of `repetition time (TR)` (i.e. MRI volumes)
+if cfg.pacedByTriggers.do
+
+  cfg.pacedByTriggers.quietMode = true;
+  cfg.pacedByTriggers.nbTriggers = 1;
+
+  cfg.timing.eventDuration = cfg.mri.repetitionTime / 2 - 0.04; % second
+
+  % Time between blocs in secs
+  cfg.timing.IBI = 0;
+  % Time between events in secs
+  cfg.timing.ISI = 0;
+  % Number of seconds before the motion stimuli are presented
+  cfg.timing.onsetDelay = 0;
+  % Number of seconds after the end all the stimuli before ending the run
+  cfg.timing.endDelay = 2;
+
+end
+```