Copy DataStub datasets through the backend writer

[ehennestad]

Motivation

Background — This PR is part of a series that makes the write path storage-agnostic (stacked on #867), so that a Zarr v3 writer can be added later.

Problem — When a file is read and then exported to a new file, datasets whose data still lives in the source file (types.untyped.DataStub) are copied over during export. This copy was done with raw HDF5 calls inside @DataStub/export.m: a check whether source and destination are the same file, a fast object copy, and a workaround that rewrites compound datasets containing references because an HDF5 library bug prevents copying them directly. All of this only works with the HDF5 backend, and a writer for another storage format cannot reuse any of it.

Solution — Move the copy into the writer. io.backend.base.Writer gains copyDatasetFromFile(sourceFilename, sourcePath, destinationPath), and the HDF5 code moves unchanged into io.backend.hdf5.HDF5Writer. DataStub.export now only calls this method. Re-exporting a read file behaves the same as before.

What changed

• New method copyDatasetFromFile(sourceFilename, sourcePath, destinationPath) on io.backend.base.Writer, implemented in io.backend.hdf5.HDF5Writer.
• types.untyped.DataStub.export contains no HDF5 calls and no writer.FileId access; it calls the writer method.
• Copy behavior is unchanged: nothing is copied when source and destination are the same file, or when the destination path already exists. Compound datasets containing references are still rewritten element by element.
• Fixed in passing: the old code did not close the source file id when it returned early on the same-file check. The moved code closes it.
• Added the new method to the expected-methods list in the base writer test.

Implementation notes

Ordinary datasets are copied with H5O.copy. Compound datasets containing references cannot be copied this way (HDFGroup/hdf5#3429), so they are read with io.parseCompound and written again through writeValue, as before. The base-class help states that an implementation may replace the raw copy with a rewrite when its storage layer cannot copy a dataset directly.

How to test

Read a file and export it to a new file; the data, which is still on disk in the source file, is carried over:

src = nwbRead('ref_demo.nwb', 'ignorecache');
nwbExport(src, 'ref_demo_copy.nwb');
copyRead = nwbRead('ref_demo_copy.nwb', 'ignorecache');
disp(copyRead.acquisition.get('ts').data.load().')

     1     2     3     4     5     6     7     8     9    10

(ref_demo.nwb is the file created in the test snippet of #867.)

Checklist

• Have you ensured the PR description clearly describes the problem and solutions?
• Have you checked to ensure that there aren't other open or previously closed Pull Requests for the same change?
• If this PR fixes an issue, is the first line of the PR description fix #XX where XX is the issue number?

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 94.11765% with 2 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (zarr-support/6-writer-reference-probe@7033673). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
+io/+backend/+hdf5/HDF5Writer.m	93.75%	2 Missing ⚠️

Additional details and impacted files

@@                           Coverage Diff                            @@
##             zarr-support/6-writer-reference-probe     #868   +/-   ##
========================================================================
  Coverage                                         ?   95.26%           
========================================================================
  Files                                            ?      234           
  Lines                                            ?     8315           
  Branches                                         ?        0           
========================================================================
  Hits                                             ?     7921           
  Misses                                           ?      394           
  Partials                                         ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.