RFC5 - explain usage of arraycoordinatesystems `arrayCoordinateSystem`

[jo-mueller]

In the current (approved) RFC5 proposal, users can specify so-called array coordinate systems to state explicitly that an array is to be interpreted in pixel coordinates by transformations rather than physical coordinates:

{
  "arrayCoordinateSystem" : {
    "name" : "myDataArray",
    "axes" : [
      {"name": "dim_0", "type": "array"},
      {"name": "dim_1", "type": "array"},
      {"name": "dim_2", "type": "array"}
    ]
  }
}

...which would mean, that a list of coordinate systems could end up looking like this:

{
  "coordinateSystems": [
    {
      "name": "some_coordinate_system",
      "axes":  [...],
    },
    {
      "arrayCoordinateSystem" : {
        "name" : "myDataArray",
        "axes" : [
          {"name": "dim_0", "type": "array"},
          {"name": "dim_1", "type": "array"},
          {"name": "dim_2", "type": "array"}
        ]
      }
    }
  ]
}

I could imagine that nesting a separate object into this list makes validation harder. I ran some validation tests with the schemas over at ome/ngff-spec#67 and added a check in the schemas so that axes in a coordinate system must satisfy either of these conditions:

• between two or three axes of type "space"
• more than two axes of type "array"

which I think should be a good enough discriminator between a regular coordinate system and an array coordinate system.

In the spec text, I think we'd only need to adjust the example under array coordinate systems and remove (or shorten) this statement:

The name and axes names MAY be customized by including a arrayCoordinateSystem field in the user-defined attributes of the array whose value is a coordinate system object. The length of axes MUST be equal to the dimensionality. The value of "type" for each object in the axes array MUST equal "array".

cc @dstansby @will-moore @bogovicj

Edit Recent comment on RFC5

In the recently submitted comment on RFC, one of the major addressed points is the location and purpose of arrayCoordinateSystems. Upon more discussion with @bogovicj , I think I've grasped it - see my explanation below

[clbarnes]

I agree that wrapping one coordinate system in the list in an extra object should be avoided. However, I don't see that the current proposal allows that. coordinateSystems lists exist in ome.multiscales or ome.scene metadata on zarr groups, where the arrayCoordinateSystem key exists directly in the zarr attributes of a zarr array. I don't think that allows for an object with the arrayCoordinateSystem key in the (ome.multiscales|ome.scene).coordinateSystems lists.

As an aside: the arrayCoordinateSystem field should go into the ome namespace rather than directly into the zarr attributes.

I would try to avoid doing any axis type counting as that would go away if/when RFC-3 "more dimensions for thee" comes in.

[jo-mueller]

However, I don't see that the current proposal allows that.

Not super explicitly. I think I would just remove the cited statement and point out in the multiscales metadata that coordinate systems must have either at least two spatial axes (axis of type space) or any number of axes of type array.

[jo-mueller]

@will-moore I will use this issue to continue the discussion from ome/ngff-spec#18 so that everything relevant is over here at ome/ngff.

After talking with @bogovicj I also got a better understanding about how arrayCoordinateSystems are supposed to work.

arrayCoordinateSystems intended use

In essence, arrayCoordinateSystems standardize using zarr arrays directly as input/output for coordinate transformations. Consider the multiscale transforms:

"coordinateTransformations": [
  {
    "scale": [...],
    "input": "s0",
    "output": "physical"
  }
]

In this case, "input" is an instance of an implicitly defined arrayCoordinateSystem. It is never actually spelled out anywhere, but it is implicitly clear (from the dimension_namesunders0/zarr.json) how the array is sized and that there are generic dimension names (dim_0`, ...) attached to it.

With the use of arrayCoordinateSystems, any other coordinat transformation could use the same kind of formalism, and wouldn't have to refer to an explicitly defined coordinateSystem anywhere in the metadata, but could point to a zarr group (and the respective zarr.json therein) instead. The examples in the current spec text are just to elaborate how the corresponding coordinateSystem in the metadata would look like, if it were explicitly defined.

Ways forward

I'm a bit uncertain how this will affect implementations that already exist. Allowing transformation's input/output to zarr arrays will undoubtedly make implementations regarding this matter yet a bit more complicated. Similar to what we discussed at the Hackathon about how overloaded usage of input/output fields for paths/coordinate systems was tricky, led to the creation of the syntax in the scene metadata:

"input" : {"name": "....", "path": ".."}

I see two paths forward from this (also discussed briefly with JB yesterday):

Use explicitly defined array coordinate systems

Do not use implictly defined coordinate systems, but rather allow explicitly defined, dimensionless coordinateSystems (see also ome/ngff-spec#90). In this case, we'd need to consider the following questions:

• Should there be a default name for an arrayCoordinateSystem (i.e., the path of the array it associates itself with)?
• Should axis names reflect the dimension_names written down in the zarr.json? Or can they be anything?

Essentially, the names of the axes and the coordinate system are a bit meaningless here - but is that actually problematic? 🤔

Implicit usage

Allow implicit usage - in this case, I feel like we would need to adopt @dstansby's proposal #437 and use something like this formalism everywhere

{
  "input": {
    "name": "some_name",
    "path": "some_path",
    "array_path": "image/s0"
  }
}

because we'd otherwise always need to check whether path points to a multiscales group or to an actual zarr array 😕