[RTM] ENH: Conformation transforms

[effigies]

I took a little time to clean this up post 1.0.0-rc6, including some lessons learned regarding affine derivatives.

Current status:

• This creates a simple transform from each input T1w file to the T1w space (defined by T1w_preproc.nii.gz)
• It places it in the associated derivative directory of the input file, i.e. in a session-specific anat/ directory

Decisions going forward:

• Is this worthwhile?
• Should we organize it differently?
• Should we give the template and spaces/affines more generally their own page to make crystal clear exactly how each non-identical affine relates to each other and how to translate from one to another?

---

Open to critiques. @satra, this one's for you.

Closes #624.

[effigies]

https://815-78558509-gh.circle-artifacts.com/0/home/ubuntu/docs/workflows.html#longitudinal-processing

[satra]

in general this looks good, but in the freesurfer stream there is a way to get a transform back to the original input anatomical image. https://surfer.nmr.mgh.harvard.edu/fswiki/FsAnat-to-NativeAnat

now that page has not been updated in a while and it would be good to check if the material still holds.

[effigies]

Okay. My read from the earlier issue was that we didn't need to map back to the original T1w images. We can definitely output the transforms from each input to the template; that's built into mri_robust_template. I guess the question is how to name these derivatives...

…

-------- Original message -------- From: Satrajit Ghosh <notifications@github.com> Date: 9/26/17 17:45 (GMT-05:00) To: poldracklab/fmriprep <fmriprep@noreply.github.com> Cc: Christopher Markiewicz <markiewicz@stanford.edu>, Author <author@noreply.github.com> Subject: Re: [poldracklab/fmriprep] DOC: Add note about T1w space (#726) in general this looks good, but in the freesurfer stream there is a way to get a transform back to the original input anatomical image. https://surfer.nmr.mgh.harvard.edu/fswiki/FsAnat-to-NativeAnat now that page has not been updated in a while and it would be good to check if the material still holds. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub<#726 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AAFF8pUhFWhzPQbV8aKK-lj929F8wByKks5smXBxgaJpZM4Pk2vW>.

[satra]

a use case would be image-guided surgery. i'm not saying we should map back, but provide a way to map the data back. so just storing transforms would be sufficient i think.

[effigies]

Okay, as it is, this creates the following files:

Single session:

fmriprep/sub-<participant_label>/
    anat/
        sub-<participant_label>_T1w_preproc.nii.gz
        sub-<participant_label>_T1w_space-T1w.mat

Multi-session:

fmriprep/sub-<participant_label>/
    anat/
        sub-<participant_label>_T1w_preproc.nii.gz
    ses-<session_label>/
        anat/
            sub-<participant_label>_ses-<session_label>_T1w_space-T1w.mat

This was pretty easily manageable with our current derivatives plumbing. Now we can argue about what it should look like and figure out how to achieve it.

Questions:

1. Should the .mat file exist in single-session outputs?
2. Is it reasonable to put these session-specific mat files in ses-<label>/anat/ or, should they be somewhere like anat/transforms/?
3. What do we think about the naming scheme?
4. Is FSL-style .mat the preferred affine format? (I think there was a derivatives subgroup on this issue.)

[effigies]

cc @oesteban @chrisfilo

[chrisgorgo]

I like the clarification in the documentation, but I am not sure about the additional affine files.

For example in the single session case: coregistration of which two files does sub-<participant_label>_T1w_space-T1w.mat file represent?

Most importantly - question for @satra - is providing matrices that map between subject template and individual T1w files is a feature you currently need for some of your studies or something that you might see needing at some point in the future? I'm asking because we are overwhelmed with different work items and need to prioritise.

[satra]

@chrisfilo - it depends on the project at hand. some are targeted at generating scanner aligned rois for realtime feedback.

@effigies - your original note is fine, just that this notion of T1-space could be clarified. Is it some average space or is it aligned to the first one (see b below)?

perhaps some questions that can help me get a better understanding :

a. if we run our own freesurfer before fMRIprep is that still allowed? (we would like to do this for many reasons, we often run mindboggle separately, but also have datasets where we need to tweak freesurfer settings) mindboggle, for example, provides options for us to pass any recon-all flag to freesurfer

b. when you say you average T1s, is this from multiple sessions or single session? if multiple, how do you account for actual variation between sessions that are not rigid-body.

[effigies]

@satra It is still allowed to pre-run FreeSurfer. I will run vanilla -autorecon1 on a multi-session dataset (ds000114/sub-07) to verify that the fmriprep template-freesurfer template conversion is still valid under these conditions.

[effigies]

Okay, pre-run FreeSurfer and fmriprep-run FreeSurfer do not register properly under the current scheme. This isn't simply a problem of adjusting our inputs to FreeSurfer or always building our template in the space of the first time point; the decision of which T1w image is the first time point can be made arbitrarily, so we can't make any assumptions.

I think what we'll have to do is actually register the T1.mgz to T1_preproc.nii.gz. If we run FreeSurfer ourselves, it should be equivalent to just asking for tkregister2 to describe the conformation transform (and hopefully quick).

I think it's reasonable to assume a 7-dof (rigid + intensity) transform?

[effigies]

@satra WRT your question (b), we use mri_robust_template to allow for changes such as neck position and tumor growth, but more broad geometric changes in brain tissue (e.g. local volume/shape) are not going to be well-handled. I'm not sure if I'm addressing the cases you have in mind, though...

[oesteban]

Since your last comment, @effigies, is there any development on the overall focus of this PR? I mean, I know you've gotten really deep into this issue during that time, so maybe you have a new perspective to this.

Coming back to the origins:

• This creates a simple transform from each input T1w file to the T1w space (defined by T1w_preproc.nii.gz)
• It places it in the associated derivative directory of the input file, i.e. in a session-specific anat/ directory

And you implemented those ideas as follow:

Single session:

fmriprep/sub-<participant_label>/
    anat/
        sub-<participant_label>_T1w_preproc.nii.gz
        sub-<participant_label>_T1w_space-T1w.mat

Multi-session:

fmriprep/sub-<participant_label>/
    anat/
        sub-<participant_label>_T1w_preproc.nii.gz
    ses-<session_label>/
        anat/
            sub-<participant_label>_ses-<session_label>_T1w_space-T1w.mat

This looks great to me, with only one worry. From sub-<participant_label>_ses-<session_label>_T1w_space-T1w.mat I cannot tell if it goes from this T1w to the T1w-preproc space or viceversa. I would suggest having a T1wpreproc label: sub-<participant_label>_ses-<session_label>_T1wpreproc_space-T1w.mat or sub-<participant_label>_ses-<session_label>_T1w_space-T1wpreproc.mat if it goes the other way around.

Decisions going forward:

• Is this worthwhile?

I'd say this is out of question. @satra mentioned some applications where this could be a game changer for FMRIPREP to be widely adopted.

• Should we organize it differently?

I think we are in the right direction, probably @chrisfilo could give this a second thought.

• Should we give the template and spaces/affines more generally their own page to make crystal clear exactly how each non-identical affine relates to each other and how to translate from one to another?

FMRIPREP needs to aim at being cristal-clear for everything, so yes, this deserves their own documentation page.

[effigies]

There are a couple changes to the implementation since the comment you're referencing. Instead of FSL-formatted *_space-T1w.mat, they're ITK-formatted *_target-T1w_affine.txt, in keeping with BEP014.

The issue with the naming scheme you're discussing is that T1wpreproc isn't an existing space, T1w is. It's just that anat/*_T1w_preproc.nii.gz is definitionally in T1w. So the interpretation of each of those files is "Here's how to go from this input file (with ses-<label> in it) to the canonical T1w space." We could add a space-orig or something like that to indicate a per-file unique space, then it would be space-orig_target-T1w_affine.mat.

(Or am I misinterpreting? Is T1w a per-file unique space, and we should come up with a new name for merged T1w space?)

[oesteban]

+1 to space-orig_target-T1w_affine.mat

[effigies]

Added a line to the space table. Feel free to edit.

[chrisgorgo]

Originally I did not intend to have both space and target in the same file. space was for imaging files and target was for transformation files. In this context did you mean space as source space?

[effigies]

Yes.

…

-------- Original message -------- From: Chris Filo Gorgolewski <notifications@github.com> Date: 10/13/17 17:24 (GMT-05:00) To: poldracklab/fmriprep <fmriprep@noreply.github.com> Cc: Christopher Markiewicz <markiewicz@stanford.edu>, Mention <mention@noreply.github.com> Subject: Re: [poldracklab/fmriprep] [WIP] ENH: Conformation transforms (#726) Originally I did not intend to have both space and target in the same file. space was for imaging files and target was for transformation files. In this context did you mean space as source space? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#726 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AAFF8nuDgML1BUuagcu_UXJ2emrgOdveks5sr9T1gaJpZM4Pk2vW>.

[oesteban]

I like this for transformations. It is very explicit and easy to interpret.

[effigies]

@oesteban I think this is good to go, if you're okay with where it's currently putting files.

Again, for reference, this is the location in the case of a single input (the transform will be the identity):

derivatives/
    fmriprep/
        sub-<participant_label>/
            anat/
                sub-<participant_label>_T1w_space-orig_target-T1w_affine.txt

In the case of multiple images (e.g., from sessions test and retest), it would be as follows:

derivatives/
    fmriprep/
        sub-<participant_label>/
            ses-test/
                anat/
                    sub-<participant_label>_ses-test_T1w_space-orig_target-T1w_affine.txt
            ses-retest/
                anat/
                    sub-<participant_label>_ses-retest_T1w_space-orig_target-T1w_affine.txt

With a proposal that's been put forward on the list, we could in all cases store affines in sub-<participant_label>/anat/affine/:

derivatives/
    fmriprep/
        sub-<participant_label>/
            anat/
                affine/
                    sub-<participant_label>_ses-test_T1w_space-orig_target-T1w_affine.txt
                    sub-<participant_label>_ses-retest_T1w_space-orig_target-T1w_affine.txt

As the derivatives spec evolves, we can move in this direction, if that's preferred. (I think I would prefer it here, in the long term.)

@satra Let us know if you have any objections to the current state of things.