[WIP; ENH] Storage of iEEG electrodes in subject-specific FreeSurfer space

[adam2392]

Closes: #747

Currently, this is a draft to demonstrate exactly what would fix issues discussed in #747 .

[adam2392]

@sappelhoff not sure what's up w/ the link-checker, i'll take another look today.

Anything holding up this you think?

[sappelhoff]

So would the workflow for this solution be something like:

README
dataset_description.json
participants.tsv
derivatives/
    freesurfer/
        sub-01/
            T1.mgz <-- based on sub-01_T1w.nii
sub-01/
    anat/
        sub-01_T1w.nii
    ieeg/
        sub-01_space-fsnative_electrodes.tsv
        sub-01_space-fsnative_coordsystem.json <-- IntendedFor contains path to freesurfer T1.mgz in derivatives?

... or am I misunderstanding this?

If I am correct, then we still need to figure out how to appropriately point to a derivatives file, given that they could be stored anywhere and simply using "relative paths from BIDS root" are not guaranteed to work.

cc @effigies

[adam2392]

Yes that is correct!

[adam2392]

Perhaps,

If the derivative data is stored as a subdirectory of `bids_root`, then `IntendedFor` must point to that file relative to `bids_root`. If not, then a DOI should be present that links to that dataset.

?

[adam2392]

If the derivative data is stored as a subdirectory of `bids_root`, then `IntendedFor` must point to that file relative to `bids_root`. If not, then a DOI should be present that links to that dataset.

Is there any update with regards to this? Should I include this part, to specify that fsnative and fsnativetkr are derivative coordinate systems?

[sappelhoff]

Thanks for the reminder, and sorry that there is so little progress - it seems like very few people are interested in solving this problem.

If the derivative data is stored as a subdirectory of bids_root, then IntendedFor must point to that file relative to bids_root. If not, then a DOI should be present that links to that dataset.

so am I understanding your proposal correctly?

1. if derivatives/ is part of a BIDS dir, interpret IntendedFor as a relative path from the BIDS dir root
2. if derivatives/ is NOT part of a BIDS dir, a DOI "should be present" to point to the derivatives/, and then IntendedFor will be used "as if" derivatives/ were nested in the BIDS dir?

then a DOI should be present that links to that dataset.

where should that DOI be present?

What about datasets that do not have a DOI?

[robertoostenveld]

the proposed fsnativetkr coordinate system is specific to a particular anatomical MRI in FS format. E.g. consider that you start with a 1mm T1 scan and another 0.7 mm T1 scan from the patient. The number of slices and hence the alignment of the first (lower-resolution) scan within the 256x256x256 volume are likely to be different than the number of slices and hence the alignment of the higher-resolution scan. If you run freesurfer on the low-res, the output will be shape-wise very similar to that of the high-res, but the data expressed in the fsnativetkr coordinate system will be shifted with respect to each other.

I think that fsnativetkr therefore cannot be specified without the corresponding IntendedFor linking to an MRI that must represent the 256x256x256 volume in the FS file format.

[robertoostenveld]

are these indices 0-offset or 1-offset?

Should the middle of a 256x256x256 volume not be represented as [127.5 127.5 127.5] (when 0-offset) or [128.5 128.5 128.5] (where 1-offset)?

The middle of a 2x2x2 volume would be at voxel [0.5 0.5 0.5] if you start counting voxels at [0 0 0], or at [1.5 1.5 1.5] when you start counting at [1 1 1].

[adam2392]

I'm pretty sure it is with 0-offset.

That's what I thought initially... but I think there is some offset, so for example, running the following

        mri_info --vox2ras-tkr <img>

    This will generally be the 4x4 matrix for FreeSurfer output.::

            [
                [-1.0, 0.0, 0.0, 128.0],
                [0.0, 0.0, 1.0, -128.0],
                [0.0, -1.0, 0.0, 128.0],
                [0.0, 0.0, 0.0, 1.0],
            ]

This essentially centers the coordinates at the "center" of the volume "almost".

Reference: https://www.mail-archive.com/freesurfer@nmr.mgh.harvard.edu/msg69541.html

[adam2392]

I think that fsnativetkr therefore cannot be specified without the corresponding IntendedFor linking to an MRI that must represent the 256x256x256 volume in the FS file format.

Then perhaps what is needed to fully define this TKR coordinate system is:

"The IntendedFor also MUST be defined linking to an MRI that MUST represent the 256x256x256 volume in the FreeSurfer file format."?

[adam2392]

https://bids-specification--757.org.readthedocs.build/en/757/99-appendices/08-coordinate-systems.html#ieeg-specific-coordinate-systems

[robertoostenveld]

fsnative is not defined relative to the 1mm 256^3 MRI, but is defined relative to the AC of the individual participant.

[adam2392]

I'm not sure I follow. Isn't fsnative just the xyz coordinates in RAS space based on the vox2ras affine transformation?

[robertoostenveld]

RAS is only the specification of the direction of the axes, the origin also needs to be defined. That origin is at the anterior commissure, or not?

[adam2392]

Ah yes you're right. I just noticed I had two incongruent sentences. Adjusted now to specify AC.

[adam2392]

1. if derivatives/ is part of a BIDS dir, interpret IntendedFor as a relative path from the BIDS dir root
2. if derivatives/ is NOT part of a BIDS dir, a DOI "should be present" to point to the derivatives/, and then IntendedFor will be used "as if" derivatives/ were nested in the BIDS dir?

then a DOI should be present that links to that dataset.

where should that DOI be present?

What about datasets that do not have a DOI?

@sappelhoff is the best place to handle this within this PR? Perhaps adding a statement:

The `IntendedFor` key must be defined either with: i) a DOI or ii) a relative path from the BIDS directory

?

[sappelhoff]

is the best place to handle this within this PR? Perhaps adding a statement:

although it will probably delay the efforts here, I think it's best to first deal with that issue here: #471 (comment)

and then come back to the present one.

[sappelhoff]

@adam2392 -- just a note that #918 has been merged and BIDS URIs will be part of the 1.8 release (probably some time in September). Not sure if what you proposed in this PR is still needed and/or salvageable. If not, please close the PR :-)

Else. we can leave it open and keep working on it.

[dorahermes]

Nice, clarifying surface space would be helpful.

[dorahermes]

Freesurfer has several surfaces (pial, white, inflated... ), it is unclear which surface is meant