scverse / scverse/spatialdata

Units and the new transforms classes

Open
#120 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

method: transforms 🔃
Dominant language
Python
Stars
394
Forks
95
Avg merge
4d 3h
Merged PRs (30d)
7

Description

@kevinyamauchi @giovp @ivirshup

I plan to re-add support for storing units, here is how.

At the moment we store the transformations inside .attrs[TRANFORM_KEY] (or .uns[TRANSFOM_KEY] for AnnData objects for storing shapes), in the form of a dict[str, BaseTransformation]. The key is the name of the coordinate system the object aligns to.

I propose to add a new slot .attrs[COORDINATE_SYSTEMS_KEY] of type dict[str, NgffCoordinateSystem] to store unit and other Axis information.

This is similar to the old ways of storing coordinate systems, but with one difference. The transformation make zero use of this information, they work even without. In particular the order of the axes is irrelevant, and the fact that a coordinate system has an axis or not (say the z axes), doesn't influence the transformation, which can be applied anyway.

For instance consider the following:

my_image: SpatialImage = sdata.image['my_image']
assert get_dims(my_image) == ('c', 'y', 'x')
scale = Scale([2., 2.], axes=('x', 'y'))
sdata.set_transformation(image, scale, 'global')
my_cs = NgffCoordinateSystem(
    name='global', axes=[
        Axis(name='x', type='space', unit='meters'), 
        Axis(name='y', type='space', unit='meters'), 
        Axis(name='c', type='channel')
    ]
)
# the name 'global' is redundant, I'll maybe omit this from the function call
sdata.set_coordinate_system(image, 'global', my_cs)  
# in this case, the following line is equivalent to t = scale
t = sdata.map_coordinate_systems(my_image, 'global')
my_image_scaled = t.transform(my_image)
assert get_dims(my_image_scaled) == ('c', 'y', 'x')

What we have is that the information of the order of the axes of 'global' is not used. If we were doing the same for transforming points ('x', 'y', 'z') to 'global', we would obtain points ('x', 'y', 'z'), with x and y coordinates scaled.

Still when visualizing the data (napari/static plotting), or doing spatial queries, we will be able to make use of the knowledge that the 'x' axis is in micrometers. If an axis is specified by the coordinate system (like nothing is said about 'z'), then simply no information regarding 'z' would be retrieved.

Finally, when saving things to NGFF I will write something that conforms to the specs.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the proposed NgffCoordinateSystem and Axis usage alongside set_coordinate_system and map_coordinate_systems, then trace the existing transformation storage in .attrs[TRANFORM_KEY] and .uns[TRANSFOM_KEY]. Done means coordinate systems can store unit and axis information without changing transformation behavior, and saving to NGFF conforms to the stated specification.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
data
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.