Fix the Units waveforms test fixtures and assert the doubly indexed structure

[adityasingh2400]

Motivation

Addresses the test-fixture half of #2220. I have deliberately left misc.py and the waveforms_desc docstring alone so this does not conflict with #1936, which is already touching that text.

For the doubly indexed Units.waveforms column, add_unit interprets a 3-D per-unit input as (num_spikes, num_electrodes, num_samples). Dim 0 becomes waveforms_index_index, the spike events of a unit, dim 1 becomes waveforms_index, the waveforms of a spike event with one per electrode, and dim 2 is the samples of each waveform. That matches the schema, which says the waveforms_index column "indexes which waveforms in this column belong to the same spike event for a given unit, where each waveform was recorded from a different electrode" and the waveforms_index_index column "indexes the waveforms_index column to indicate which spike events belong to a given unit".

Both TestUnitsIO and TestUnitsWaveformsOnlyIO label these the other way round, with the outer dimension commented as electrodes and the middle one as spikes. Because of that the fixtures also contradict their own spike_times: TestUnitsIO declares 3 spike_times for each unit but encodes 2 spike events for the first unit and 3 for the second, and TestUnitsWaveformsOnlyIO declares 3 spike_times per unit but encodes 2 spike events. Neither test asserted anything about the waveforms columns, so nothing caught it.

Changes

Both fixtures are reordered to (num_spikes, num_electrodes, num_samples) so the number of spike events matches the number of spike_times, and the comments now describe what add_unit actually does. TestUnitsIO gets distinct sample values, 1 through 54, instead of the repeated [1, 2, 3] rows, so a transposed or mis-flattened write is detectable rather than looking identical.

A new test_waveforms_structure roundtrips the container and asserts waveforms_index_index, waveforms_index, and the 2-D waveforms dataset, plus the per-spike electrode counts. This is the first coverage of the doubly ragged structure of this column.

How to test the behavior?

Running the new assertions against the old fixture shows the inconsistency directly. The old first unit had 3 spike_times but only 2 spike events:

>       np.testing.assert_array_equal(waveforms_index_index.data[:], [3, 6])
E       AssertionError:
E       Arrays are not equal
E        [0]: 2 (ACTUAL), 3 (DESIRED)
E        [1]: 5 (ACTUAL), 6 (DESIRED)
E        ACTUAL: array([2, 5], dtype=uint8)
E        DESIRED: array([3, 6])

FAILED tests/integration/hdf5/test_misc.py::TestUnitsIO::test_waveforms_structure
1 failed, 16 deselected

With the corrected fixtures:

$ pytest tests/integration/hdf5/test_misc.py tests/unit/test_misc.py -q
61 passed, 662 subtests passed in 99.98s

The equivalent minimal repro of the ordering, on dev and unchanged by this PR:

import numpy as np
from pynwb.misc import Units

u = Units(name='units')
u.add_unit(spike_times=[0.], waveforms=np.arange(1 * 5 * 7).reshape(1, 5, 7))
wf = u['waveforms']
print(np.asarray(wf.target.target.data).shape)  # (5, 7)  -> (num_waveforms, num_samples)
print(list(np.asarray(wf.target.data)))         # [5]     -> 5 electrodes for the 1 spike event

Checklist

• Did you update CHANGELOG.md with your changes?
• Have you checked our Contributing document?
• Have you ensured the PR clearly describes the problem and the solution?
• Is your contribution compliant with our coding style? This can be checked running ruff check . && codespell from the source directory.
• Have you checked to ensure that there aren't other open Pull Requests for the same change?
• Have you included the relevant issue number using "Fix #XXX" notation where XXX is the issue number? By including "Fix #XXX" you allow GitHub to close issue #XXX when the PR is merged. This PR covers only part of Units waveforms dimension order is mislabeled in add_unit docstring and TestUnitsIO (actual order is (num_spikes, num_electrodes, num_samples)) #2220, so it references the issue without a closing keyword.