Merge pull request #51 from Remi-Gau/remi_constrast-specification

[WIP] constrast specification + uni and multivaraite issues + remove dummies

Author: Remi-Gau

.gitignore

@@ -3,3 +3,5 @@
 *.asv
 *.m~
 *.nii
+
+opt.mat

List_of_Contrast.m

@@ -49,6 +49,8 @@ This set of function will read and unzip the data from a [BIDS data set](https:/
 
 This has to be run for each task independently. All parameters should preferably be changed in the `getOptions.m` file.
 
+It can also prepare the data to run an MVPA analysis by running a GLM for each subject on non-normalized images and get one beta image for each condition to be used in the MVPA.
+
 The core functions are in the sub-function folder `subfun`
 
 ## Assumption
@@ -60,6 +62,9 @@ At the moment this pipeline makes some assumptions:
 
 ## Setting up
 
+### getOptions
+
+
 All the details specific to your analysis should be set in the `getOptions.m`.
 
 Set the group of subjects to analyze.
@@ -97,6 +102,58 @@ The directory where your files are located on your computer: make sure you have
 
 Some more SPM options can be set in the `spm_my_defaults.m`.
 
+### model JSON files
+This files allow you to specify which contrasts to run and follow the BIDS statistical model extension and as implement by [fitlins](https://fitlins.readthedocs.io/en/latest/model.html)
+
+The model json file that describes:
+-   out to prepare the regressors for the GLM: `Transformation`
+-   the design matrix: `X`
+-   the contrasts to compute: `contrasts`
+
+It also allows to specify those for different levels of the analysis:
+-   run
+-   session
+-   subject
+-   dataset
+
+An example of json file could look something like that.
+
+```json
+{
+  "Name": "Basic",
+  "Description": "",
+  "Input": {
+    "task": "motionloc"
+  },
+  "Steps": [
+    {
+      "Level": "subject",
+      "AutoContrasts": ["stim_type.motion", "stim_type.static"],
+      "Contrasts": [
+        {
+          "Name": "motion_vs_static",
+          "ConditionList": [
+            "stim_type.motion",
+            "stim_type.static"
+          ],
+          "weights": [1, -1],
+          "type": "t"
+        }
+      ]
+    },
+    {
+      "Level": "dataset",
+      "AutoContrasts": ["stim_type.motion", "stim_type.static", "motion_vs_static"]
+    }
+  ]
+}
+```
+
+In brief this means:
+-   at the subject level automatically compute the t contrast against baseline for the condition `motion`and `static` and compute the t-contrats for motion VS static with these given weights.
+-   at the level of the data set (so RFX) do the t contrast of the `motion`, `static`, `motion VS static`.
+
+
 ## Order of the analysis
 
 1.  __Remove Dummy Scans__:

README.md

@@ -1,3 +1,6 @@
+clear 
+clc
+
 %% Run batches
 opt = getOption();
 
@@ -7,18 +10,33 @@
 % we add all the subfunctions that are in the sub directories
 addpath(genpath(WD))
 
-% In case some toolboxes need to be added the matlab path, specify and uncomment 
+% In case some toolboxes need to be added the matlab path, specify and uncomment
 % in the lines below
 % toolbox_path = '';
 % addpath(fullfile(toolbox_path)
 
+checkDependencies();
+
+% copy raw folder into derivatives folder
+BIDS_copyRawFolder(opt, 1)
+
+% preprocessing
+BIDS_STC(opt);
+BIDS_SpatialPrepro(opt);
+BIDS_Smoothing(6, opt);
+
+% subject level Univariate
+BIDS_FFX(1, 6, opt);
+BIDS_FFX(2, 6, opt);
+
+% group level univariate
+BIDS_RFX(1, 6, 6)
+BIDS_RFX(2, 6, 6)
+
+% subject level multivariate
+isMVPA=1;
+BIDS_FFX(1, 6, opt, isMVPA);
+BIDS_FFX(2, 6, opt, isMVPA);
+make4Dmaps(6,opt)
+
 
-%cd(WD); checkDependencies();
-%cd(WD); BIDS_rmDummies(opt);
-%cd(WD); BIDS_STC(opt);
-%cd(WD); BIDS_SpatialPrepro(opt);
-%cd(WD); BIDS_Smoothing(6, opt);
-%cd(WD); BIDS_FFX(1, 6, opt);
-%cd(WD); BIDS_FFX(2, 6, opt);
-%cd(WD); BIDS_RFX(1, 6, 6)
-%cd(WD); BIDS_RFX(2, 6, 6)

batch.m

@@ -2,7 +2,7 @@
 % tutorial and will run the basic preprocessing, FFX and contrasts on it.
 % Results might be a bit different from those in the manual as some
 % default options are slightly different in this pipeline (e.g use of FAST
-% instead of AR(1))
+% instead of AR(1), motion regressors added)
 
 clear
 clc
@@ -14,38 +14,42 @@
 % URL of the data set to download
 URL = 'http://www.fil.ion.ucl.ac.uk/spm/download/data/MoAEpilot/MoAEpilot.bids.zip';
 
-WD = pwd; % the directory with this script becomes the current directory
-addpath(genpath(WD)) % we add all the subfunctions that are in the sub directories
+% directory with this script becomes the current directory
+WD = fileparts(mfilename('fullpath')); 
+
+% we add all the subfunctions that are in the sub directories
+addpath(genpath(fullfile(WD, '..'))) 
 
 
 %% Set options
 opt = getOption();
 
 % respecify options here in case the getOption file has been modified on
 % the repository
-opt.derivativesDir = fullfile(WD, '..', 'output', 'MoAEpilot'); % the dataset will downloaded and analysed there
+
+ % the dataset will downloaded and analysed there
+opt.dataDir = fullfile(WD, 'output', 'MoAEpilot');
 opt.groups = {''}; % no specific group
-opt.subjects = {1};  % first subject
+opt.subjects = {[]};  % first subject
 opt.taskName = 'auditory'; % task to analyze
-opt.contrastList = {...
-    {'listening'} ...
-    };
 
 % the following options are less important but are added to reset all
 % options
-opt.numDummies = 0;
 opt.STC_referenceSlice = [];
 opt.sliceOrder = [];
 opt.funcVoxelDims = [];
-opt.JOBS_dir = fullfile(opt.derivativesDir, 'JOBS', opt.taskName);
+opt.JOBS_dir = fullfile(opt.dataDir, '..', 'derivatives', 'SPM12_CPPL', 'JOBS', opt.taskName);
+
+
+% specify the model file that contains the contrasts to compute
+opt = rmfield(opt, 'model');
+opt.model.univariate.file = fullfile(WD, 'model-MoAE_smdl.json');
+
 
 %% Get data
-if ~exist(opt.derivativesDir, 'dir')
-    [~,~,~] = mkdir(opt.derivativesDir);
-end
 fprintf('%-40s:', 'Downloading dataset...');
 urlwrite(URL, 'MoAEpilot.zip');
-unzip('MoAEpilot.zip', fullfile(WD, '..', 'output'));
+unzip('MoAEpilot.zip', fullfile(WD, 'output'));
 
 
 %% Check dependencies
@@ -62,10 +66,11 @@
 
 
 %% Run batches
-BIDS_rmDummies(opt);
+BIDS_copyRawFolder(opt, 1)
 BIDS_STC(opt);
 BIDS_SpatialPrepro(opt);
 BIDS_Smoothing(FWHM, opt);
-BIDS_FFX(1, FWHM, opt);
-BIDS_FFX(2, FWHM, opt);
+BIDS_FFX(1, FWHM, opt, 0);
+BIDS_FFX(2, FWHM, opt, 0);
+
 

batch_download_run.m renamed to demo/batch_download_run.m

@@ -0,0 +1,23 @@
+{
+  "Name": "Listening",
+  "Description": "contrasts to compute for the FIL MoAE dataset",
+  "Input": {
+    "task": "auditory"
+  },
+  "Steps": [
+    {
+      "Level": "subject",
+      "AutoContrasts": ["trial_type.listening"],
+      "Contrasts": [
+        {
+          "Name": "listening_inf_baseline",
+          "ConditionList": [
+            "trial_type.listening"
+          ],
+          "weights": [-1],
+          "type": "t"
+        }
+      ]
+    }
+  ]
+}

demo/model-MoAE_smdl.json

@@ -9,19 +9,29 @@
 % group of subjects to analyze
 opt.groups = {''}; % {'blnd', 'ctrl'};
 % suject to run in each group
-opt.subjects = {[1:2]}; % {[1:2], [1:2]};
-% set the number of zeros used to pad the subject label (2 --> sub-blnd01 ; 3 --> sub-blnd001 )
-opt.zeropad = 2;
+% opt.subjects = {[4:6]};  % {[1:2], [1:2]};
+opt.subjects = {[]};  % {[1:2], [1:2]};
+
 
 % task to analyze
-opt.taskName = 'visMotion';
+opt.taskName = 'MotionDecoding';
+
+% opt.taskName = 'visMotion';
+
+% opt.taskName = 'balloonanalogrisktask';
+
+
+
+% The directory where the data are located
+
+% opt.dataDir = '/Users/mohamed/Desktop/MotionWorkshop/raw';
+% opt.dataDir = '/Users/mohamed/Desktop/Data/raw';
 
-% The directory where the derivatives are located
-opt.derivativesDir = '/Users/mohamed/Desktop/MotionWorkshop/derivatives';
+% opt.dataDir = '/home/remi/BIDS/visMotion/raw';
+opt.dataDir = '/home/remi/BIDS/MotionDecoding/raw';
+
+% opt.dataDir = '/home/remi/BIDS/ds001/rawdata';
 
-% Specify the number of dummies that you want to be removed.
-opt.numDummies = 0;
-opt.dummyPrefix = 'dr_';
 
 % Options for slice time correction
 % If left unspecified the slice timing will be done using the mid-volume acquisition
@@ -37,14 +47,23 @@
 % Voxel dimensions for resampling at normalization of functional data or leave empty [ ].
 opt.funcVoxelDims = [];
 
+
 % Suffix output directory for the saved jobs
-opt.JOBS_dir = fullfile(opt.derivativesDir, 'JOBS', opt.taskName);
+opt.JOBS_dir = fullfile(opt.dataDir, '..', 'derivatives', 'SPM12_CPPL', 'JOBS', opt.taskName);
+
+% specify the model file that contains the contrasts to compute
+
+% opt.model.univariate.file = '/Users/mohamed/Documents/GitHub/BIDS_fMRI_scripts/model-motionDecodingUnivariate_smdl.json';
+% opt.model.multivariate.file = '/Users/mohamed/Documents/GitHub/BIDS_fMRI_scripts/model-motionDecodingMultivariate_smdl.json';
+
+% opt.model.univariate.file = '/home/remi/github/CPP_BIDS_SPM_pipeline/model-visMotionLoc_smdl.json';
+
+opt.model.univariate.file = '/home/remi/github/CPP_BIDS_SPM_pipeline/model-motionDecodingUnivariate_smdl.json';
+opt.model.multivariate.file = '/home/remi/github/CPP_BIDS_SPM_pipeline/model-motionDecodingMultivariate_smdl.json';
+
+% opt.model.univariate.file = '/home/remi/github/CPP_BIDS_SPM_pipeline/model-balloonanalogriskUnivariate_smdl.json';
+% opt.model.multivariate.file = '/home/remi/github/CPP_BIDS_SPM_pipeline/model-balloonanalogriskMultivariate_smdl.json';
 
-opt.contrastList = {...
- {'VisMot'}; ...
- {'VisStat'}; ...
- % {'VisMot-VisStatic'}; ...
- };
 
 % Save the opt variable as a mat file to load directly in the preprocessing
 % scripts

getOption.m

@@ -3,46 +3,44 @@ function opt = getOption()
 % slice timing correction, pre-processing, FFX, RFX.
 
 if nargin<1
-    opt = [];
+ opt = [];
 end
 
 % group of subjects to analyze
-opt.groups = {};    % {'blnd', 'ctrl'};
+opt.groups = {''}; % {'blnd', 'ctrl'};
 % suject to run in each group
-opt.subjects = {};  % {[1:2], [1:2]};
+opt.subjects = {[]};  % {[1:2], [1:2]};
+
 
 % task to analyze
-opt.taskName = '';
+opt.taskName = 'visMotion';
+
 
 % The directory where the derivatives are located
-opt.derivativesDir = '';
+opt.dataDir = '/home/remi/BIDS/visMotion/raw';
 
-% Specify the number of dummies that you want to be removed.
-opt.numDummies = 2;
-opt.dummyPrefix = 'dr_';
 
 % Options for slice time correction
-opt.STC_referenceSlice = []; % reference slice: middle acquired slice (NOTE: Middle in time of acquisition, not space)
-% If  slice order is entered in time unit (ms) doing  so,  the  next  item  (Reference Slice) will contain a reference time (in
-% ms) instead of the slice index of the reference slice.
+% If left unspecified the slice timing will be done using the mid-volume acquisition
+% time point as reference.
+% Slice order must be entered in time unit (ms) (this is the BIDS way of doing things)
+% instead of the slice index of the reference slice (the "SPM" way of doing things).
+% More info here: https://en.wikibooks.org/wiki/SPM/Slice_Timing
+opt.sliceOrder = [];
+opt.STC_referenceSlice = [];
+
 
 % Options for normalize
-opt.funcVoxelDims = [];  % voxel dimensions to use for resampling at normalization
+% Voxel dimensions for resampling at normalization of functional data or leave empty [ ].
+opt.funcVoxelDims = [];
 
-% Suffix output directory for the saved jobs
-opt.JOBS_dir = fullfile(opt.derivativesDir,'JOBS',opt.taskName);
 
-opt.contrastList = {...
-    {'word'}; ...
-    {'pseudoword'}; ...
-%     {'pseudoword-word'}; ...
-    };
+% Suffix output directory for the saved jobs
+opt.JOBS_dir = fullfile(opt.dataDir, '..', 'derivatives', 'SPM12_CPPL', 'JOBS', opt.taskName);
 
-%% SLICE TIMING INFORMATION
-% TO BE USED ONLY IF SPM_BIDS CAN'T EXTRACT SLICE INFORMATION
-opt.sliceOrder = [];
+% specify the model file that contains the contrasts to compute
+opt.model.univariate.file = '/home/remi/github/CPP_BIDS_SPM_pipeline/model-visMotionLoc_smdl.json';
 
-opt.funcVoxelDims = [];  % Voxel dimensions of the functional data or leave empty [ ].
 
 % Save the opt variable as a mat file to load directly in the preprocessing
 % scripts