Merge pull request #97 from marcobarilari/marco_streamline-expDesing-MtMST

Fix #87 - make `expDesign` computing the design of both MTplus and MT/MST loc

Author: marcobarilari

.github/workflows/moxunit.yml

@@ -4,24 +4,32 @@ on:
   push:
     branches:
       - master
+      - dev
   pull_request:
     branches: ['*']
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
+
     - uses: actions/checkout@v2
       with:
         submodules: true
         fetch-depth: 1
+
     - name: MOxUnit Action
-      uses: joergbrech/moxunit-action@v1.1
+      uses: joergbrech/moxunit-action@v1.2.0
       with:
         tests: tests
         src: subfun
+        # add CPP_PTB to the path but don't include it the coverage
+        ext: lib/CPP_PTB/src
+        # Octave packages needed
+        pkg: statistics
         with_coverage: true
         cover_xml_file: coverage.xml
+
     - name: Code coverage
       uses: codecov/codecov-action@v1
       with:

README.md

@@ -124,9 +124,9 @@ Wrapper function that present the dot stimulation (static or motion) per event.
 
 > 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(MtMst)
+### subfun/design/expDesign
 
-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).
+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 display a visual example of the possible design. See `getMockConfig` to set up the mock configuration.
 

setParameters.m

@@ -48,15 +48,16 @@
     % - MST: radial motion centered in a circle aperture that is on the opposite
     % 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';
+    cfg.design.localizer = 'MT_MST';
 
     cfg.design.motionType = 'translation';
     cfg.design.motionDirections = [0 0 180 180];
     cfg.design.names = {'static'; 'motion'};
 
-    % if you have static and motion and `nbRepetions` = 4, this will return 8 blocks (n blocks per
-    % hemifield in case of MT/MST localizer)
+    % if you have static and motion and `nbRepetions` = 4, this will return 8 blocks (for MT/MST
+    % localizer && 2 hemifield it is 8 blocks per hemifield), i.e. how many times each condition
+    % will be repeated
     cfg.design.nbRepetitions = 12;
     cfg.design.nbEventsPerBlock = 12;
 
@@ -221,17 +222,14 @@
 
         cfg.design.motionType = 'radial';
         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.names = {'motion'};
+        %         cfg.design.names = {'static'; 'motion'};
+        cfg.design.fixationPosition = {'fixation_left'};
+        %         cfg.design.fixationPosition = {'fixation_right'; 'fixation_left'};
         cfg.design.xDisplacementFixation = 7;
         cfg.design.xDisplacementAperture = 3;
 
-        % here we double the repetions (2 hemifields)
-        cfg.design.nbRepetitions = cfg.design.nbRepetitions * length(cfg.design.fixationPosition);
-
-        % inward&outward are presented as separated event
+        % inward and outward are presented as separated event
         cfg.design.nbEventsPerBlock = cfg.design.nbEventsPerBlock * 2;
 
         cfg.timing.IBI = 4;

subfun/design/diplayDesign.m

@@ -1,4 +1,7 @@
 function diplayDesign(cfg, displayFigs)
+    %
+    % diplayDesign(cfg, displayFigs)
+    %
     %
     % (C) Copyright 2020 CPP visual motion localizer developpers
 
@@ -22,7 +25,19 @@ function diplayDesign(cfg, displayFigs)
         myColorMap = lines(5);
         colormap(myColorMap);
 
-        title('Block (static and motion) & Events (motion direction)');
+        if  strcmp(cfg.design.localizer, 'MT') || ...
+                strcmp(cfg.design.localizer, 'MT_MST') && ...
+                length(cfg.design.names) == 2
+
+            title(['Blocks (rows, static-odd and motion-even) & ' ...
+                   'Events (columns, colors: motion direction)']);
+
+        else
+
+            title(['Block (rows, only motion blocks) & ' ...
+                   'Events (columns, colors: motion direction)']);
+
+        end
 
         % Shows the fixation targets design in each event (1 or 0)
         fixationTargets = cfg.design.fixationTargets;
@@ -39,9 +54,11 @@ function diplayDesign(cfg, displayFigs)
 
         subplot(3, 1, 3);
         hist(itargetPosition);
-        labelAxesFreq();
+        labelAxesFreqTarget();
         title('Fixation Targets position distribution');
 
+        % Show the direction presented distribution per event position
+        % in the blocks across the experiment
         figure(2);
 
         [~, motionDirections] = getDirectionBaseVectors(cfg);
