Skip to content

Commit

Permalink
update doc basic calls bids app and bids filter file
Browse files Browse the repository at this point in the history
  • Loading branch information
@Remi-Gau
Remi-Gau committed Jun 27, 2022
1 parent aa8c223 commit 722bfc0
Show file tree
Hide file tree
Showing 2 changed files with 101 additions and 20 deletions.
57 changes: 54 additions & 3 deletions docs/source/FAQ.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,60 @@ You can use bids matlab to help you create bids valid filenames.
### 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`.
Currently there are 2 ways of doing this.
- using a `bids_filter_file.json` file or its counterpart field `opt.bidsFilterFile`
- using the `opt.query` option field.
On the long run the plan is to use only the `bids_filter_file.json`,
but for now both possibilities should work.
#### `bids filter file`
This is similar to the way you can "select" only certain files to preprocess
with [fmriprep](https://fmriprep.org/en/stable/faq.html#how-do-i-select-only-certain-files-to-be-input-to-fmriprep).
You can use a `opt.bidsFilterFile` field in your options
to define a typical images "bold", "T1w" in terms of their bids entities.
The default value is:
```matlab
struct('fmap', struct('modality', 'fmap'), ...
'bold', struct('modality', 'func', 'suffix', 'bold'), ...
't2w', struct('modality', 'anat', 'suffix', 'T2w'), ...
't1w', struct('modality', 'anat', 'space', '', 'suffix', 'T1w'), ...
'roi', struct('modality', 'roi', 'suffix', 'mask'));
```
Similarly when using the BIDS app cpp_spm you can use the argument `bids_filter_file`
to point to a JSON file that would also define typical images "bold", "T1w"...
The default content in this case would be:
```json
{
"fmap": {"datatype": "fmap"},
"bold": {"datatype": "func", "suffix": "bold"},
"t2w": {"datatype": "anat", "suffix": "T2w"},
"t1w": {"datatype": "anat", "space": "", "suffix": "T1w"},
"roi": {"datatype": "roi", "suffix": "mask"},
}
```
So if you wanted to run your analysis on say run `02` and `05` of session `02`,
you would define this file like this:
```json
{
"fmap": {"datatype": "fmap"},
"bold": {"datatype": "func", "suffix": "bold", "ses": "02", "run": ["02", "05"]},
"t2w": {"datatype": "anat", "suffix": "T2w"},
"t1w": {"datatype": "anat", "space": "", "suffix": "T1w"},
"roi": {"datatype": "roi", "suffix": "mask"},
}
```
#### `opt.query`
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
Expand All @@ -221,8 +274,6 @@ you would define your filter like this:
opt.query.run = {'02', '05'}
```
<!-- TODO add info about bidsFilterFile -->
(preprocessing resampling)=
## Preprocessing
Expand Down
64 changes: 47 additions & 17 deletions src/messages/cppSpmHelp.m
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ function cppSpmHelp()
%
% Note:
%
% - all parameters use snake_case
% - most invalid calls simply initialize CPP SPM
% - all parameters use ``snake_case``
% - most "invalid" calls simply initialize CPP SPM
%
%
%
Expand All @@ -17,8 +17,13 @@ function cppSpmHelp()
% .. code-block:: matlab
%
% cpp_spm(bids_dir, output_dir, analysis_level, ...
% 'action', 'some_action')
%
% 'action', 'some_action', ...
% 'participant_label', {}, ...
% 'dry_run', false, ...
% 'bids_filter_file', struct([]), ...
% 'verbosity', 2, ...
% 'space', {'individual', 'IXI549Space'}, ...
% 'options', struct([]))
%
%
% *Obligatory parameters*
Expand All @@ -32,7 +37,6 @@ function cppSpmHelp()
% :param analysis_level: can either be ``'subject'`` or ``'dataset'``
% :type analysis_level: string
%
%
% :param action: defines the pipeline to run; can be any of:
%
% - ``'preprocess'``
Expand All @@ -41,11 +45,11 @@ function cppSpmHelp()
% - ``'results'``
% :type action: string
%
% Note that:
% .. note::
%
% - ``'stats'`` runs model speification / estimation, contrast computation, display results
% - ``'contrasts'`` runs contrast computation, display results
% - ``'results'`` displays results
% - ``'stats'`` runs model speification / estimation, contrast computation, display results
% - ``'contrasts'`` runs contrast computation, display results
% - ``'results'`` displays results
%
% *Optional parameters common to all actions*
%
Expand All @@ -60,27 +64,44 @@ function cppSpmHelp()
% :param bids_filter_file:
% :type bids_filter_file: path to JSON file or structure
%
% :param options:
% :type options: path to JSON file or structure
%
% :param verbosity: can be ``0``, ``1`` or ``2``. Defaults to ``2``
% :type verbosity: positive scalar
%
% :param space: Defaults to ``{'individual', 'IXI549Space'}``
% :type space: cell string
%
% :param options: See the ``checkOptions`` help to see the available options.
% :type options: path to JSON file or structure
%
% .. note::
%
% Arguments passed to cpp_spm have priorities over the options defined in ``opt``.
% For example passing the argument ``'dry_run', true``
% will override the option ``opt.dryRun = false``.
%
% **PREPROCESSING:**
%
% .. code-block:: matlab
%
% cpp_spm(bids_dir, output_dir, 'subject', ...
% 'action', 'preprocess', ...
% 'task', {...})
% 'participant_label', {}, ...
% 'dry_run', false, ...
% 'bids_filter_file', struct([]), ...
% 'verbosity', 2, ...
% 'space', {'individual', 'IXI549Space'}, ...
% 'options', struct([]), ...
% 'task', {}, ...
% 'dummy_scans', 0, ... % specific to preprocessing
% 'anat_only', false, ... % specific to preprocessing
% 'ignore', {}, ... % specific to preprocessing
% 'fwhm', 6)
%
%
% *Obligatory parameters*
%
% .. TODO check if REALLY obligatory
%
% :param task: only one task
% :type task: cell string
%
Expand All @@ -106,17 +127,26 @@ function cppSpmHelp()
%
% cpp_spm(bids_dir, output_dir, 'subject', ...
% 'action', 'stats', ...
% 'preproc_dir', preproc_dir, ...
% 'model_file', model_file)
% 'preproc_dir', preproc_dir, ... % specific to stats
% 'model_file', model_file, ... % specific to stats
% 'participant_label', {}, ...
% 'dry_run', false, ...
% 'bids_filter_file', struct([]), ...
% 'verbosity', 2, ...
% 'space', {'individual', 'IXI549Space'}, ...
% 'options', struct([]), ...,
% 'roi_based', false, ...
% 'task', {}, ...
% 'fwhm', 6)
%
%
% *Obligatory parameters*
%
% :param preproc_dir: path to preprocessed data
% :type preproc_dir: path
% :type preproc_dir: path
%
% :param model_file:
% :type model_file: path to JSON file or structure
% :type model_file: path to JSON file or structure
%
%
% *Optional parameters*
Expand Down

0 comments on commit 722bfc0

Please sign in to comment.