Merge remote-tracking branch 'cpp-lln-lab/master'

Author: CerenB

README.md

@@ -35,44 +35,74 @@ We use the [MISS_HIT linter](https://florianschanda.github.io/miss_hit/style_che
 
 ## How to install
 
-### Use the matlab package manager
+### Download with git
+
+``` bash
+cd fullpath_to_directory_where_to_install
+# use git to download the code
+git clone https://github.com/cpp-lln-lab/CPP_PTB.git
+# move into the folder you have just created
+cd CPP_PTB
+# add the src folder to the matlab path and save the path
+matlab -nojvm -nosplash -r "addpath(fullfile(pwd)); savepath ();"
+```
+
+Then get the latest commit:
+```bash
+# from the directory where you downloaded the code
+git pull origin master
+```
 
-This repository can be added as a dependencies by listing it in a [mpm-requirements.txt file](.mpm-requirements.txt)
-as follows:
+To work with a specific version, create a branch at a specific version tag number
+```bash
+# creating and checking out a branch that will be calle version1 at the version tag v0.0.1
+git checkout -b version1 v0.0.1
+```
 
-    CPP_PTB -u https://github.com/cpp-lln-lab/CPP_PTB.git
+### Add as a submodule
 
-You can then use the [matlab package manager](https://github.com/mobeets/mpm), to simply download the appropriate version of those dependencies and add them to your path by running a `getDependencies` function like the one below where you just need to replace `YOUR_EXPERIMENT_NAME` by the name of your experiment.
+Add it as a submodule in the repo you are working on.
 
-```matlab
-  function getDependencies(action)
-  % Will install on your computer the matlab dependencies specified in the mpm-requirements.txt
-  %  and add them to the matlab path. The path is never saved so you need to run getDependencies() when
-  %  you start matlab.
-  %
-  % getDependencies('update') will force the update and overwrite previous version of the dependencies.
-  %
-  % getDependencies() If you only already have the appropriate version but just want to add them to the matlab path.
-
-  experimentName = YOUR_EXPERIMENT_NAME;
-
-  if nargin<1
-      action = '';
-  end
-
-  switch action
-      case 'update'
-          % install dependencies
-          mpm install -i mpm-requirements.txt -f -c YOUR_EXPERIMENT_NAME
-  end
-
-  % adds them to the path
-  mpm_folder = fileparts(which('mpm'));
-  addpath(genpath(fullfile(mpm_folder, 'mpm-packages', 'mpm-collections', experimentName)));
-
-  end
+``` bash
+cd fullpath_to_directory_where_to_install
+# use git to download the code
+git submodule add https://github.com/cpp-lln-lab/CPP_PTB.git
+# move into the folder you have just created
+cd CPP_PTB
+# add the src folder to the matlab path and save the path
+matlab -nojvm -nosplash -r "addpath(fullfile(pwd))"
 ```
 
+To get the latest commit you then need to update the submodule with the information 
+on its remote repository and then merge those locally.
+```bash
+git submodule update --remote --merge
+```
+
+Remember that updates to submodules need to be commited as well. 
+
+**TO DO**
+<!-- Submodules
+pros: in principle, downloading the experiment you have the whole package plus the benefit to stay updated and use version control of this dependency. Can probably handle a use case in which one uses different version on different projects (e.g. older and newer projects).
+cons: for pro users and not super clear how to use it at the moment. -->
+
+### Direct download
+
+Download the code. Unzip. And add to the matlab path.
+
+Pick a specific version:
+
+https://github.com/cpp-lln-lab/CPP_PTB/releases
+
+Or take the latest commit (NOT RECOMMENDED):
+
+https://github.com/cpp-lln-lab/CPP_PTB/archive/master.zip
+
+**TO DO**
+<!-- Download a specific version and c/p it in a subfun folder
+pros: the easiest solution to share the code and 'installing' it on the stimulation computer (usually not the one used to develop the code).
+cons: extreme solution useful only at the very latest stage (i.e. one minute before acquiring your data); prone to be customized/modified (is it what we want?) -->
+
 ## Setting up keyboards
 
 To select a specific keyboard to be used by the experimenter or the participant, you need to know
@@ -98,9 +128,66 @@ press the keys necessary to start or abort the experiment.
 
 Using empty vectors (ie `[]`) or a negative value for those means that you will let PTB find and use the default device.
 
-## Structure and function details
+## Structure
+
+```matlab
+
+cfg.testingDevice = 'pc';
+
+% cfg.color
+cfg.keyboard.keyboard = [];
+cfg.keyboard.responseBox = [];
+cfg.keyboard.responseKey = {};
+cfg.keyboard.escapeKey = 'ESCAPE';
+
+% cfg.debug
+cfg.debug.do = true;
+cfg.debug.transpWin = true;
+cfg.debug.smallWin = true;
+
+% cfg.text
+cfg.text.font 
+cfg.text.size 
+cfg.text.style 
+
+% cfg.color
+cfg.color.background
+
+% cfg.screen
+cfg.screen.monitorWidth
+cfg.screen.monitorDistance
+cfg.screen.idx
+cfg.screen.win 
+cfg.screen.winRect 
+cfg.screen.winWidth 
+cfg.screen.winHeight 
+cfg.screen.center 
+cfg.screen.FOV
+cfg.screen.ppd 
+cfg.screen.ifi 
+cfg.screen.monRefresh 
+
+% cfg.audio
+cfg.audio.do
+cfg.audio.pahandle
+cfg.audio.devIdx
+cfg.audio.playbackMode
+cfg.audio.requestedLatency
+cfg.audio.fs
+cfg.audio.channels
+cfg.audio.initVolume
+cfg.audio.pushSize  
+cfg.audio.requestOffsetTime 
+cfg.audio.reqsSampleOffset
+
+% cfg.mri
+cfg.mri.repetitionTime
+cfg.mri.triggerNb
+cfg.mri.triggerKey
+```
+
+## function details
 
-<!-- ### setParameters -->
 
 ### initPTB
 

apertureTexture.m

@@ -0,0 +1,55 @@
+function cfg = apertureTexture(action, cfg, thisEvent)
+
+    transparent = [0 0 0 0];
+
+    switch action
+
+        case 'init'
+
+            % we take the screen height as maximum aperture width if not
+            % specified.
+            if ~isfield(cfg.aperture, 'width') || isempty(cfg.aperture.width)
+                cfg.aperture.width = cfg.screen.winRect(4) / cfg.screen.ppd;
+            end
+            cfg.aperture = degToPix('width', cfg.aperture, cfg);
+
+            cfg.aperture.texture = Screen('MakeTexture', cfg.screen.win, ...
+                cfg.color.background(1) * ones(cfg.screen.winRect([4 3])));
+
+        case 'make'
+
+            switch cfg.aperture.type
+
+                case 'none'
+
+                    Screen('Fillrect', cfg.aperture.texture, transparent);
+
+                case 'circle'
+
+                    diameter = cfg.aperture.widthPix;
+
+                    xPos = cfg.screen.center(1);
+                    yPos = cfg.screen.center(2);
+                    if isfield(cfg.aperture, 'xPosPix')
+                        xPos = cfg.screen.center(1) + cfg.aperture.xPosPix;
+                    end
+                    if isfield(cfg.aperture, 'yPosPix')
+                        yPos = cfg.screen.center(2) + cfg.aperture.yPosPix;
+                    end
+
+                    Screen('FillOval', cfg.aperture.texture, transparent, ...
+                        CenterRectOnPoint([0 0 repmat(diameter, 1, 2)], ...
+                        xPos, yPos));
+
+            end
+
+        case 'draw'
+
+            Screen('DrawTexture', cfg.screen.win, cfg.aperture.texture);
+
+            % Screen('DrawTexture', cfg.screen.win, apertureTexture, ...
+            % cfg.screen.winRect, cfg.screen.winRect, current.apertureAngle - 90);
+
+    end
+
+end

checkAbort.m

@@ -1,4 +1,6 @@
 function checkAbort(cfg, deviceNumber)
+    % checkAbort(cfg, deviceNumber)
+    %
     % Check for experiment abortion from operator
     % When no deviceNumber is set then it will check the default device
     % When an abort key s detected this will set a global variable and throw a

cleanUp.m

@@ -1,4 +1,6 @@
-function cleanUp
+function cleanUp()
+    % cleanUp()
+    %
     % A wrapper function to close all windows, ports, show mouse cursor, close keyboard queues
     % and give access back to the keyboards.
 

collectAndSaveResponses.m

@@ -1,17 +1,17 @@
-function responseEvents = collectAndSaveResponses(cfg, expParameters, logFile, experimentStart)
-    
+function responseEvents = collectAndSaveResponses(cfg, logFile, experimentStart)
+
     responseEvents = getResponse('check', cfg.keyboard.responseBox, cfg);
-    
+
     if isfield(responseEvents(1), 'onset') && ~isempty(responseEvents(1).onset)
-        
+
         for iResp = 1:size(responseEvents, 1)
             responseEvents(iResp).onset = ...
                 responseEvents(iResp).onset - experimentStart;
         end
-        
+
         responseEvents.fileID = logFile.fileID;
         responseEvents.extraColumns = logFile.extraColumns;
-        saveEventsFile('save', expParameters, responseEvents);
-        
+        saveEventsFile('save', cfg, responseEvents);
+
     end
-end
+end

computeFOV.m

@@ -0,0 +1,17 @@
+function FOV = computeFOV(cfg)
+    % FOV = computeFOV(cfg)
+    %
+    % computes the number of degrees of visual angle in the whole field of view
+    %
+    % δ = 2 arctan ( d / 2D )
+    %
+    %  δ is the angular diameter, and d is the actual diameter of the object,
+    %  and D is the distance to the object.
+    %  The result obtained is in radians.
+    %
+
+    FOV =  ...
+        180 / pi * ...
+        2 * atan(cfg.screen.monitorWidth / (2 * cfg.screen.monitorDistance));
+
+end

decompMotion.m

@@ -0,0 +1,5 @@
+function [horVector, vertVector] = decompMotion(angleMotion)
+    % decompose angle of start motion into horizontal and vertical vector
+    horVector = cos(pi * angleMotion / 180);
+    vertVector = -sin(pi * angleMotion / 180);
+end

degToPix.m

@@ -1,11 +1,13 @@
 function structure = degToPix(fieldName, structure, cfg)
+    % structure = degToPix(fieldName, structure, cfg)
+    %
     % For a given field value in degrees of visual angle in the structure,
     % 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.
 
     deg = getfield(structure, fieldName); %#ok<GFLD>
 
     structure = setfield(structure, [fieldName 'Pix'], ...
-        floor(cfg.ppd * deg)) ; %#ok<SFLD>
+        floor(deg * cfg.screen.ppd)) ; %#ok<SFLD>
 
 end

demos/CPP_waitForTriggerDemo.m

@@ -2,9 +2,9 @@
 
 cfg.testingDevice = 'mri';
 
-cfg.numTriggers = 4;
+cfg.mri.triggerNb = 4;
 
-cfg.triggerKey = 'space';
+cfg.mri.triggerKey = 'space';
 
 KbName('UnifyKeyNames');