@@ -54,11 +71,13 @@ function diplayDesign(cfg, displayFigs)
             subplot(2, 2, iMotion);
             hist(position);
             scaleAxes();
-            labelAxesFreq();
+            labelAxesFreqDirection();
             title(num2str(motionDirections(iMotion)));
 
         end
 
+        suptitle('Distribution of events for each direction');
+
     end
 
 end
@@ -69,12 +88,18 @@ function labelAxesBlock()
     xlabel('Events', 'Fontsize', 8);
 end
 
-function labelAxesFreq()
+function labelAxesFreqTarget()
     % an old viking saying because they really cared about their axes
     ylabel('Number of targets', 'Fontsize', 8);
     xlabel('Events', 'Fontsize', 8);
 end
 
+function labelAxesFreqDirection()
+    % an old viking saying because they really cared about their axes
+    ylabel('Number of directions', 'Fontsize', 8);
+    xlabel('Events', 'Fontsize', 8);
+end
+
 function scaleAxes()
     xlim([1 12]);
     ylim([0 5]);

subfun/design/expDesign.m

@@ -1,21 +1,23 @@
-function [cfg] = expDesign(cfg, displayFigs)
+function [cfg] = expDesign(cfg)
     %
     % Creates the sequence of blocks and the events in them
     %
-    % The conditions are consecutive static and motion blocks. It gives better results than
-    % randomised.
+    % The conditions are consecutive static and motion blocks.
+    % It gives better results than randomised.
     %
     % It can be run as a stand alone without inputs and display 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 ]
+    % (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``
     %
@@ -40,15 +42,19 @@
     % Output:
     % - 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.
+    % - cfg.design.directions: array (nbBlocks, nbEventsPerBlock) with the direction
+    %                          to present in a given event of a block.
+    % - cfg.design.blockFixationPosition: [MT_MST] array (nbBlocks, 1)
+    %                                     with the position in the hemifiled
+    %                                     where to show the fixation cross
     %  - 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
+    % - cfg.design.fixationTargets: array (nbBlocks, numEventsPerBlock) showing
+    %                               for each event if it should be accompanied by a target
+    %
     %
     % (C) Copyright 2020 CPP visual motion localizer developpers
 
@@ -59,9 +65,12 @@
 
     if nargin < 1 || isempty(cfg)
 
+        % make sure we got access to all the required functions and inputs
+        run('../../initEnv.m');
+
         % ``true`` for MT+ translational localizer
         % ``false`` for MT/MST localizer
-        isMT = true;
+        isMT = false;
 
         % Get mock inputs to run this function as a stand alone and get a flavour of how the design
         % looks like given certain inputs. Open this function to set different inputs.
@@ -85,6 +94,9 @@
     % Compute a matrix [nbBlocks x nbEventsPerBlock]
     cfg.design.directions = setDirections(cfg);
 
+    % Compute the fixation position (left/right hemifield) for MT/MST
+    cfg.design.blockFixationPosition = setFixationPosition(cfg);
+
     %% Task(s) design
 
     % Compute a matrix [nbBlocks x nbEventsPerBlock] with

subfun/design/expDesignMtMst.m

@@ -1,9 +1,21 @@
 function [nbRepetitions, nbEventsPerBlock, maxNbPerBlock, nbBlocks] = getDesignInput(cfg)
+    %
+    % [nbRepetitions, nbEventsPerBlock, maxNbPerBlock, nbBlocks] = getDesignInput(cfg)
+    %
     %
     % (C) Copyright 2020 CPP visual motion localizer developpers
 
     nbRepetitions = cfg.design.nbRepetitions;
+
+    if strcmpi(cfg.design.localizer, 'MT_MST')
+
+        % here we double the nb of repetitions (2 hemifields) if needed
+        nbRepetitions = nbRepetitions * length(cfg.design.fixationPosition);
+
+    end
+
     nbEventsPerBlock = cfg.design.nbEventsPerBlock;
     maxNbPerBlock = cfg.target.maxNbPerBlock;
     nbBlocks = length(cfg.design.names) * nbRepetitions;
+
 end

subfun/design/getDesignInput.m

@@ -1,4 +1,7 @@
 function [directionsCondition1, directionsCondition2] = getDirectionBaseVectors(cfg)
+    %
+    % [directionsCondition1, directionsCondition2] = getDirectionBaseVectors(cfg)
+    %
     %
     % (C) Copyright 2020 CPP visual motion localizer developpers