Skip to content

Plot datasets against their HDF5 dimension scales - #2035

Open
NAThompson wants to merge 1 commit into
silx-kit:mainfrom
NAThompson:feat/hdf5-dimension-scales
Open

Plot datasets against their HDF5 dimension scales#2035
NAThompson wants to merge 1 commit into
silx-kit:mainfrom
NAThompson:feat/hdf5-dimension-scales

Conversation

@NAThompson

Copy link
Copy Markdown

H5Web derives plot axes only from NeXus NXdata metadata. A file that labels its axes the native HDF5 way -- make_scale() plus attach_scale(), which writes DIMENSION_LIST on the dataset and REFERENCE_LIST on the scale -- gets no axis at all, and is plotted against the integer sample index instead.

That is a real loss of information rather than a cosmetic one. A non-uniformly sampled abscissa cannot be recovered from indices, so the plot is not merely unlabelled but wrong in shape: support/sample/create_dimension_scales_sample.py generates t*sin(1/t) on a time axis whose spacing spans four orders of magnitude, which the index axis renders as a completely different function. Dimension scales are also how NetCDF4 and h5py users label axes by default, so the affected set is large. Today the only workaround is to duplicate the data into hand-written NXdata groups, which is the redundancy #1313 exists to remove.

That fixture is a separate file rather than a group in sample.h5 for two reasons: sample.h5 is snapshotted by both the h5wasm and h5grove provider tests, which inline every root dataset's value and assert that every root child is a dataset; and shrinking the data enough to keep those snapshots readable would leave nothing to demonstrate, since the point is the spacing ratio.

Scale resolution sits behind a new optional getDimensionScales on DataProviderApi, implemented here for h5wasm, which can lean on libhdf5 to dereference DIMENSION_LIST. h5grove and HSDS are untouched and keep plotting against indices; both would need server-side support first. Labels need none of this, since DIMENSION_LABELS is a plain attribute: a dimension can be named even when no scale is attached.

Where HDF5 permits more than H5Web can show: the first usable of several scales on a dimension wins, so a dimension carrying N+1 bin boundaries next to N centres still gets an axis; a scale that is not 1D, or whose length differs from its dimension, falls back to the index axis rather than erroring, which the spec leaves to the application; the dimension label beats the scale's own name, as #1435 did for NeXus long_name; and NeXus is untouched, so it still takes precedence. Failing to resolve the scales at all degrades the same way, so a dataset that used to plot against indices never becomes unviewable over an axis it did not have before.

Scales are resolved in the vis container and their values fetched under VisBoundary, mirroring how the NeXus pack splits metadata from values. That split is load-bearing rather than stylistic: prefetching under a boundary that has already suspended would set the values store's progress state while the mounted loader is subscribed to it, which React reports as updating one component while rendering another. usePrefetchValue runs ahead of the resolution so the dataset's own values load alongside the scales, and each dimension's scale metadata and attributes are prefetched as a batch rather than one round trip per dimension.

H5Web derives plot axes only from NeXus `NXdata` metadata. A file that labels
its axes the native HDF5 way -- `make_scale()` plus `attach_scale()`, which
writes `DIMENSION_LIST` on the dataset and `REFERENCE_LIST` on the scale -- gets
no axis at all, and is plotted against the integer sample index instead.

That is a real loss of information rather than a cosmetic one. A non-uniformly
sampled abscissa cannot be recovered from indices, so the plot is not merely
unlabelled but wrong in shape: `support/sample/create_dimension_scales_sample.py`
generates `t*sin(1/t)` on a time axis whose spacing spans four orders of
magnitude, which the index axis renders as a completely different function.
Dimension scales are also how NetCDF4 and h5py users label axes by default, so
the affected set is large. Today the only workaround is to duplicate the data
into hand-written `NXdata` groups, which is the redundancy silx-kit#1313 exists to
remove.

That fixture is a separate file rather than a group in `sample.h5` for two
reasons: `sample.h5` is snapshotted by both the h5wasm and h5grove provider
tests, which inline every root dataset's value and assert that every root child
is a dataset; and shrinking the data enough to keep those snapshots readable
would leave nothing to demonstrate, since the point is the spacing ratio.

Scale resolution sits behind a new optional `getDimensionScales` on
`DataProviderApi`, implemented here for h5wasm, which can lean on libhdf5 to
dereference `DIMENSION_LIST`. h5grove and HSDS are untouched and keep plotting
against indices; both would need server-side support first. Labels need none of
this, since `DIMENSION_LABELS` is a plain attribute: a dimension can be named
even when no scale is attached.

Where HDF5 permits more than H5Web can show: the first *usable* of several
scales on a dimension wins, so a dimension carrying N+1 bin boundaries next to N
centres still gets an axis; a scale that is not 1D, or whose length differs from
its dimension, falls back to the index axis rather than erroring, which the spec
leaves to the application; the dimension label beats the scale's own name, as
silx-kit#1435 did for NeXus `long_name`; and NeXus is untouched, so it still takes
precedence. Failing to resolve the scales at all degrades the same way, so a
dataset that used to plot against indices never becomes unviewable over an axis
it did not have before.

Scales are resolved in the vis container and their values fetched under
`VisBoundary`, mirroring how the NeXus pack splits metadata from values. That
split is load-bearing rather than stylistic: prefetching under a boundary that
has already suspended would set the values store's progress state while the
mounted loader is subscribed to it, which React reports as updating one
component while rendering another. `usePrefetchValue` runs ahead of the
resolution so the dataset's own values load alongside the scales, and each
dimension's scale metadata and attributes are prefetched as a batch rather than
one round trip per dimension.

Towards silx-kit#1313.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant