Allow Custom Indexes to define HTML repr for managed coords

[ianhi]

Is your feature request related to a problem?

When a complicated index is attached to a dataset it can potentially fill up the coords field with lots of extra low value information. For example for the builtin multiindex the xarray version looks like this:

which is lower signal to noise than the equivalent pandas repr:

or in the case of layered intervals annotating a dimension (https://ianhuntisaak.com/xarray-linked-indexes/) the coords can really get out of hand

Describe the solution you'd like

Allow Indexes to override the default html repr for any coords that they manage. The dataset repr can compose itself out of the reprs for coords from coords, so the would be in charge of returing the html +/- css for those coords

I think the built in multindex could be a nice example use case of this.

Describe alternatives you've considered

No response

Additional context

No response

cc @benbovy @keewis @dcherian

[benbovy]

The repr of the builtin PandasMultiIndex could be improved indeed. Although not done yet, I think the plan is still to eventually remove the multiindex dimension coordinate (i.e., x(x) in the example above) along with deprecating a few other multiindex special cases, so the repr would be more consistent with the pandas repr.

Besides your linked indexes example, a good example of coordinate clutter is the representation of geometries in the CF conventions where no less than six distinct variables are used to represent a single sequence of polygon geometries: vertices, offsets, interior rings, dummy "scalar" variable... cf-xarray and xvec solve this problem by encoding the geometries as shapely objects stored in a single dimension coordinate and vice-versa. This is done via the helper functions encode_geometries() / decode_geometries() in cf_xarray and encode_cf() / decode_cf() in xvec: see an example here.

IMHO the approach used by cf-xarray and xvec is preferable than allow an Xarray index overriding the repr of its coordinates. The latter would give extra-power to 3rd-party Xarray indexes (they already have a lot), which could really go off the rails. Even though Xarray indexes and coordinates are closely related, it is also best to keep them distinct to each other, e.g., avoid .set_xindex() and .drop_indexes() having any major visible effect on the coordinate variables of a dataset or dataarray.

Looking at your linked indexes example, I guess you could already remove a good amount of coordinate clutter by hiding the onset and duration information under the hood of the Xarray DimensionInterval index, assuming that users don't really need to directly interact with this information. Like cf-xarray and xvec, you could also provide some helper functions to decode (encode) the onset and duration data to (from) coordinate variables, which is useful for I/O serialization.

[ianhi]

Thanks for the thoughts @benbovy. I've thought on this a bit, and also done effectively another user case study on a long zoom with @prlabu working out how to most effectively work with iEEG data in xarray. Combined I have some further thoughts, and would encourage Latané to chime in as well.

good example of coordinate clutter is the representation of geometries in the CF conventions where no less than six distinct variables are used to represent a single sequence of polygon geometries: vertices, offsets, interior rings, dummy "scalar" variable... cf-xarray and xvec solve this problem by encoding the geometries as shapely objects stored in a single dimension coordinate and vice-versa

I guess you could already remove a good amount of coordinate clutter by hiding the onset and duration information under the hood of the Xarray DimensionInterval index, assuming that users don't really need to directly interact with this information

The last bit here is the key difference I think. For those geometries the shapely object is really the irreducible unit that a user might want to work with. Whereas with the cases I'm thinking about here direct access to the onset or duration values is crucial. This also extends further with other more complicated annotations of the data.

e.g. @prlabu has complex annotation dataframes with values such as sentence and last_phoneme and others. Many of which are necessary to directly access at various points.

Having spent a while looking at @prlabu's datasets (annotations on top of EEG data) I suspect that a crucial difference in use case here between bio/med and geo data is how important being able to directly inspect the coordinates is. In bio/med applications being able to scroll through the full annotation table and look at the relationships can be quite helpful. In a way that I suspect (but am not sure!) is less true for e.g. a lat/lon coord system.

For example @prlabu regularly uses the vscode datawrangler to inspect the annotation dataframe. Moving to xarray will require switching that dataframe into coords which currently comes at a high cost of visualization of the annotations/coords.

To convince @prlabu users like him to move to xarray (which has real benefits for these use cases!) I need to find a way to wherein the advantages do not come at the cost of much worse exploratory/viz tooling for coords.

Even an API to allow overriding the default html repr with a custom one might be sufficient

the latter would give extra-power to 3rd-party Xarray indexes (they already have a lot), which could really go off the rails.

hahaha fair enough. Though a question I have is what's the failure mode we are worried about here. The burden seems fully on the 3rd-party index to be well behaved.

Even though Xarray indexes and coordinates are closely related, it is also best to keep them distinct to each other, e.g., avoid .set_xindex() and .drop_indexes() having any major visible effect on the coordinate variables of a dataset or dataarray.

This was really clarifying for me thank you! A big part of the issue here is that I am using an index to implicitly define a relationship between coordinates. In the case of coords sharing dimension then there could be a more full featured viz built in that is not dependent on the index. In these interval use cases the information about the relationship is only contained within the index, so I don't think it's too terrible for drop_indexes to have a significant visible effect because that would reflect the significant change in available information.

[prlabu]

Thanks @ianhi . Yes, big downside for me in moving to xarray is the loss of nice viz/inspection tools to look at the relationship between different coords.

In cognitive neuroscience EEG we often start with channels x time recordings, then eventually [epoch] the data (https://mne.tools/stable/generated/mne.Epochs.html) into trials (see mne-python for our field-specific standard tooling). We have a channels/electrodes table where each row represents an channels and we have tons of columns about the channel recording location, whether the channel was task-activated, the quality of the recording at the channel, and others. It's important for me to be able to visualize them as a table rather than being split up into coords in the visualization of a ds in xarray: quality(channel), mni_x(channel), is_activated(channel). After epoching, we have a trial x channels x time datacube. We have a trials table which has a row for each trial and columns for task condition and various other things (often 10+ columns): again, when visualizing a ds, my trial-related variables are split up into coords that are hard to inspect: stimulus_onset(trial), speech_onset(trial), condition_AB(trial), condition_XY(trial). Here, too, I want to visualize all the coordinates associated with the trial dim in one table.

One easy solution (I think, I'm new here so I could be off base) would be to have a simple function that detect all 1d coords associated with a dimension of a ds and compiles them into a pandas df such that we could use all pandas viz tools.

[benbovy]

Thank you @ianhi and @prlabu for the additional context, which is very useful to better understand your needs.

It's important for me to be able to visualize them [the columns] as a table rather than being split up into coords in the visualization of a ds in xarray

This seems to be the key thing here.

One easy solution (I think, I'm new here so I could be off base) would be to have a simple function that detect all 1d coords associated with a dimension of a ds and compiles them into a pandas df such that we could use all pandas viz tools.

Yes that is likely the easiest solution! If the Xarray Dataset already has a DimensionInterval index associated with all the time + channels coordinates, it is straightforward to detect the relevant coordinates and extract them into a dataframe.

For example @prlabu regularly uses the vscode datawrangler to inspect the annotation dataframe.

The 3rd-party dataframe fancy visualization tools vs. the builtin pandas.Dataframe basic (html) repr is a good reference! IMO there are good reason to keep the builtin repr basic and "boring" (easier maintenance, stick with static HTML/CSS implementation, tidy repr for the simple cases...) and provide advanced visualization capabilities in separate tools.

That was my motivation with https://github.com/benbovy/xarray-fancy-repr, which currently mimics the built-in Xarray object reprs but implemented using react components and https://github.com/manzt/anywidget. Although not yet implemented, this opens up a lot of possibilities for advanced and interactive exploration of Xarray data cubes, dealing with large data, etc. ! We could for example imagine adding some UI elements to show a parametrized & interactive "table view" of the data cube (by specifying one or more dimensions), among many other things.

Another option that works with the current, builtin Xarray reprs is to implement DimensionInterval._repr_inline_, DimensionInterval.__repr__ and/or DimensionInterval.__repr_html__. Xarray just shows whatever is returned from those functions, so it is fully customizable. Compared to the custom coordinate repr solution proposed here, one downside is that users would need to scroll and maybe expand the "indexes" section of the Dataset repr, and then expand the DimensionInterval index's full repr by clicking on the "database icon".