diff --git a/docs/source/function_description.rst b/docs/source/function_description.rst index a1de908f..0fe8f7e8 100644 --- a/docs/source/function_description.rst +++ b/docs/source/function_description.rst @@ -1,5 +1,5 @@ Function description -==================== +******************** The functions of our pipeline @@ -21,20 +21,27 @@ List of functions in the ``src`` folder. ---- +Aperture +======== + List of functions in the ``src/aperture`` folder. +(to add saveAperture) + .. module:: src.aperture .. autofunction:: apertureTexture .. autofunction:: eccenLogSpeed .. autofunction:: getApertureName -.. autofunction:: saveAperture .. autofunction:: saveApertures .. autofunction:: smoothOval .. autofunction:: smoothRect ---- +Dot +=== + List of functions in the ``src/dot`` folder. .. module:: src.dot @@ -53,6 +60,9 @@ List of functions in the ``src/dot`` folder. ---- +Errors +====== + List of functions in the ``src/errors`` folder. .. module:: src.errors @@ -64,6 +74,9 @@ List of functions in the ``src/errors`` folder. ---- +Fixation +======== + List of functions in the ``src/fixation`` folder. .. module:: src.fixation @@ -73,6 +86,9 @@ List of functions in the ``src/fixation`` folder. ---- +Keyboard +======== + List of functions in the ``src/keyboard`` folder. .. module:: src.keyboard @@ -86,6 +102,9 @@ List of functions in the ``src/keyboard`` folder. ---- +Randomization +============= + List of functions in the ``src/randomization`` folder. .. module:: src.randomization @@ -96,6 +115,9 @@ List of functions in the ``src/randomization`` folder. ---- +Screen +====== + List of functions in the ``src/screen`` folder. .. module:: src.screen @@ -105,6 +127,9 @@ List of functions in the ``src/screen`` folder. ---- +Utilities +========= + List of functions in the ``src/utils`` folder. (to add makeGif) diff --git a/src/dot/initDots.m b/src/dot/initDots.m index 32175b50..65a6c243 100644 --- a/src/dot/initDots.m +++ b/src/dot/initDots.m @@ -20,8 +20,7 @@ % dots.isSignal : signal dots (1) and those are noise dots (0) % dots.directionAllDots % dots.lifeTime : in frames - % dots.speeds : [ndots, 2] ; horizontal and vertical speed ; in pixels per - % frame + % dots.speeds : [ndots, 2] ; horizontal and vertical speed ; in pixels per frame % dots.speedPixPerFrame dots.direction = thisEvent.direction(1); diff --git a/src/eyeTracker.m b/src/eyeTracker.m index 7378bd3a..3e27016e 100755 --- a/src/eyeTracker.m +++ b/src/eyeTracker.m @@ -1,29 +1,37 @@ % (C) Copyright 2020 CPP_PTB developers function [el, cfg] = eyeTracker(input, cfg, varargin) - % [el] = eyeTracker(input, cfg, varargin) % % Wrapper function that deals with all the necessery actions to implement - % Eye Tracker recording with eyelink. + % Eye Tracker recording with eyelink. % - % INPUT + % USAGE: % - % - action: Defines what we want the function to do - % - Calibration: to initialize EyeLink and run calibration - % -- 'default calibration' (default) will run a calibration with 6 points - % -- 'custom calibration' (cfg.eyeTracker.defaultCalibration = 'false') will run a - % calibration with 6 points but the experimenter can choose their position on the screen - % - StartRecording: to start eye movements recording - % - Message: will add a tag (e.g. 'Block_n1') in the ET output file, the tag is a string and it - % is input from `varargin` - % - StopRecordings: to stop eye movements recornding - % - Shutdown: to save the `.edf` file with BIDS compliant name, from cpp-lln-lab/CPP_BIDS, in - % the output folder and shut the connection between the stimulation computer and the EyeLink - % computer + % function [el, cfg] = eyeTracker(input, cfg, [message]) % - % OUTPUT + % :param input: Defines what we want the function to do + % :type input: string + % :param cfg: structure that stores any info regarding the experiment + % :type cfg: struct + % :param message: optional argument to pass in when you want to tag the output in a specific + % moment of the experiment (for example ``Experiment-start``) + % :type message: string % - % `el` is a structure where are stored EyeLink setup variables + % :returns: - :el: (struct) stores info related to the Eye Tracker + % - :cfg: (struct) + % + % - ``Calibration`` to initialize EyeLink and run calibration + % - ``default calibration`` (default) will run a calibration with 6 points + % - ``custom calibration`` (``cfg.eyeTracker.defaultCalibration = 'false'``) will run + % a calibration with 6 points but the experimenter can choose their position + % on the screen + % - ``StartRecording``: to start eye movements recording + % - ``Message``: will add a tag (e.g. ``Block_n1``) in the ET output file, the tag is a + % string and it is input from `varargin` + % - ``StopRecordings``: to stop eye movements recording + % - ``Shutdown``: to save the ``.edf`` file with BIDS compliant name, from + % cpp-lln-lab/CPP_BIDS, in the output folder and shut the connection between the + % stimulation computer and the EyeLink computer if ~cfg.eyeTracker.do diff --git a/src/keyboard/checkAbort.m b/src/keyboard/checkAbort.m index ed2e0dfb..c1201ae3 100644 --- a/src/keyboard/checkAbort.m +++ b/src/keyboard/checkAbort.m @@ -1,25 +1,37 @@ % (C) Copyright 2020 CPP_PTB developers 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 + % Check for experiment abortion from operator. When no deviceNumber is set then it will check + % the default device. When an abort key is detected this will set a global variable and throw a % specific error that can then be catched. % - % Maint script - % try - % % Your awesome experiment - % catch ME % when something goes wrong - % switch ME.identifier + % USAGE:: + % + % checkAbort(cfg, deviceNumber) + % + % Examples:: + % + % try + % + % % Your awesome experiment + % + % catch ME % when something goes wrong + % + % switch ME.identifier + % % case 'checkAbort:abortRequested' - % % stuff to do when an abort is requested (save data...) + % + % % stuff to do when an abort is requested (save data...) + % % otherwise - % % stuff to do otherwise - % rethrow(ME) % display the error - % end - % end + % + % % stuff to do otherwise + % rethrow(ME) % display the error + % + % end + % end + % if nargin < 1 || isempty(cfg) error('I need at least one input.'); diff --git a/src/keyboard/getResponse.m b/src/keyboard/getResponse.m index 11aee4e1..7e482e2d 100644 --- a/src/keyboard/getResponse.m +++ b/src/keyboard/getResponse.m @@ -1,60 +1,68 @@ % (C) Copyright 2020 CPP_PTB developers function responseEvents = getResponse(action, deviceNumber, cfg, getOnlyPress) - % responseEvents = getResponse(action, deviceNumber, cfg, getOnlyPress) % - % Wrapper function to use KbQueue + % Wrapper function to use KbQueue. The queue will be listening to key presses + % on a keyboard device: + % ``cfg.keyboard.responseBox`` or ``cfg.keyboard.keyboard`` are 2 main examples. + % When no ``deviceNumber`` is set then it will listen to the default device. + % Check the ``CPP_getResponseDemo`` for a quick script on how to use it. % - % The queue will be listening to key presses on a keyboard device: - % cfg.keyboard.responseBox or cfg.keyboard.keyboard are 2 main examples. + % USAGE:: % - % When no deviceNumber is set then it will listen to the default device. + % responseEvents = getResponse(action, deviceNumber, cfg, getOnlyPress) % - % Check the CPP_getResponseDemo for a quick script on how to use it. + % :param action: Defines what we want the function to do + % :param deviceNumber: device number of the keyboard or trigger box in MRI + % :type deviceNumber: integer + % :param cfg: + % :param getOnlyPress: if set to true the function will only return the key presses and will not + % return when the keys were released (default=true). See the section on + % `Returns` below for more info % + % :returns: % - % INPUT + % - :responseEvents: returns all the keypresses and return them + % as a structure with field names that make it easier + % to save the output of in a BIDS format % - % - action: Defines what we want the function to do - % - init: to initialise the queue - % - start: to start listening to keypresses - % - check: checks all the key presses events since 'start', or since last - % 'check' or 'flush' (whichever was the most recent) - % -- can check for demand to abort if the escapeKey is listed in the - % Keys of interest. - % -- can only check for demands to abort when getResponse('check') is called: - % so there will be a delay between the key press and the experiment stopping - % -- abort errors send specific signals that allow the catch to get - % them and allows us to "close" nicely - % - flush: empties the queue of events in case you want to restart from a clean - % queue - % - stop: stops listening to key presses + % - ``responseEvents.onset`` this is an absolute value and you should substract + % the "experiment start time" to get a value relative to when the experiment was started. % - % - getOnlyPress: if set to true the function will only return the key presses and - % will not return when the keys were released (default=true) - % See the section on OUTPUT below for more info + % - ``responseEvents.trial_type = response`` % + % - ``responseEvents.duration = 0`` % + % - ``responseEvents.keyName`` the name of the key pressed % - % OUTPUT + % - ``responseEvents(iEvent,1).pressed`` if % - % responseEvents: returns all the keypresses and return them as a structure - % with field names that make it easier to save the output of in a BIDS - % format + % - ``pressed == 1`` --> the key was pressed + % - ``pressed == 0`` --> the key was released % - % responseEvents.onset : this is an absolute value and you should - % substract the "experiment start time" to get a value relative to when the - % experiment was started. + % --- % - % responseEvents.trial_type = 'response'; + % ``action`` options: % - % responseEvents.duration = 0; + % - ``init`` to initialise the queue % - % responseEvents.keyName : the name of the key pressed + % - ``start`` to start listening to keypresses + % + % - ``check`` checks all the key presses events since 'start', or since last 'check' + % or 'flush' (whichever was the most recent) + % + % - can check for demand to abort if the ``escapeKey`` is listed in the Keys of interest + % + % - can only check for demands to abort when ``getResponse('check')`` is called + % so there will be a delay between the key press and the experiment stopping + % + % - abort errors send specific signals that allow the catch to get them and allows us + % to "close" nicely + % + % - ``flush`` empties the queue of events in case you want to restart from a clean queue + % + % - ``stop`` stops listening to key presses % - % responseEvents(iEvent,1).pressed : if - % pressed == 1 --> the key was pressed - % pressed == 0 --> the key was released if nargin < 2 || isempty(deviceNumber) deviceNumber = -1; diff --git a/src/readAndFilterLogfile.m b/src/readAndFilterLogfile.m index 9049b444..00b54ad7 100644 --- a/src/readAndFilterLogfile.m +++ b/src/readAndFilterLogfile.m @@ -1,27 +1,30 @@ % (C) Copyright 2020 CPP_PTB developers -function outputFiltered = readAndFilterLogfile(columnName, filterBy, varargin) - % outputFiltered = readOutputFilter(filterHeader, filterContent, varargin) +function [outputFiltered] = readAndFilterLogfile(columnName, filterBy, varargin) % - % It will display in the command window the content of the `output.tsv' filtered by one element - % of a target column. + % It will display in the command window the content of the `output.tsv` filtered + % by one element of a target column. Dependecies: bids_matlab (from CPP_BIDS) % - % DEPENDENCIES: - % - bids_matlab (from CPP_BIDS) + % USAGE: % - % INPUT: + % [outputFiltered] = readOutputFilter(filterHeader, filterContent, varargin) % - % - columnName: string, the header of the column where the content of insterest is stored - % (e.g., for 'trigger' will be 'trial type') - % - filterBy: string, the content of the column you want to filter out. It can take just - % part of the content name (e.g., you want to display the triggers and you have - % 'trigger_motion' and 'trigger_static', 'trigger' as input will do) - % - varargin: either cfg (to display the last run output) or the file path as string + % :param columnName: the header of the column where the content of insterest is stored + % (e.g., for 'trigger' will be 'trial type') + % :type columnName: string + % :param filterBy: the content of the column you want to filter out. It can take just + % part of the content name (for example, you want to display the triggers and + % you have ``trigger_motion`` and ``trigger_static``, ``trigger`` as input + % will do) + % :type filterBy: string + % :param varargin: either ``cfg`` (to display the last run output) or the file path as string + % + % :returns: + % + % - :outputFiltered: dataset with only the specified content to see it in the + % command window use display(outputFiltered) % - % OUTPUT: % - % - outputFiltered: dataset with only the specified content, to see it in the command window - % use display(outputFiltered) % Checke if input is cfg or the file path if ischar(varargin{1}) diff --git a/src/templates/templateFunction.m b/src/templates/templateFunction.m new file mode 100644 index 00000000..e71713b0 --- /dev/null +++ b/src/templates/templateFunction.m @@ -0,0 +1,29 @@ +% (C) Copyright 2020 CPP_PTB developers + +function [argout1, argout2] = templateFunction(argin1, argin2, argin3) + % + % Short description of what the function does goes here. + % + % USAGE:: + % + % [argout1, argout2] = templateFunction(argin1, [argin2 == default,] [argin3]) + % + % :param argin1: (dimension) obligatory argument. Lorem ipsum dolor sit amet, + % consectetur adipiscing elit. Ut congue nec est ac lacinia. + % :type argin1: type + % :param argin2: optional argument and its default value. And some of the + % options can be shown in litteral like ``this`` or ``that``. + % :type argin2: string + % :param argin3: (dimension) optional argument + % + % :returns: - :argout1: (type) (dimension) + % - :argout2: (type) (dimension) + % + % .. todo: + % + % - item 1 + % - item 2 + + % The code goes below + +end diff --git a/src/templates/templateFunctionExample.m b/src/templates/templateFunctionExample.m new file mode 100644 index 00000000..99670d10 --- /dev/null +++ b/src/templates/templateFunctionExample.m @@ -0,0 +1,42 @@ +% (C) Copyright 2020 CPP_PTB developers + +function templateFunctionExample() + % This function illustrates a documentation test defined for MOdox. + % Other than that it does absolutely nothinghort description of what + % the function does goes here. + % + % Examples: + % a=2; + % disp(a) + % % Expected output is prefixed by '%||' as in the following line: + % %|| 2 + % % + % % The test continues because no interruption through whitespace, + % % as the previous line used a '%' comment character; + % % thus the 'a' variable is still in the namespace and can be + % % accessed. + % b=3+a; + % disp(a+[3 4]) + % %|| [5 6] + % + % % A new test starts here because the previous line was white-space + % % only. Thus the 'a' and 'b' variables are not present here anymore. + % % The following expression raises an error because the 'b' variable + % % is not defined (and does not carry over from the previous test). + % % Because the expected output indicates an error as well, + % % the test passes + % disp(b) + % %|| error('Some error') + % + % % A set of expressions is ignored if there is no expected output + % % (that is, no lines starting with '%||'). + % % Thus, the following expression is not part of any test, + % % and therefore does not raise an error. + % error('this is never executed) + % + % + % % tests end here because test indentation has ended + + % The code goes below + +end diff --git a/src/templates/templateFunctionNumpy.m b/src/templates/templateFunctionNumpy.m new file mode 100644 index 00000000..a5974bf0 --- /dev/null +++ b/src/templates/templateFunctionNumpy.m @@ -0,0 +1,21 @@ +% (C) Copyright 2020 CPP_PTB developers + +function [argout] = templateFunctionNumpy(argin1, argin2, argin3) + % + % Short description of what the function does goes here. + % + % y = templateFunction(argin1, argin2, argin3) + % + % Parameters: + % argin1: The first input value + % + % argin2: The second input value + % + % argin3: The third input value + % + % Returns: + % The input value multiplied by two + + % The code goes below + +end diff --git a/src/utils/degToPix.m b/src/utils/degToPix.m index a2a1c09e..b694ea48 100644 --- a/src/utils/degToPix.m +++ b/src/utils/degToPix.m @@ -1,23 +1,21 @@ % (C) Copyright 2020 CPP_PTB developers 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. % - % 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. + % USAGE: % + % structure = degToPix(fieldName, structure, cfg) % - % USAGE: - % ------ % fixation.width = 2; % cfg.screen.ppd = 10; % % fixation = degToPix('width', fixation, cfg); % - % Returns: - % ------- - % fixation.widthPix = 20; + % - Returns: + % fixation.widthPix = 20; % deg = getfield(structure, fieldName); %#ok diff --git a/src/utils/pixToDeg.m b/src/utils/pixToDeg.m index 728d558d..3eb29d05 100644 --- a/src/utils/pixToDeg.m +++ b/src/utils/pixToDeg.m @@ -10,14 +10,14 @@ % 'Pix' suffix removed and replaced with the 'DegVA' suffix . % % USAGE: - % ------ + % % fixation.widthPix = 20; % cfg.screen.ppd = 10; % % fixation = degToPix('widthPix', fixation, cfg); % % Returns: - % ------- + % % fixation.widthDegVA = 2; % diff --git a/src/waitForTrigger.m b/src/waitForTrigger.m index a8c8bace..6f603290 100644 --- a/src/waitForTrigger.m +++ b/src/waitForTrigger.m @@ -1,10 +1,29 @@ % (C) Copyright 2020 CPP_PTB developers -function lastTriggerTimeStamp = waitForTrigger(varargin) - % waitForTrigger(cfg, deviceNumber, quietMode, nbTriggersToWait) - % +function [lastTriggerTimeStamp] = waitForTrigger(varargin) % Counts a certain number of triggers coming from the scanner before returning. % + % USAGE: + % + % [lastTriggerTimeStamp] = waitForTrigger([cfg,] ... + % [deviceNumber,] ... + % [quietMode,] ... + % [nbTriggersToWait]) + % + % :param cfg: + % :type cfg: struct + % :param deviceNumber: device number of the keyboard or trigger box in MRI + % :type deviceNumber: integer + % :param quietMode: a boolean to make sure nothing is printed on the screen or the prompt + % :type quietMode: boolean + % :param nbTriggersToWait: number of triggers to wait + % :type nbTriggersToWait: integer + % + % :returns: + % + % - :lastTriggerTimeStamp: (optional) it can be used as experimentStart + % timestamp (``cfg.experimentStart``) + % % If you are not using the quietMode, it flips and waits for half a TR before starting to % check for the next trigger (unless this was the last trigger to wait for and in % this case it returns immediately). @@ -12,23 +31,13 @@ % Will print the count down in the command line and on the PTB window if one is % opened. % - % If the fMRI sequence RT is provided (cgf.MRI.repetitionTime) then it will wait + % If the fMRI sequence RT is provided (``cgf.MRI.repetitionTime``) then it will wait % for half a RT before starting to check for next trigger, otherwise it will % wait 500 ms. % % When no deviceNumber is set then it will check the default device: this is % probably only useful in debug as you will want to make sure you get the % triggers coming from the scanner in a real case scenario. - % - % INPUTS - % - varargin{1} = cfg - % - % - varargin{2} = deviceNumber - % - % - varargin{3} = quietMode: a boolean to make sure nothing is printed on the screen or - % the prompt - % - % - nvarargin{4} = nbTriggersToWait [cfg, nbTriggersToWait, deviceNumber, quietMode] = checkInputs(varargin);