Describe raster windows with a gWCS built from per-exposure pointing

[nabobalis]

Each spectral window is now one SpectrogramCube with a gWCS built from the AUX pointing, roll and T_OBS time of every exposure:

• a single raster file or a sit-and-stare observation is a 3D cube;
• a multi-file observation is a 4D cube with a leading raster scan axis.

This replaces SpectrogramCubeSequence. docs/migration.rst shows the old and new versions of the common patterns, and the changelog/182.* fragments list the breaking changes.

Reviewing

The pieces that did not depend on the rewrite are already on main: #184 (minimum versions and figure hashes), #185 (SGMeta.observer) and #186 (negative indices, SJICube.fits_wcs). What is left is four commits, each of which passes the tests on its own:

1. Add a gWCS builder for raster windows (irispy/_spectrograph_wcs.py, with the tests that need no reader). This is where the coordinates come from, including sit-and-stare.
2. Read each spectral window into one SpectrogramCube: the reader, combining files along the scan axis, the cube class, and moving the tests, tutorial doctests and gallery examples to the new API.
3. Plotting: slider labels for the step and scan axes, axis positions, and nearest-neighbour images.
4. Migration guide.

What changes for users

• raster_slice(k) and split_rasters() give individual rasters. cube[0] now indexes the first array axis: raster step 0 on a single file, scan 0 on a combined cube.
• cube.fits_wcs is main's FITS-TAB WCS, built per file.
• cube.time gives the exposure times, with shape (scan, step) on a combined cube.
• cube.celestial_frame works on spectrograph cubes, as it already does on SJI cubes, and on any slice.
• Crops can use any subset of world coordinates: sky only, time only, steps only, or any combination. Sky crops respect each exposure's slit width. These partial crops need ndcube's crop-bounds hook (see below).
• Removed without deprecation: SpectrogramCubeSequence and IRISSequencePlotter.
• A window whose WCS cannot be built now raises an error naming the window and file, instead of being skipped with a log message.
• AUX rows with all-zero or non-finite pointing or PC values, or non-finite times, are interpolated from the neighbouring exposures with a warning, for rasters and sit-and-stare alike. Rows at either end are extrapolated from the two nearest good rows. A file whose rows are all unusable raises an error, except that an all-NaN exposure-time column falls back to the planned start times.
• The pixel scales of a rebinned cube, and so its radiometric calibration, are those of the native pixels. radiometric_calibration also accepts a cube that is already in units per second.

Coordinates

I compared the gWCS against main's FITS-TAB WCS on every exposure, several slit rows and 3 wavelengths. On 7 cached observations the largest difference is 1.25e-5″ and 0 non-finite values:

• a 400-step raster near the limb and a 320-step raster;
• a 99-file raster and an 8-file v34 raster;
• two sit-and-stares, with 1020 and 1600 exposures.

At the slit centre, each exposure matches the AUX XCENIX/YCENIX to 2.4e-10″. For sit-and-stare, the along-slit offsets equal CDELT2·dy·(PC3_2, PC2_2) to 5e-7″. Tests guard both at 0.01″ and 0.001″.

dkist picks each exposure's table row with np.round, which rounds half to even, so the far pixel edge of an even number of steps had no coordinates. The builder repeats the last table row, which makes those pixel corners finite. Every other coordinate is unchanged bitwise.

ndcube

Partial crops need ndcube's _get_crop_bounds hook. That hook isn't in a release yet, and it waits on sunpy/ndcube#977. Until then:

• the partial-crop tests skip, with a reason, on released ndcube;
• the devdeps and docs envs use nabobalis/ndcube@irispy-devdeps, which is ndcube main plus the hook, Fix crop world-object order for WCSes with non-contiguous components sunpy/ndcube#977, #979, #980 and #982. It carries upstream's v2.5dev tag, so it builds as ndcube 2.5.dev.

Known cost: plots across exposures are slow

dkist's varying celestial transforms loop over every exposure, and dkist 1.18.1 still does. The figures below are for the 1600-exposure sit-and-stare, main vs this branch:

Operation	main	this branch
axis_world_coords()	0.04 s	1.3 s
Default plot (slit × wavelength), plot+draw	0.18 s	0.30 s
Default plot, slider step	0.05 s	0.12 s
Exposure × slit image, plot+draw	0.09 s	7.9 s
Exposure × slit image, slider step	0.10 s	14.2 s

We are accepting this for the merge and will decide before the release. The fix is a vectorised _map_transform in dkist.

Tests

Every commit passes all of these environments, and none of them changes a figure. The counts are for the last commit:

• irispy-devdeps with remote data: 433 passed, including the doc tests.
• Released ndcube 2.4.2: 391 passed, with 42 skips shown in the summary (the 41 partial-crop tests and the remote-data test).
• Minimum versions (Python 3.12, astropy 8.0.0, ndcube 2.4.0 and the other declared minimums): 387 passed and the same 42 skips, without the doc tests.
• The strict docs build (-W) passes, and all 20 gallery examples run from commit 2 onwards.

Other notes

• Built on main at v0.9.1. It uses main's FITS-TAB builder unchanged.
• SpectrogramCube.axis_world_coords returns C-ordered Time arrays. It works around ndcube returning N-D coordinates transposed, together with an astropy bug that prints non-C-ordered Time arrays out of order (issue to follow).