[DOC] update doc on how to filter files and what files gets upsampled

docs/source/FAQ.rst

@@ -144,6 +144,87 @@ You can use bids matlab to help you create bids valid filenames.
      hemi-R_space-MNI_label-V1v_desc-wang_mask.nii
 
 
+How can run my script only only certain files, like just the session ``02`` for example?
+----------------------------------------------------------------------------------------
+
+So in general you can select a subset of your data by using the ``opt.query``.
+
+This will create a "filter" that bids matlab will use to only "query"
+and retrieve the subset of files that match the requirement of that filter
+
+In "pure" bids matlab it would look like
+
+.. code-block:: matlab
+
+  BIDS = bids.layout(path_to_my_dataset)
+  bids.query(BIDS, 'data', opt.query)
+
+So if you wanted to run your analysis on say run ``02`` and ``05`` of session ``02``,
+you would define your filter like this:
+
+.. code-block:: matlab
+
+  opt.query.ses = '02'
+  opt.query.run = {'02', '05'}
+
+.. TODO add info about bidsFilterFile
+
+Preprocessing
+=============
+
+
+.. _preprocessing resampling:
+
+What images are resampled during preprocessing and to what resolution?
+----------------------------------------------------------------------
+
+In the spatial preprocessing workflow (``bidsSpatialPrepro``):
+
+1. When no normalization is requested
+
+This is the case when ``opt.space = 'individual'``, functional images resolution is not changed.
+This cannot be overridden.
+
+2. During normalization to MNI
+
+By default, functional images resolution is not changed.
+Override possible by setting ``opt.funcVoxelDims`` to the desired resolution.
+
+The anatomical images are resampled at 1 mm.
+
+Tissue probability maps downsampled at resolution of functional images
+mostly to help with potential with creation of tissue-based mask and also quality control pipelines.
+
+For several files, you can guess their resolution if they have ``res`` entity in their filename:
+
+- ``res-bold`` means that the image is resampled at the resolution of the BOLD timeseries
+- ``res-r1pt0`` means that the image is resampled at a resolution of 1.00 mm isometric
+
+.. code-block:: bash
+
+  sub-01
+  ├── anat
+  │   ├── sub-01_space-individual_desc-biascor_T1w.nii                   # native res
+  │   ├── sub-01_space-individual_desc-skullstripped_T1w.nii             # native res
+  │   ├── sub-01_space-individual_label-brain_mask.nii                   # native res
+  │   ├── sub-01_space-individual_label-CSF_probseg.nii
+  │   ├── sub-01_space-individual_label-GM_probseg.nii
+  │   ├── sub-01_space-individual_label-WM_probseg.nii
+  │   ├── sub-01_space-individual_res-r1pt0_desc-preproc_T1w.nii         # 1.0 mm
+  │   ├── sub-01_space-IXI549Space_res-bold_label-CSF_probseg.nii        # bold res
+  │   ├── sub-01_space-IXI549Space_res-bold_label-GM_probseg.nii         # bold res
+  │   ├── sub-01_space-IXI549Space_res-bold_label-WM_probseg.nii         # bold res
+  │   └── sub-01_space-IXI549Space_res-r1pt0_T1w.nii                     # 1.0 mm
+  └── func
+      ├── sub-01_task-auditory_space-individual_desc-mean_bold.nii       # native res
+      ├── sub-01_task-auditory_space-individual_desc-preproc_bold.nii    # native res
+      ├── sub-01_task-auditory_space-individual_desc-std_bold.nii        # native res
+      ├── sub-01_task-auditory_space-IXI549Space_desc-mean_bold.nii      # native res
+      └── sub-01_task-auditory_space-IXI549Space_desc-preproc_bold.nii   # native res
+
+See those `slides <https://docs.google.com/presentation/d/1bAAzvXpQ_4vcSO1yqOD3Uq_d70b-uu0h9xoIx0sx3es/edit?usp=sharing>`_
+for some pointers on how to make choices for the resolution to choose for your analysis.
+
 Results
 =======
 

src/bids_model/applyTransformersToEventsTsv.m

@@ -42,7 +42,8 @@
   for iTrans = 1:numel(transformers)
 
     % TODO make transformers more general
-    % - assumes only trial types can be input (therefore means that transformations cannot be "chained")
+    % - assumes only trial types can be input
+    %   (therefore means that transformations cannot be "chained")
     % - assumes transformations are only on onsets
     name = transformers(iTrans).Name;
     value = transformers(iTrans).Value;

src/defaults/checkOptions.m

@@ -34,6 +34,23 @@
   %       Default = ``struct('modality', {{'anat', 'func'}})``
   %       See ``bids.query`` to see how to specify.
   %
+  %       .. warning::
+  %
+  %         ``opt.query`` might be progressively deprecated in favor of ``opt.bidsFilterFile``
+  %         that allows using different filters for T1w and bold data.
+  %
+  %     - ``opt.bidsFilterFile`` - Sets how to define a typical images "bold", "T1w"...
+  %       in terms of their bids entities. The default value is:
+  %
+  %     .. code-block:: matlab
+  %
+  %           struct( ...
+  %               'fmap', struct('modality', 'fmap'), ...
+  %               'bold', struct('modality', 'func', 'suffix', 'bold'), ...
+  %               't2w',  struct('modality', 'anat', 'suffix', 'T2w'), ...
+  %               't1w',  struct('modality', 'anat', 'suffix', 'T1w'), ...
+  %               'roi',  struct('modality', 'roi', 'suffix', 'roi'));
+  %
   %  - **preprocessing**
   %
   %     - ``opt.realign.useUnwarp = true``

src/workflows/preproc/bidsSpatialPrepro.m

@@ -25,6 +25,9 @@
   % - normalize the data to MNI space, make sure
   %   ``opt.space`` includes ``IXI549Space``.
   %
+  % See the :ref:`preprocessing resampling` section of the FAQ to know
+  % at what resolution files are resampled during normalization.
+  %
   % If you want to:
   %
   % - use another type of anatomical data than ``T1w`` as a reference or want to specify