Allow writing variable layout multi-segment records.

The layout header of a variable layout multi-segment record lists its
signals as null signals (format 0, file name '~'), with no samples.
Writing such a record failed: the header validation rejected format 0
and the file name '~', and Record.wrsamp tried to compute checksums and
write dat files for signals with no data.

Null signals are now accepted (file name '~' together with format 0),
and only the header is written for a record whose signals have no
files. This applies to records written to files as well as to .wfdb
archives.

Author: tompollard

docs/changes.rst

@@ -26,6 +26,9 @@ Unreleased
 **Read and write .wfdb archive files**
   A record can be stored in a single ``.wfdb`` archive file (a ZIP file containing the header and signal files). ``rdrecord``, ``rdsamp``, ``rdheader`` and ``rdann`` read a record or its annotations from an archive when given the path of the archive, and ``wrsamp`` writes a record into an archive with the new ``wfdb_archive`` argument. Multi-segment records are supported, with all their segments stored in the same archive.
 
+**Write variable layout multi-segment records**
+  ``MultiRecord.wrsamp`` can now write variable layout multi-segment records, such as those read with ``rdrecord(..., m2s=False)``. Previously, writing the layout header failed because its signals have no samples (format ``0``, file name ``~``).
+
 Version 4.3.1 (Feb 2026)
 -----------------------------
 

src/wfdb/io/record.py

@@ -451,9 +451,13 @@ def check_field(self, field, required_channels="all"):
                         continue
 
                 if field == "file_name":
-                    # Check for file_name characters
+                    # Check for file_name characters. A null signal (format
+                    # 0), as in the layout header of a variable layout
+                    # multi-segment record, has no file and uses '~'.
                     accepted_string = re.match(r"[-\w]+\.?[\w]+", item[ch])
-                    if not accepted_string or accepted_string.string != item[ch]:
+                    if item[ch] == "~" and self.fmt[ch] == "0":
+                        pass
+                    elif not accepted_string or accepted_string.string != item[ch]:
                         raise ValueError(
                             "File names should only contain alphanumerics, hyphens, and an extension. eg. record-100.dat"
                         )
@@ -463,7 +467,11 @@ def check_field(self, field, required_channels="all"):
                             "Signals in a record that share a given file must be consecutive."
                         )
                 elif field == "fmt":
-                    if item[ch] not in _signal.DAT_FMTS:
+                    # Format 0 is a null signal, which has no samples and
+                    # no file
+                    if item[ch] == "0" and self.file_name[ch] == "~":
+                        pass
+                    elif item[ch] not in _signal.DAT_FMTS:
                         raise ValueError(
                             "File formats must be valid WFDB dat formats:",
                             _signal.DAT_FMTS,
@@ -894,10 +902,17 @@ def wrsamp(self, expanded=False, write_dir="", wfdb_archive=None):
         N/A
 
         """
+        # A record whose signals have no files, such as the layout header
+        # of a variable layout multi-segment record, has no samples:
+        # only its header is written.
+        has_signal_files = self.n_sig > 0 and (
+            self.file_name is None or any(f != "~" for f in self.file_name)
+        )
+
         # Update the checksum field (except for channels that did not have
         # a checksum to begin with, or where the checksum was already
         # valid.)
-        if self.checksum is not None:
+        if self.checksum is not None and has_signal_files:
             checksums = self.calc_checksum(expanded=expanded)
             for ch, old_val in enumerate(self.checksum):
                 if old_val is None or (checksums[ch] - old_val) % 65536 == 0:
@@ -908,7 +923,7 @@ def wrsamp(self, expanded=False, write_dir="", wfdb_archive=None):
             # Perform field validity and cohesion checks, and write the
             # header file.
             self.wrheader(write_dir=write_dir, expanded=expanded, wfdb_archive=archive)
-            if self.n_sig > 0:
+            if has_signal_files:
                 # Perform signal validity and cohesion checks, and write the
                 # associated dat files.
                 self.wr_dats(

tests/test_archive.py

@@ -807,11 +807,24 @@ def test_archive_write_bytes_like(tmp_path, monkeypatch):
         assert zf.getinfo("array.dat").compress_type == zipfile.ZIP_STORED
 
 
-@pytest.mark.parametrize("record", ["fixed1/v102s", "041s/041s"])
-def test_multi_record_wrsamp_archive(record, tmp_path):
+@pytest.mark.parametrize(
+    "record, kwargs",
+    [
+        ("fixed1/v102s", {}),
+        ("041s/041s", {}),
+        ("s25047/s25047-2704-05-04-10-44", {}),
+        (
+            "s00001/s00001-2896-10-10-00-31",
+            dict(sampfrom=14428364, sampto=14428375),
+        ),
+    ],
+)
+def test_multi_record_wrsamp_archive(record, kwargs, tmp_path):
     """A multi-segment record written into an archive reads back like its files.
 
     In 'fixed1', all segments share one dat file, which is written to the archive once.
+    's25047' and 's00001' have a variable layout, with a layout header and empty
+    segments.
     """
     record_name = f"sample-data/multi-segment/{record}"
     archive_path = os.fspath(tmp_path / "multi.wfdb")
@@ -824,6 +837,7 @@ def test_multi_record_wrsamp_archive(record, tmp_path):
         assert sorted(zf.namelist()) == sorted(
             os.path.basename(path) for path in multi_record_files(record_name)
         )
-    record = wfdb.rdrecord(archive_path, physical=False)
-    expected = wfdb.rdrecord(record_name, physical=False)
-    np.testing.assert_array_equal(record.d_signal, expected.d_signal)
+    record = wfdb.rdrecord(archive_path, **kwargs)
+    expected = wfdb.rdrecord(record_name, **kwargs)
+    assert record.sig_name == expected.sig_name
+    np.testing.assert_array_equal(record.p_signal, expected.p_signal)

tests/test_record.py

@@ -1117,6 +1117,25 @@ def test_multi_variable_d(self, source):
             assert record.__eq__(record_pn)
         assert record.__eq__(record_named)
 
+    def test_multi_variable_write(self, tmp_path):
+        """Write a variable layout multi-segment record and read it back.
+
+        This includes its layout header and empty segments.
+        """
+        record_name = "sample-data/multi-segment/s25047/s25047-2704-05-04-10-44"
+        multi_record = wfdb.rdrecord(record_name, m2s=False, physical=False)
+
+        multi_record.wrsamp(write_dir=str(tmp_path))
+        layout = wfdb.rdheader(str(tmp_path / "3234460_layout"))
+        record = wfdb.rdrecord(str(tmp_path / "s25047-2704-05-04-10-44"))
+
+        expected = wfdb.rdrecord(record_name)
+        assert layout.sig_len == 0
+        assert layout.file_name == ["~"] * 3
+        assert layout.fmt == ["0"] * 3
+        assert record.sig_name == expected.sig_name
+        np.testing.assert_array_equal(record.p_signal, expected.p_signal)
+
 
 class TestTimeConversion:
     """Test cases for time conversion"""