Stats#

How can change the name of the folder of the subject level analysis?#

This can be done by changing the Name of the run level Nodes in the BIDS stats model.

If your Nodes.Name is one of the “default” values:

  • "run"

  • "run level"

  • "run_level"

  • "run-level"

  • …

like in the example below

  "Nodes": [
    {
      "Level": "Run",
      "Name": "run_level",
    }
  ]

then src.stats.subject_level.getFFXdir.m() will set the subject level folder to be named as follow:

sub-subLabel
└── task-taskLabel_space-spaceLabel_FWHM-FWHMValue

However if your Nodes.Name is not one of the “default” values, like this

  "Nodes": [
    {
      "Level": "Run",
      "Name": "parametric",
    }
  ]

then the subject level folder to be named as follow:

sub-subLabel
└── task-taskLabel_space-spaceLabel_FWHM-FWHMValue_node-parametric

How can I see what the transformation in the BIDS stats model will do to my events.tsv?#

You can use the bids.util.plot_events function to help you visualize what events will be used in your GLM.

If you want to vivualize the events file:

bids.util.plot_events(path_to_events_files);

This assumes the events are listed in the trial_type column (though this can be changed by the trial_type_col parameter).

If you want to see what events will be included in your GLM after the transformations are applied:

bids.util.plot_events(path_to_events_files, 'model_file', path_to_bids_stats_model_file);

This assumes the transformations to apply are in the root node eof the model.

In case you want to save the output after the transformation:

% load the events and the stats model
data = bids.util.tsvread(path_to_events_files);
model = BidsModel('file', path_to_bids_stats_model_file);

% apply the transformation
transformers = model.Nodes{1}.Transformations.Instructions;
[new_content, json] = bids.transformers(transformers, data);

% save the new TSV for inspection to make sure it looks like what we expect
bids.util.tsvwrite(fullfile(pwd, 'new_events.tsv'), new_content);

How should I name my conditions in my events.tsv?#

In BIDS format, conditions should be named in the trial_type column of the events.tsv file.

Some good practices for naming “things” can probably be applied here.

  • use only alphanumeric characters, underscores and hyphens, avoid spaces in the condition names

For example: foo_bar is ok, but f$o}o b^a*r is not.

  • the condition names should be short AND descriptive AND human readable

For example: 1 or one or condition1 are short but not descriptive.

An extra requirement to have condition names that can work with bidspm is that condition names ending with an underscore followed by one or more digits may lead to unwanted behavior (error or nothing happening - see issue when computing results of a GLM.)

So for example:

happy_face1 and house123 are ok, but happy_face_1 and house_123 are not.

If your BIDS dataset has conditions that do not follow this rule, then you can use the Replace variable transform in your BIDS statistical model to rename them on the fly without having to manually edit potentially dozens of files.

See also example below.

Say one of your events.tsv files looks like this:

onset

duration

trial_type

2

2

happy_face_1

4

2

house_2

5

2

happy_face_2

8

2

house_4

You can add the following transformation to the first node (usually the run level node) of your BIDS stats model.

{
  "Nodes": [
    {
      "Level": "Run",
      "Name": "run_level",
      "GroupBy": [
        "run",
        "subject"
      ],
      "Transformations": {
        "Description": "Replace",
        "Instruction": [
            {
                "Name": "Replace",
                "Input": "trial_type",
                "Replace": [
                    {
                        "key": "happy_face_1",
                        "value": "happy_face1"
                    },
                    {
                        "key": "house_2",
                        "value": "house2"
                    },
                    {
                        "key": "happy_face_2",
                        "value": "happy_face2"
                    },
                    {
                        "key": "house_4",
                        "value": "house4"
                    }
                ]
            }
        ]
    },
      "Model": {
        "X": [
            "trial_type.happy_face*",
            "trial_type.house*"
          ],
        "Description": "the rest of the bids stats model would go below this as usual."

    }
    }
  ]
}

Related issue: https://github.com/cpp-lln-lab/bidspm/issues/973

How should I structure my data to run my statistical analysis?#

The main thing to remember is that bidspm will read the events.tsv files from your raw BIDS data set and will read the bold images from a bidspm-preproc folder.

If your data was preprocessed with fmriprep, bidspm will first need to copy, unzip and smooth the data into a bidspm-preproc folder

Here is an example of how the data is organized for the MoAE fmriprep demo and what the bidspm BIDS call would look like.

├── inputs
│   ├── fmriprep                     # fmriprep preprocessed BIDS dataset
│   |   ├── dataset_description.json
│   │   └── sub-01
│   │       ├── anat
│   │       ├── figures
│   │       └── func
│   │           ├── sub-01_task-auditory_desc-confounds_timeseries.json
│   │           ├── sub-01_task-auditory_desc-confounds_timeseries.tsv
│   │           ├── sub-01_task-auditory_space-MNI152NLin6Asym_desc-brain_mask.json
│   │           ├── sub-01_task-auditory_space-MNI152NLin6Asym_desc-brain_mask.nii.gz
│   │           ├── sub-01_task-auditory_space-MNI152NLin6Asym_desc-preproc_bold.json
│   │           └── sub-01_task-auditory_space-MNI152NLin6Asym_desc-preproc_bold.nii.gz
│   └── raw                          # raw BIDS dataset
│       ├── dataset_description.json
│       ├── README
│       ├── sub-01
│       │   ├── anat
│       │   │   └── sub-01_T1w.nii
│       │   └── func
│       │       ├── sub-01_task-auditory_bold.nii
│       │       └── sub-01_task-auditory_events.tsv
│       └── task-auditory_bold.json
├── models                            # models used to run the GLM
│   ├── model-MoAEfmriprep_smdl.json
│   ├── model-MoAEindividual_smdl.json
│   └── model-MoAE_smdl.json
├── options
└── outputs
    └── derivatives
        └── bidspm-preproc          # contains data taken from fmriprep and smoothed
            ├── dataset_description.json
            ├── README
            ├── jobs
            │   └── auditory
            │       └── sub-01
            └── sub-01
                ├── anat
                └── func
                    ├── sub-01_task-auditory_desc-confounds_timeseries.json
                    ├── sub-01_task-auditory_desc-confounds_timeseries.tsv
                    ├── sub-01_task-auditory_space-MNI152NLin6Asym_desc-brain_mask.json
                    ├── sub-01_task-auditory_space-MNI152NLin6Asym_desc-brain_mask.nii
                    ├── sub-01_task-auditory_space-MNI152NLin6Asym_desc-preproc_bold.json
                    ├── sub-01_task-auditory_space-MNI152NLin6Asym_desc-preproc_bold.nii
                    ├── sub-01_task-auditory_space-MNI152NLin6Asym_desc-smth8_bold.json
                    └── sub-01_task-auditory_space-MNI152NLin6Asym_desc-smth8_bold.nii

WD = fileparts(mfilename('fullpath'));

subject_label = '01';

bids_dir = fullfile(WD, 'inputs', 'raw');
output_dir = fullfile(WD, 'outputs', 'derivatives');
preproc_dir = fullfile(output_dir, 'bidspm-preproc');

model_file = fullfile(pwd, 'models', 'model-MoAEfmriprep_smdl.json');

bidspm(bids_dir, output_dir, 'subject', ...
        'participant_label', {subject_label}, ...
        'action', 'stats', ...
        'preproc_dir', preproc_dir, ...
        'model_file', model_file, ...
        'fwhm', 8, ...
        'options', opt);

Generated by FAQtory