[tompollard]

Follow-up to #541, which added .wfdb archive files for single-segment records. This adds support for multi-segment records.

Changes

1. Multi-segment records in archives. The archive of a multi-segment record holds the main header together with the header and signal files of each segment.
   • rdrecord, rdsamp and rdheader (with rd_segments=True) read the segments from the same open archive. This covers fixed and variable layouts, empty segments (~), sample ranges, channels, channel_names and m2s=False.
   • MultiRecord.wrsamp takes a wfdb_archive argument and writes the whole record into one archive.
   • An archive still holds a single record. It can contain several headers only if one is a multi-segment header that lists all the others as its segments (including the layout header). This is now checked when the archive is closed, so files can be added in any order, and an archive that breaks the rule is not saved. Finding the main header takes linear time in the number of segments, whatever order the headers were added in.
   • Segments can share a signal file (as in sample-data/multi-segment/fixed1), so writing a file that is already in the archive is allowed if the content is the same.
   • Small fix: reading a fixed-layout record with channel_names now takes the signal names from the first non-empty segment, as the code intended, instead of the first segment, which can be empty.
2. Writing variable layout records. This fixes an existing bug that also affects writing to normal files. MultiRecord.wrsamp failed for variable layout records, such as those read with rdrecord(..., m2s=False). The layout header lists its signals as null signals (format 0, file name ~), which the header validation rejected, and Record.wrsamp tried to compute checksums and write .dat files for signals without samples. Null signals are now accepted, and only the header is written for a record whose signals have no files.
   • set_defaults() no longer fails for null signals: they get the WFDB library's default resolution (12 bits), so a variable layout record created from scratch can be written too. A record that mixes null signals with signals that have samples is rejected with a clear error.

Example

import wfdb
from wfdb.io.archive import create_archive

# Write a multi-segment record into an archive
record = wfdb.rdrecord(
    "sample-data/multi-segment/s25047/s25047-2704-05-04-10-44",
    m2s=False,
    physical=False,
)
record.wrsamp(wfdb_archive="s25047.wfdb")

# Read it back, as a single record or as segments
signal = wfdb.rdrecord("s25047.wfdb", channel_names=["ABP", "II"])
segments = wfdb.rdrecord("s25047.wfdb", m2s=False)
header = wfdb.rdheader("s25047.wfdb", rd_segments=True)

Tests

• Records read from archives are compared with the same records read from files, for the fixed and variable layout samples in sample-data/multi-segment. This includes sample ranges, channel selection and m2s=False.
• Multi-segment records written into archives read back the same as the original files, and contain exactly the record's files.
• Error cases: a missing segment, and an archive with a header that isn't one of the record's segments.
• test_record.py has new tests that write a variable layout record to files and read it back (one read from sample-data, one created from scratch), and that check the error for a record that mixes null signals with other signals.
• An archive whose main header was added last is read correctly.

p000878 isn't used in the archive tests, because one of its segments is not included in sample-data.

[lukepayyapilli]

Thanks Tom, checked 0af27fe2 locally, merged with current main. The offline tests pass (294), ruff check and ruff format --check are clean, and CI is green.

• Round trips: fixed1, 041s, s00001 and s25047 all read back from an archive the same as from the files, both when written with MultiRecord.wrsamp(wfdb_archive=...) and when built with create_archive, for full reads and sample ranges across segment boundaries.
• Shared signal files: with one segment of fixed1 changed so its share of v102s.dat differs, the archive write fails with the "different content" error and the existing archive at that path is left unchanged. Writing the same record to a directory silently overwrites v102s.dat (so segment 1 ends up with segment 3's samples). That behaviour predates this PR, and the archive check is an improvement on it.
• Tests: removing BIT_RES["0"], the mixed null-signal check or the skip for re-written identical files each makes tests fail. The fixed-layout channel_names change isn't covered, but per header(5) fixed-layout segments always contain samples, so it only guards against invalid input.

Approving.

[tompollard]

thanks luke!