Merge pull request #115 from cpp-lln-lab/dev

[REL] v0.5.0

.github/workflows/update_submodules.yml

@@ -30,8 +30,6 @@ name: update submodules
 on:
   push:
     branches:
-      - main
-      - master
       - dev
   schedule:
     - cron: "0 0 1 * *"

.gitignore

@@ -8,9 +8,9 @@ test_report.log
 */logfiles/*
 */*/*/logfiles/*
 *.tsv
-*.mat
 
 output
+source
 
 ## virtual env
 env/
@@ -19,6 +19,10 @@ venv/
 ## visual studio code
 .vscode
 
+# exclude temp files from tests and coverage
+test_report.log
+*coverage*
+
 ## MATLAB / OCTAVE gitignore template
 
 # From : https://github.com/github/gitignore/blob/master/Global/MATLAB.gitignore

.gitmodules

@@ -1,8 +1,8 @@
 [submodule "lib/CPP_PTB"]
 	path = lib/CPP_PTB
 	url = https://github.com/cpp-lln-lab/CPP_PTB.git
-	branch = master
+	branch = dev
 [submodule "lib/CPP_BIDS"]
 	path = lib/CPP_BIDS
 	url = https://github.com/cpp-lln-lab/CPP_BIDS.git
-	branch = master
+	branch = dev

CITATION.cff

@@ -0,0 +1,57 @@
+cff-version: 1.2.0
+
+title: "CPP localizer visual motion"
+
+version: 0.4.0dev
+
+abstract: A localizer for visual motion sensitive brain regions using RDK.
+
+message: "If you use this software, please cite it as below."
+
+repository-code: "https://github.com/cpp-lln-lab/localizer_visual_motion.git"
+
+identifiers:
+  - description: This is the collection of archived snapshots of all releases
+    type: doi
+    value: "10.5281/zenodo.4007674"
+
+contact:
+  - affiliation: "Université catholique de Louvain"
+    email: remi.gau@uclouvain.be
+    family-names: Gau
+    given-names: Rémi
+
+authors:
+  - family-names: "Gau"
+    given-names: "Rémi"
+    orcid: "https://orcid.org/0000-0002-1535-9767"
+    affiliation: "Université catholique de Louvain"
+
+  - family-names: "Barilari"
+    given-names: "Marco"
+    orcid: "https://orcid.org/0000-0002-3313-3120"
+    affiliation: "Université catholique de Louvain"
+
+  - family-names: "Battal"
+    given-names: "Ceren"
+    orcid: "https://orcid.org/0000-0002-9844-7630"
+    affiliation: "Université catholique de Louvain"
+
+  - family-names: "Rezk"
+    given-names: "Mohamed"
+    orcid: "https://orcid.org/0000-0002-1866-8645"
+    affiliation: "Université catholique de Louvain"
+
+  - family-names: "Shahzad"
+    given-names: "Iqra"
+    orcid: "https://orcid.org/0000-0002-8724-7668"
+    affiliation: "Université catholique de Louvain"
+
+license: MIT license
+
+keywords:
+  - BIDS
+  - brain imaging data structure
+  - neuroscience
+  - MATLAB
+  - Octave

Makefile

@@ -0,0 +1,22 @@
+# TODO make more general to use the local matlab version
+MATLAB = /usr/local/MATLAB/R2017a/bin/matlab
+ARG    = -nodisplay -nosplash -nodesktop
+
+.PHONY: clean manual fix_submodule
+clean: clean
+	rm -rf version.txt
+
+fix_submodule:
+	git submodule update --init --recursive && git submodule update --recursive
+
+lint:
+	mh_style --fix && mh_metric --ci && mh_lint
+
+test:
+	$(MATLAB) $(ARG) -r "runTests; exit()"
+
+version.txt: CITATION.cff
+	grep -w "^version" CITATION.cff | sed "s/version: /v/g" > version.txt
+
+validate_cff: CITATION.cff
+	cffconvert --validate

README.md

@@ -1,34 +1,28 @@
 [![](https://img.shields.io/badge/Octave-CI-blue?logo=Octave&logoColor=white)](https://github.com/cpp-lln-lab/localizer_visual_motion/actions)
 ![](https://github.com/cpp-lln-lab/localizer_visual_motion/workflows/CI/badge.svg)
 [![codecov](https://codecov.io/gh/cpp-lln-lab/localizer_visual_motion/branch/master/graph/badge.svg)](https://codecov.io/gh/cpp-lln-lab/localizer_visual_motion)
-<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 [![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-)
-<!-- ALL-CONTRIBUTORS-BADGE:END -->
 
-<!-- TOC -->
 - [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-)
-<!-- TOC -->
 
 # 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 / octave path. See the next section on how to install the submodule toolboxes.
+Make sure that the following toolboxes are installed and added to the matlab /
+octave path. See the next section on how to install the submodule toolboxes.
 
 For instructions see the following links:
 
@@ -42,129 +36,50 @@ For instructions see the following links:
 
 ## Installation
 
-The CPP_BIDS and CPP_PTB dependencies are already set up as submodule to this repository.
-You can install it all with git by doing.
+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
+Type `help checkParameters` and see the [README in docs](./docs/README.md) to
+get more information about the configuration options.
 
-#### 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.
-  - 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 ✨
 
-Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
+Thanks goes to these wonderful people
+([emoji key](https://allcontributors.org/docs/en/emoji-key)):
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
 <!-- prettier-ignore-start -->
@@ -184,4 +99,6 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+This project follows the
+[all-contributors](https://github.com/all-contributors/all-contributors)
+specification. Contributions of any kind welcome!

cfgMST.m

@@ -0,0 +1,44 @@
+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;
+
+    % in Liege is 0.6
+    % on macs is 0.3
+    cfg.timing.eventDuration = 0.6; % 0.6 seconds
+
+    %% variable FOV info
+    % in case the field of view is not properly centered or obstructed
+    %
+    % see https://github.com/cpp-lln-lab/estimate_visual_FOV.git
+    %
+    % set up configuration: ensure that the following fields are the same
+    % as when you ran the estimate_visual_FOV script
+    %
+    % cfg.testingDevice
+    % cfg.screen.monitorDistance
+    % cfg.screen.monitorWidth
+
+    % fixation cross displacement in degrees of visual angles
+    % this will also shift the whole FOV relative to the center of the screen
+    % Note: negative values will move things to the left and up.
+    cfg.fixation.xDisplacement = -3.676540;
+    cfg.fixation.yDisplacement = -0.499724;
+
+    % determines position of the fixation cross on the right / left
+    % should be a bit less than the: ( width of FOV ) / 2
+    cfg.design.xDisplacementFixation = 3;
+
+    % determines position of the dots on the left /
+    % should be a bit less than the: ( width of FOV ) / 2
+    cfg.design.xDisplacementAperture = 7;
+
+    % determines the width of the dot circle
+    cfg.aperture.width = 7;
+
+end