BIDS derivatives for freesurfer

1

Hello,

I’m working on converting freesurfer output to bids format. Only anatomical T1, T2 data are processed.
I have a few questions.

  1. File structure

1-1) Do I need to specify anat folder?
In the free surfer wiki (https://surfer.nmr.mgh.harvard.edu/fswiki/BIDS), they didn’t specify anat or func folder and just went with

freesurfer/
    sub-<subject_label>/
        /mri
        /surf
        ...

1-2) Is it okay to folders such as /mri , /surf , /stats ? As far as I know, it is not specified in BIDS extension proposals.

  1. Filename and extension
    What should I do with all the mgz files? As for file extension, is mgz format allowed in BIDS? Do I have to rename them in a certain way? (by making all the mgz files to somehow matching https://docs.google.com/document/d/1YG2g4UkEio4t_STIBOqYOwneLEs1emHIXbGKynx7V0Y/edit# ?)

  2. JSON file
    In BEP, I saw that all derivative files should have their own JSON file (https://docs.google.com/document/d/1Wwc4A6Mow4ZPPszDIWfCUCRNstn7d_zzaWPcfcHmgI4/edit#; Metadata organization (file level)). However, as you can see (ex. https://surfer.nmr.mgh.harvard.edu/fswiki/ReconAllOutputFiles), there are too many. Is it necessary?

  3. fMRIprep
    I’m planning to run fMRIprep and use --fs-no-reconall flag. If the filenames and format are converted (question 2 above), would fmriprep recognize freesurfer outputs?

2

Hi,

You probably want to take a closer look at the bids format structure, here is a good overview: https://github.com/bids-standard/bids-starter-kit/wiki/The-BIDS-folder-hierarchy

Typically, any freesurfer output will go into a derivatives subfolder of your top-level bids directory, rather than as your main files. So your directory structure will look like:

yourdataset
├── dataset_description.json
├── participants.tsv
├── derivatives
│   ├── freesurfer
│   │   ├── sub-01
│   │   │  ├──mri
│   │   │. ├──surf
│   │   │. ├──...
├── sub-01
│   ├── anat
│   │   ├── sub-01_inplaneT2.nii.gz
│   │   └── sub-01_T1w.nii.gz
│   └── func
├── sub-01_task-balloonanalogrisktask_run-01_bold.nii.gz
│       ├── sub-01_task-balloonanalogrisktask_run-01_events.tsv
└── task-balloonanalogrisktask_bold.json

Here is documentation on fmriprep and freesurfer: https://fmriprep.readthedocs.io/en/stable/outputs.html?highlight=freesurfer#freesurfer-derivatives

If you have your freesurfer dir in derivatives and named properly, fmriprep will automatically detect it when running your subjects and not rerun freesurfer, but rather use the pre-run freesurfer.

1 Like
3

Hi, @Ursula_Tooley
Thank you so much for your response! It helps me a lot.

However, I was thinking to put the derivatives folder out of BIDS folder like in this post (Raw and derivatives seperation) @effigies and it would be also okay?

Also, you said “any freesurfer output”, do you mean that I should maintain the freesurfer output file structure and format as it is? Could you tell me whether I need to change mgz file format to nii.gz or not?

Thank you so much, sincerely!

4

Hi @1116,

FreeSurfer outputs are not BIDS-compliant, but are generally useful. Which is also true of basically anything that wasn’t written in lockstep with the BIDS derivatives standard, and yet we still need to publish derived data. So we have to take a pragmatic view that a derivative can be non-BIDS, and sit alongside BIDS Derivatives. BIDS-Derivatives-compliant outputs will have the advantage of being programmatically queryable, while non-compliant outputs will presumably have the advantage of being understood by their toolchain.

If you look at the output of fMRIPrep, we place a freesurfer/ subjects directory where the subjects have the sub-<label> format of participants in BIDS, alongside an fmriprep/ directory that works to conform to the BIDS-derivatives (draft) specification.

Because FreeSurfer tools will assume that your data is in MGZ, you should keep it that way.

Best,
Chris

1 Like
5

In the ds000248 example we have taken a slightly different approach than the one that @effigies pointed out (click on the link to check it out).

In a nutshell, we create a /derivatives/freesurfer/ directory and in that freesurfer directory, we nest the freesurfer subjects/ directory … in which we then place the subjects in their own directories named by their label --> note that for sub-01, 01 would be the actual label.

We took this idea from here: https://github.com/BIDS-Apps/freesurfer

–> search for (ctrl + F)

  • … so it does not include "sub-" …
  • … output of the pipeline consist of the SUBJECTS_DIR …

cc @jasmainak @agramfort

Example:

├── derivatives
│   ├── freesurfer
│   │   └── subjects
│   │    │  ├── 01
...
6

Thank you for your reply!
It helped me a lot!

7

I can see that there’s somewhat variance within bids-derivatives.
Thank you for your reply.