RFC 7: Channel Metadata (collective scoping)

[lubianat]

EDIT: This is a scoping issue for RFC 7 - Channel Metadata and all comments are welcome.

You don't need to read the comments to contribute!

Just share your thoughts on which kind of "metadata" related to Channels you would like to see in OME-Zarr.

For user stories, use:

• Metadata: User stories for named channels #173

For design considerations:

• https://github.com/lubianat/rfc7-drafts

Other details and links hidden for simplicity.

Details

what

There are at least 5 kinds of "channel metadata" that could be useful:

• structural (i.e. where the bytes for each channel are located; that is in the OME-Zarr spec)
• acquisition (e.g. mostly the “Channel” part of the OME Model, indirectly via bioformats2raw layout in OME-Zarr)
• rendering metadata (e.g. the channels field of “omero” metadata in OME-Zarr)
• specimen/sample (e.g. DCA's Channel Metadata spec, covering the biological aspects particular to that channel)
• pre-computed metadata (e.g. DCA's Normalization Statistics , which may be used for rendering/processing

how

• to be defined, depending on progress of extensibility proposals and RFC-8

scope

(this section may change)

For a first draft RFC-7 for channel metadata, the goal would be to find a "core":

• agreeing on a way to represent structural metadata for channels (and perhaps discrete axis in general)
• agreeing on a design that would allow future extensions with rendering/specimen/acquisition/pre-computed metadata for channels

not in scope

For the first draft, we will avoid over specifying some of the details:

• omero.channels need to be revisited, but somewhat separately to avoid duplicated efforts
• structural is needed for user stories (named channel; channels by reference vs by index)
• rendering is broad and complex (multiple agreement points, multiple proposals)
• specimen/bio is broad and complex (multiple agreement-building points)
• precomputed is similarly broad
• acquisition is a large epic (e.g. Quarep LiMi), too early to go into decisions

Some background:

Issues

• RFC-7: where is it? #392

• GDocs with rough drafts

• Metadata: User stories for named channels #173 (structural)

• EPIC: rendering settings #537 (rendering)

• Metadata for color and contrast limits #23 (rendering)

OME-XML metadata (including Channels part)

• OME-XML equivalent data #27
• OME Metadata Support #104

image.sc:

OME-Zarr: how “transitional” is the omero metadata? (Jan 2026)

zulip:

• https://imagesc.zulipchat.com/#narrow/channel/328251-NGFF/topic/per-channel.20metadata.20after.20.60omero.60.20key.20is.20phased.20out/near/482224328

• https://imagesc.zulipchat.com/#narrow/channel/328251-NGFF/topic/potential.20RFC.3A.20coordinate.20arrays/with/609824018

previous work

broad:

• https://github.com/broadinstitute/cellpainting-gallery-metadata
• https://github.com/bethac07/ngff/blob/channel_RFC/rfc/7/draft.json

biohub

• https://github.com/chanzuckerberg/ops-schema
• hi! would you welcome feedback? chanzuckerberg/dynamic-cell-atlas-specs#1 (specimen/sample)
  about https://chanzuckerberg.github.io/dynamic-cell-atlas-specs/v0.2/channel-metadata.html
• https://chanzuckerberg.github.io/cryoet-data-portal/stable/cryoet_data_portal_docsite_data.html

allen

• https://github.com/AllenNeuralDynamics/biodata-schema/blob/c348b05ddc94e5a896708213fe4f360317e2b515/src/aind_data_schema/components/configs.py#L176

omero metadata

https://ngff.openmicroscopy.org/specifications/0.5/index.html#omero-metadata-transitional

[d-v-b]

it might be helpful to separate some concerns.

one big concern is how to model an array where one or more dimensions has indices that only make sense in relation to some other array. For multichannel data, there's often an array dimension that can only be interpreted by consulting another array, e.g. a 1D array of channel names, ["dapi", "gfp", "dsred"], or just ["channel_0", "channel_1", ...].

this structure -- one array requires another dimensionally-aligned array for its interpretation -- is not specific to multichannel data. Image segmentations of overlapping entities also use this structure, as does tiled imaging, etc. it's actually very common. So any solution for this particular aspect of multichannel data should be designed so that it also covers these other uses cases. That means you should not make the "data array relates to a 1D array of labels" relationship specific to multichannel images.

xarray already uses this general data model (where an array can be indexed by values defined in another array), so if you bake it in to ome-zarr you get a big xarray compatibility boost for free.

[jluethi]

Thanks a lot @lubianat for summarising the thinking about this & linking to relevant issues!

I've added our user story over here: #173 (comment)

My main question from it is whether channel identifiers for image processing count as structural information or are its own "what". The only way this is currently in the OME-Zarr spec (that I'm aware of) is the (marked transitional) optional Omero metadata. Getting to a single, non-transitional space for named channels would be great!

For multichannel data, there's often an array dimension that can only be interpreted by consulting another array, e.g. a 1D array of channel names, ["dapi", "gfp", "dsred"], or just ["channel_0", "channel_1", ...].

One of the interesting questions to me is whether the core spec should "just" have a list like this associated to channels or slightly more complex objects similar to the current omero objects. I could see a case made that "just" a list of strings is core and any more complex metadata about those channels is a potential extension that can then refer to the channels by name.

[lubianat]

@d-v-b

this structure -- one array requires another dimensionally-aligned array for its interpretation -- is not specific to multichannel data.

Thanks, I had not thought about that. If you have links, I'd love to read more on how other specs handle it. Do you have a concrete suggestion of how to not make it specific to channels?

and @jluethi

whether channel identifiers for image processing count as structural information

yes! I am broadly thinking as "structural" anything that directly affects storage/retrieval of the bytes (i.e., getting it wrong means messing up viewing/analysis/conversion etc)

[d-v-b]

Thanks, I had not thought about that. If you have links, I'd love to read more on how other specs handle it.

I would look at the relevant section of the CF conventions: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/cf-conventions.html#discrete-axis.

Do you have a concrete suggestion of how to not make it specific to channels?

yes, I would formally define how two arrays can be related along one or more co-equal axes. in netcdf / xarray these relationships are implicitly derived from the structure of individual zarr arrays in a zarr group. yall might want something more explicit, but it doesn't need to be super complex, just a rule that defines how the axes of different arrays can be associated. I would also consider allowing inline JSON arrays instead of separate zarr arrays, for simple cases like RGB data. The metadata might look like this:

// inline JSON array
"coordinate_arrays": {
   "channel": { // the key here is the name of the relationship
     "array": ["name", "of", "channels"],
     "dimension_names" : ["channel"] // this would match an element of the image array's dimension_names attribute
  }}

or

// external zarr array (e.g., with string data type)
// at least one element from the dimension_names attribute of that array would match the dimension_names element
// of the image array
"coordinate_arrays": {"channel": {"path": "channels"}} // names an array named "channels" in the same namespace as the bearer of this metadata

I would then define some kind of scheme that clearly instructs visualization applications to treat a channel axis as a channel axis. This can take a variety of forms, but you could also reserve a relationship name "channel"

and application that doesn't care about multichannel visualization can still use this metadata -- it would treat the literal channel names as labels for elements along the channel axis of the image array. an application that does care about multichannel visualization would use the channel names as keys. This way, the "this axis is described by a coordinate array" concern is largely separated from the "this image has import per-channel metadata". They relate via a very small contact patch: the elements of the coordinate array act as a set of keys, which any consumer can use. For must use cases, a single channel identifier should only appear once in the coordinate array, but that constraint should be critically evaluated.

[jburel]

@lubianat I will avoid embedding directly the rendering metadata in the channel metadata spec itself. We may want to revisit #78.
The grouping of channels is also important for images with very large number of channels (in that case a color is assigned to a group of channels). Different levels to consider

[lubianat]

@jburel thanks!

I agree rendering is a huge work packages on its own, and indeed involves many other aspects.

My current thought for avoiding endless dicussions would be just moving omero.channels to a channels field.

So for this RFC, we perhaps avoid new decisions on rendering metadata an just create a home for channel-specific metadata without being under omero?

[d-v-b]

One of the interesting questions to me is whether the core spec should "just" have a list like this associated to channels or slightly more complex objects similar to the current omero objects. I could see a case made that "just" a list of strings is core and any more complex metadata about those channels is a potential extension that can then refer to the channels by name.

I would definitely start here, and see if the core needs anything more than:

• a way to generate a canonical list of channel identifiers
• a way to associate a channel identifier with an element along an axis of an image

then non-core stuff can work with the channel identifiers + the assumption that an implementation knows how to relate a channel identifier to a selection of an array.

something else worth considering: some arrays might pack different channels into the data type of the array, instead of using an extra array dimension. yall could handle this option, or require that channels be done with extra dimensions.

[lubianat]

Moving the last comments to here from #173 to try and keep #173 for user stories. trying to center design/scoping discussions here

jo-mueller

Some 2or3cts from my side:

The first idea that came to my mind to make this a bit nicer, was to add the channels metadata directly where the channels are described, i.e. in the axes metadata, which would look something like this:

{
  "name": "physical",
  "axes": [
    {
      "name": "c",
      "type": "channel",
      "channels": [
        {
          "name": "DAPI",
          "type": "fluorescent",
          "color": "#808080",
          ...
          }
      ]
    },
    {
      "name": "z",
      "type": "space",
    }
  ]
}

which would be neat in the sense that the channel information sits directly adjacent to where the existence of a channel dimension is declared in the first place.

But:

• images need not necessarily have a channel dimension (brightfield is single-channel with no extra channel dimension) but one would still want to declare the channel somewhere. The channel axis doesn't exist in this case, so that's not an option.
• The other argument against plugging channel info into the axis metadata comes from a coordinate transform point of view: If you have two coordinate systems with a simple translation in-between, would you need to declare the full channel metadata in both? Duplication is undesirable, so one would declare the channel metadata elsewhere and reference it here.

Which brings us back to the status quo: The channel information is fundamentally tied to the image in a semantic sense, and not subject to reordering from a coordinate transform. Maybe we'd need to say this somewhere: coordinate transformations are not defined for dimensions of "discrete": true and transforms MUST fall back to default values for such dimensions (i.e. 1.0 for scale, 0.0 for translate, etc) This would make sure that transforms don't reorder the channel dimension or do other weird things along this axis.

So...I think this brings us to the path of replacing the omero metadata by a proper "channels" attribute, which should sit under the multiscales metadata (or in the attributes of an MultiscaleNode in a post-RFC8 world). There we could collect from the omero metadata what feels useful and enrich it with what's missing? I.e., wavelengths, dye, name, color and brightness, etc.

d-v-b

I highly recommend making the decisions about how to logically organize this information by thinking about the different consumers of it.

• Labels for a discrete axis (like channels, but also many other things) would be consumed by any application that wants to faithfully represent the basic structure of the data, and support label-based lookup of data values (e.g., a software that allows the user to index data using axis labels instead of plain integers). Software at all layers of the stack -- from CLIs to rich GUIs -- could use this.
• Instructions for rendering a particular view of the data (e.g., the color field above). First, this is not channel-specific: folks might use these instructions for segmentation data, or any other data with a discrete axis. Second, I would argue that "how to display this on a screen" narrowly relevant to a small subset of (very important) consumers, namely image visualization tools, and even then I worry that different visualization tools have different models for this kind of information. Some tools take a color string, but other tools like neuroglancer are much more expressive and can take raw shader code as a definition of how data should be rendered.

Another important point about rendering settings: it's definitely important to store metadata about how visualization tools should display data. But I don't think this is an attribute of a single image. It's an attribute of at least one view of an image. That distinction matters because people often combine separate images (like combining multiple segmentations over the raw data). For openorganelle, information about rendering was stored at the image collection level as an array of "views". We needed this because we found that even a single image might need different contrast limits in different regions, and when overlaying multiple images, we might use differnent colors per image depending on the number of images in the view. If two images (or two channels) claim the color blue, then you simply can't overlay them. So we solved this by picking rendering settings based on everything we knew about a view -- which images, how far zoomed in, etc. If ome-zarr approaches this by binding single rendering settings to entire images, then it will create a lot of complexity for folks trying to create multi-image scenes. I would avoid this if possible.

will-moore

Yes, even in OMERO we store multiple rendering settings per Image. Users only see 1 per user, but it's possible to store multiple settings per user.
I think there's a distinction between what the channel is (aquisition metadata) and how to view it (rendering settings)

d-v-b

3h ago

I think there's a distinction between what the channel is (aquisition metadata) and how to view it (rendering settings)

💯 and these have distinct (but overlapping) consumers.

[lubianat]

From #173:

@jo-mueller

I think there's a distinction between what the channel is (aquisition metadata) and how to view it (rendering settings)

Completely agree and I think this discrimination will be a good ruler to judge where a piece of metadata should go.

Re how to view it: People discussed a rendering RFC at a recent Hackathon in Heidelberg that would contain something like a viewer frustum and collected a lot of ideas around it. I think this is quite similar to the concept of coordinate systems? I.e. getting the same rendered view will need the same camera setting AND coordinate system. Currently, the omero metadata has a bit of both, I suppose.

[d-v-b]

Re how to view it: People discussed a rendering RFC at a recent Hackathon in Heidelberg that would contain something like a viewer frustum and collected a lot of ideas around it.

that's a useful example because some viewers may require a frustum specification and others (e.g., ones that don't fully believe in the third dimension) will not be able to use it at all. So this could be an area to mark as extensible, so different applications can define what they need.

[lubianat]

what about something for channels like:

{ "ome": 
  { "multiscales": [...], 
    "indexed_axes":
         { "channels": 
           [
             {
                "tags": ["phase-image", "label-free"], // Optional
                "name": "Phase", 
                "index": 0,
                "description": "Quantitative phase imaging, label-free"  // Optional
             },
            {
                "tags": ["nuclei", "h2b-gfp"], // Optional
                "name": "H2B-GFP",
                "index": 1,
                "description": "Histone-Green Fluorescent Protein fusion protein (H2B-GFP)", // Optional
                "curies": ["uniprot:B4DR52"]
            }
         ],
       }
   }
}

tags match n:1, i.e."getChannelsByTag("tag") --> list, so it can be used for e.g. channel grouping, if needed
curies does the same as slugs, but allows standardized terms to be used broadly (as mentiond by @keller-mark here).
name required to be unique, so it becomes the canonical identifier, 1:1, "getChannelByname("Phase")

And other things (rendering, specimen, acquisition parameters...) as extensions in a second step, but using this dedicated space where necessary.

Details

This is basically the initial part of the [DCA channel spec](https://chanzuckerberg.github.io/dynamic-cell-atlas-specs/v0.2/dca-metadata.html), with a top level "indexed_axes".

The top-level "indexed_axes" indicates for which axes there are named elements (or perhaps element sets/ranges), so one extension could use it for (use case example by @joshmoore) , say:

"indexed_axes": 
{ "timepoints": // Separate spec/extension 
      [ 
        {"slugs": ["perturbation", "laser ablation"],
          "name": "laser-ablation" ,
         "index_range": {"start": 10, "end": 20},
         "description": "During these timepoints, laser ablations was being performed to etc etc etc. "
        }
    ] 

in this case the mapping of "channels" or "timepoints" to the axis of type:channel would be hard coded in the spec (i.e. not configurable).

[lubianat]

to @jo-mueller's point

images need not necessarily have a channel dimension (brightfield is single-channel with no extra channel dimension) but one would still want to declare the channel [metadata]

I think we could have something like "unbound": true or "whole_array":true to signal that the "axis" is unbound/implicit/better_term_here in these cases

So the presence of an "indexed_axes.channels" of len() = 1 is valid even in the absence of an axis of type:channel

[jluethi]

To summarize something here I discussed with multiple people separately:
I'd see a lot of potential to have a very narrow definition of channel identifiers be part of the core, while all the other topics (rendering settings, acquisition metadata, other channel metadata) should be delegated to other metadata e.g. RFC-8 based extensions. If the core defines a unique identifier for channels, then all those extensions have a clear way to refer to a channel of interest.

Basically @d-v-b 's point from above if I understood that correctly:

I would definitely start here, and see if the core needs anything more than:

a way to generate a canonical list of channel identifiers
a way to associate a channel identifier with an element along an axis of an image

---

For scoping, that would then make clear what is a core channel identifier discussion, what's part of a rendering metadata extension, what's part of an acquisition metadata extension. That doesn't mean we'd need to wait with the rendering discussion until everything for core channel definitions is finished and released, just that we'd agree to make them relative to however the identifiers are defined.

If within the rendering extension, we can find a core set of rendering parameters that many viewers will care for: Amazing! Then we can agree on a shared extension that multiple viewers understand. And maybe there's an effort to even declare some rendering extension core.
But if agreement on rendering specs is very complex, I'd much prefer to be in a world where 6 viewers have 4 documented extensions with relevant channel metadata (and maybe some viewers understand 2-3 of them?) than one where everyone adds the necessary rendering metadata somewhere else outside the OME-Zarr context (because it needs to actually be saved and we can never agree on some advanced features that may literally be viewer specific).

[keller-mark]

I think it would be fine to reduce the scope like this, and delegate everything else to rendering extensions. I would argue that this core should be extended to:

• channel identifiers (must be unique per channel)
• photometric interpretation
  • either as its own field (like the OME-XML PhotometricInterpretation or the current omero.rdefs.model), or at a minimum, a requirement that RGB images specify certain channel identifiers like ["R", "G", "B"]
• mechanism to define zero or more ontology ID (+ontology version?) + ontology term per channel