SurfaceTransform class #203

feilong · 2024-05-16T19:47:23Z

Transforms data between different surface spaces.

Dylan is working on algorithms to derive the transforms.

…is comparable with input data. See https://feilong.github.io/tpl-onavg/how_to_use/space_travel.html

oesteban · 2024-05-16T20:25:46Z

nitransforms/surface.py

+
+        Parameters
+        ----------
+        x : array-like, shape (..., nv1)


what is nv1? number of vertices?

Yes, the number of vertices. I use nv1 for the number of vertices of input, and nv2 for the output, given they are likely to be different.

oesteban · 2024-05-16T20:26:06Z

nitransforms/surface.py

+        Parameters
+        ----------
+        x : array-like, shape (..., nv1)
+            Data to transform.


What is "data" in this context?

I was thinking typically either functional data (2D data matrices, e.g., response time series) or anatomical data (1D maps, e.g., thickness).

oesteban · 2024-05-16T21:07:34Z

nitransforms/surface.py

+        return filename
+
+    @classmethod
+    def from_filename(cls, filename, fmt=None):


from filename would not read sphere.reg and so forth?

This one is only reading the sparse matrix from a file.
With the code Dylan's working on, we can generate the sparse matrix from the spheres.

codecov · 2024-05-20T10:29:00Z

Codecov Report

Attention: Patch coverage is 89.92629% with 41 lines in your changes missing coverage. Please review.

Project coverage is 94.39%. Comparing base (76832f5) to head (f69faaf).
Report is 89 commits behind head on master.

Files with missing lines	Patch %	Lines
nitransforms/surface.py	89.37%	26 Missing and 13 partials ⚠️
nitransforms/base.py	94.87%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #203      +/-   ##
==========================================
- Coverage   95.79%   94.39%   -1.40%     
==========================================
  Files          14       15       +1     
  Lines        1307     1713     +406     
  Branches      259      323      +64     
==========================================
+ Hits         1252     1617     +365     
- Misses         52       79      +27     
- Partials        3       17      +14

Flag	Coverage Δ
unittests	`94.39% <89.92%> (-1.40%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Shotgunosine · 2024-05-21T13:55:35Z

From the documentation for wb_command -surface-sphere-project-unproject:

A surface registration starts with an input sphere, and moves
its vertices around on the sphere until it matches the template data.
This means that the registration deformation is actually represented as
the difference between two separate files - the starting sphere, and the
registered sphere. Since the starting sphere of the registration may not
have vertex correspondence to any other sphere (often, it is a native
sphere), it can be inconvenient to manipulate or compare these
deformations across subjects, etc.

Based on that description, I think the next class we need is one that will represent registration deformation and contains the original sphere and the deformation sphere (in other words, mea culpa, @oesteban was right). I'm not 100% certain it will be useful for anything (maybe project-unproject?), but it is the representation of the deformation.

Edit:
Ok actually the Surface Coordinate Transform class will already represent this deformation.

oesteban · 2024-05-21T14:02:38Z

As I mentioned, I totally see why you wanted to focus on the interpolation matrix. In practical terms, it's all you care for.

But to calculate it, in one way or another you need to formalize the transform ;)

Shotgunosine · 2024-05-21T14:04:57Z

@oesteban Happy to talk about it more, but I think the SurfaceCoordinateTransform is the formalization of the transform. Isn't it? The deformation itself isn't useful and transforming data by subtracting the coordinate would less accurate than looking up the new coordinates by index.

oesteban · 2024-05-21T14:05:28Z

@oesteban Happy to talk about it more, but I think the SurfaceCoordinateTransform is the formalization of the transform. Isn't it? The deformation itself isn't useful and transforming data by subtracting the coordinate would less accurate than looking up the new coordinates by index.

Yup, that's correct.

Shotgunosine · 2024-05-21T15:57:55Z

In terms of use cases for surface transformations, here's what I can think of:

Taking some metric defined on the cortical surface in subject T1w space and determining what the value of that metric would be for every vertex in a reference space (wb_command -metric-resample).
Taking labels defined in a reference space and determining which vertices in subject space those labels should be applied to (wb_command -label-resample).
Creating a surface in which every vertex corresponds to a vertex from a reference surface, but with coordinates defined in the subject's T1w space (wb_command -surface-sphere-project-unproject).

We can kinda do 1 and 2 with the resampling method we've got now (though we've only implemented barycentric for this and they recommend adap_bary_area). I still have trouble wrapping my head around how surface-sphere-project-unproject works, but I feel like that's the next use case to try implementing to confirm that this representation of surface transformation is sufficient.

feilong · 2024-06-04T14:06:43Z

Hi @Shotgunosine, I think surface-sphere-project-unproject is closely related to the transform @oesteban wants.
It defines the warp using two spheres (e.g., sphere and sphere.reg). If a new sphere X is aligned to one of them (say, sphere.reg), we can use the barycentric weights (between sphere.reg and X) and the coordinates of sphere to warp X. That is, computing the new coordinates of X when it's aligned to sphere space. Conceptually, it's a diffeomorphic transform defined by the two spheres.
In practice, this is hardly used. The only use case I know is warping between fsaverage and fs_LR spheres. That being said, it's good to have it for completeness.

effigies · 2024-06-20T21:41:13Z

nitransforms/surface.py

+            rs_x = x._coords[:, 0] @ mat
+            rs_y = x._coords[:, 1] @ mat
+            rs_z = x._coords[:, 2] @ mat
+            y = SurfaceMesh.from_arrays(np.vstack([rs_x, rs_y, rs_z]).T, self.reference._triangles)


I'm confused why this is decomposed. Is it a mathematical requirement, or a hack to get things working, or...?

Dockerfile

Co-authored-by: Oscar Esteban <code@oscaresteban.es>

oesteban · 2024-06-21T05:36:33Z

nitransforms/surface.py

+        reference: surface
+            Surface with the destination coordinates for each index.
+        moving: surface
+            Surface with the starting coordinates for each index.


I feel this is defined in reverse.

Suggested change

reference: surface

Surface with the destination coordinates for each index.

moving: surface

Surface with the starting coordinates for each index.

reference: surface

Surface with the starting coordinates for each index.

moving: surface

Surface with the destination coordinates for each index.

oesteban · 2024-06-21T05:38:14Z

nitransforms/surface.py

+        if inverse:
+            source = self.reference
+            dest = self.moving
+        else:
+            source = self.moving
+            dest = self.reference


Reference gives typically the sampling, so like above:

Suggested change

if inverse:

source = self.reference

dest = self.moving

else:

source = self.moving

dest = self.reference

if not inverse:

source = self.reference

dest = self.moving

else:

source = self.moving

dest = self.reference

oesteban · 2024-06-21T05:39:13Z

nitransforms/surface.py

+        reference: spherical surface of the reference space.
+            Output will have number of indices equal to the number of indicies in this surface.
+            Both reference and moving should be in the same coordinate space.
+        moving: spherical surface that will be resampled.
+            Both reference and moving should be in the same coordinate space.


this matches my understanding of reference and moving

oesteban

Looks good overall, thanks for putting this together.

We still disagree on what reference and moving is, but I'm happy to go ahead and swap them the day I manage to convince you of the convention :D

oesteban · 2024-06-22T02:44:03Z

.gitignore

Let me get this in in a separate PR

oesteban · 2024-06-22T02:44:21Z

Dockerfile

Let me get this in in a separate PR

nitransforms/surface.py