Formalizing BIDS derivative for freesurfer output

[omar-rifai]

Objective

Formalizing a way to store freesurfer outputs in a BIDS compliant hierarchy. In other words, the objective is not to make every freesurfer file BIDS compliant, but rather have a freesurfer output root directory that is BIDS compliant. This is needed in case we want to programmatically compose BIDS apps that perform freesurfer processing.

Previous Discussions

There are two open issues that discuss the problem more or less:

• #377: mentions two examples: freesurfer/sub-01/ and freesurfer/sub-01/ses-mri/anat/. But both are problematic because:

  • The former does not account for longitudinal datasets
  • Neither are up to date with the current file naming convention which requires a suffix and an extension

• #461: For cross sectional output the suggestion (in the comment) is freesufer/sub-01_ses-01/. This also does not account for the latest file naming convention.

Proposal

In order to abide by the BIDS derivative filenaming convention

Each Derivatives filename MUST be of the form: <source_entities>[keyword-].

A proposal would be to:

• Add freesurfer as a suffix and dir as an extension (dir can be replaced with something else but the idea is to use an extension and let the extension reflect the fact that the content is a folder)

• Allow the directory to reside inside a datatype such as anat (freesurfer) or pet (petsurfer).

The result would be a directory that would look as follows:

`freesurfer/sub-01/ses-01/anat/sub-01_ses-01_freesurfer.dir/` 

Granted, the downside of this is that it would require specifying multiple dirs in the subject ID, like subj="sub-01/ses-01/anat/sub-01_ses-01_freesufer and it does "feel a bit hacky". However:

• A generic BIDS parser would be able to grap the output
• The alternative "freesufer/sub_01/ses-01/" would still be allowed as an unspecified derivative.

@ftadel @effigies @dnacombo

[ftadel]

Neither are up to date with the current file naming convention which requires a suffix and an extension

I think this applies to an individual pre-processed file that correspond to one single file raw file in the root dataset, and that are BIDS-compliant. FreeSurfer is not BIDS-compliant and therefore we should not try to make anything in the freesurfer sub-folder BIDS-compliant.

Formalizing a way to store freesurfer outputs in a BIDS compliant hierarchy.

It is explicitly specified that there is no need to try to make it BIDS compliant: https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#non-compliant-derivatives

This is needed in case we want to programmatically compose BIDS apps that perform freesurfer processing.

I think the recommendation from the FreeSurfer wiki (https://surfer.nmr.mgh.harvard.edu/fswiki/BIDS):

• is very simple and non-ambiguous,
• handles all the cases efficiently,
• is compatible with the FreeSurfer SUBJECTS folder,
• is easily accessible programmatically to any app needing to deal with FreeSurfer outputs.

Am I missing something here?

[omar-rifai]

Thanks for having a look at this. Sorry if this was not clear but the purpose was not to make anything inside the freesurfer sub-folder BIDS compliant but just having the path to that "root" freesufer directory BIDS compliant.

My proposal is sort of a hack so that we could treat the entire freesurfer directory as a BIDS compliant file (that is, with a suffix and an extension).

The context (and the reason for this proposal) is that we are trying to build a generic "BIDS" output parser with which we could fetch outputs from different neuro-imaging software. If we stay with the proposal in the wiki (https://surfer.nmr.mgh.harvard.edu/fswiki/BIDS), the parser would require specific instructions for accessing freesurfer output.

That being said, if this is too much of a hassle (in particular with the issue of the FreeSurfer SUBJECTS folder compatibility), we can just agree on the wiki proposal.

[ftadel]

the parser would require specific instructions for accessing freesurfer output.

Indeed. But these rules are very simple and probably easy to code, in comparison to the hassle of having all the FreeSurfer users needing to hack their existing scripts and modifying their databases (which most people wouldn't do anyway - causing you in practice to have to code the two versions in your parser). My preference would go along the line of minimum global effort in the community - sorry for the added work it means on your end :-)

However, others might have different opinions, and I'm probably not up-to-date with what was already decided in the past 2-3 years. Let's wait for more feedback.

[Remi-Gau]

I feel that this discussion has its place in the BEP35 google doc: https://docs.google.com/document/d/1tFRNumQyIgjXBNC3brFDLO9FaikjL84noxK6Om-Ctik/edit#heading=h.gjdgxs

@omar-rifai