Clarification of axes in the event dict.

[tlambert03]

I have a question about the design/intent of keys in the "axes" dict in the event dict.

from what I can tell "axes" key/values are put into AcquisitionEvent.axisPositions_ in eventFromJSON. And the only real consequence in the acquisition engine seems to be tha shouldAcquireImage will return true if there are any keys present in axisPositions_. (And, importantly, that "axes" keys are then added to the image metadata).

It seems that some keys (such as position, time, and z) have special meaning, but only for the pycro-manager Dataset. The meaning of other keys, (for instance, like z_ext in the napari example) seems entirely up to the user (beyond the forcing of an acquisition).

If I have that correct, it seems that axes is more or less performing double duty as a boolean "please acquire an image" flag, and as a metadata store that various IO services can interpret as desired. From the perspective of event object schema I wonder if it might be clearer to decouple things that have very real acquisition consequences from arbitrary things that are left to the interpretation of the image processing/IO pipeline? This would essentially turn "axes" into something more like "metadata" ... and add one additional object to the event dict like:

{
  'metadata': {"indices": {"time": 0}}, 
  'acquire_image': True
}

# or, something that could eventually be expanded with 
# well-defined non-acquisition events.
{
  'action': 'acquire' 
}

thoughts?

---

side note: if I'm correct about the keys position, time, and z being there just for Dataset, maybe using, e.g. Dataset._TIME_AXIS instead of the hard-coded "time" in multi_d_acquisition_events would make that relationship clearer?

[henrypinkard]

Yes, I fully agree. The reason I made the presences of 'Axes' also serve as the flag for whether to acquire an image was an attempt to keep the events as succinct as possible. But yeah I think it would be better to make it more explicit and not have this hidden double duty as you suggest. I like the 'action': 'acquire' syntax better. It would be easy to just make this default to 'acquire' if no 'action' is provided, both to keep the events succinct and maintain backwards compatibility.

maybe using, e.g. Dataset._TIME_AXIS instead of the hard-coded "time" in multi_d_acquisition_events would make that relationship clearer?

Agreed.

There's not actually much special about 'time', 'z', 'position'. Dataset will work just the same regardless of which ones you use. They're just hard coded and included to simplify things for new users--for example, so that time is a named argument of Dataset.read_image to help guide a new user. This is also consistent with the axis names hard coded by Micro-Magellan and probably eventually the Micro-Manager MDA.

'channel' is somewhat special, as it gets added by the Acquisition Engine based on the images that get acquired and is then used to split apart data by the (Java) viewer. 'row' and 'column' are also special, as they can be used by the viewer and by Dataset to automatically stitch tiled images. But there's is also another flag in the summary metadata needed to activate this mode I believe.