[Bug]: Units.waveform_rate is not written to /units/waveforms sampling_rate

[ehennestad]

What happened?

While looking at how Units.waveform_rate is serialized, I noticed that PyNWB maps it onto the sampling_rate attribute of waveform_mean and waveform_sd, but not onto the sampling_rate attribute of waveforms.

The NWB schema defines sampling_rate on all three:

• /units/waveform_mean
• /units/waveform_sd
• /units/waveforms

However, in the current PyNWB export path, only waveform_mean and waveform_sd are populated from Units.waveform_rate.

This means that if a Units table contains waveforms but not waveform_mean or waveform_sd, then the waveform sampling rate does not appear to be serialized anywhere related to waveforms.

I'm not sure whether this is intentional, so I wanted to ask:

• Is there a reason waveforms.sampling_rate is not populated by the Units API/export mapper?
• If not intentional, should Units.waveform_rate also be written to /units/waveforms.attrs["sampling_rate"]?
• Should readback also consider waveforms.sampling_rate when reconstructing Units.waveform_rate?

Steps to Reproduce

from pynwb import NWBFile, NWBHDF5IO
from datetime import datetime
from dateutil.tz import tzlocal

nwbfile = NWBFile(
    session_description="desc",
    identifier="id",
    session_start_time=datetime.now(tzlocal()),
)

nwbfile.add_unit(
    spike_times=[0.1, 0.2, 0.3],
    waveforms=[
        [[1, 2, 3]],
        [[1, 2, 3]],
        [[1, 2, 3]],
    ],
)

nwbfile.units.waveform_rate = 30000.0

with NWBHDF5IO("test.nwb", "w") as io:
    io.write(nwbfile)

Then inspect /units/waveforms in the output file.

Traceback

No traceback. This is a schema/API/export consistency question.

Relevant code references

• src/pynwb/misc.py: Units.waveform_rate is defined on the container
• src/pynwb/io/core.py: export mapping only covers waveform_mean and waveform_sd
• src/pynwb/io/misc.py: readback only checks waveform_mean and waveform_sd
• src/pynwb/nwb-schema/core/nwb.misc.yaml: schema defines waveforms.sampling_rate

Environment

• Operating System: macOS
• Python Executable: Python
• Python Version: 3.12

[rly]

Good catch. I can't believe this has not come up yet.

Is there a reason waveforms.sampling_rate is not populated by the Units API/export mapper?

No. Looking back at the old PRs, I think this was accidentally missed when implemented Units.waveforms in pynwb

If not intentional, should Units.waveform_rate also be written to /units/waveforms.attrs["sampling_rate"]?

Yes

Should readback also consider waveforms.sampling_rate when reconstructing Units.waveform_rate?

Yes

@ehennestad Would you have bandwidth to make a PR to fix this?