Merge pull request #372 into main

This adds support for reading FLAC compressed signal files (indicated
by format codes 508, 516, and 524, which were added in libwfdb version
10.7.0.)

Reading FLAC files uses the Python soundfile package, which in turn
requires the libsndfile and libFLAC C libraries to be installed.
soundfile is now included as a dependency of wfdb; you can install it
even if you don't have libsndfile, but trying to 'import soundfile'
will fail in that case.  Consequently, wfdb will only try to import
soundfile when you actually try to read a FLAC signal file.

Note that most desktop Linux systems include libsndfile by default,
and the soundfile wheel packages include libsndfile binaries for
x86-64 Windows and Mac OS platforms.

Author: Benjamin Moody

.github/workflows/run-tests.yml

@@ -28,6 +28,10 @@ jobs:
         run: |
           python -m pip install --upgrade pip poetry
           pip install ".[dev]"
+      - name: Install libsndfile
+        if: startsWith(matrix.os, 'ubuntu')
+        run: |
+          sudo apt-get install -y libsndfile1
       - name: Run tests
         run: pytest
       - name: Validate poetry file
@@ -48,6 +52,7 @@ jobs:
                   python3-pandas \
                   python3-requests \
                   python3-scipy \
+                  python3-soundfile \
                   python3-pytest \
                   git
 

README.md

@@ -35,6 +35,8 @@ pip install wfdb
 poetry add wfdb
 ```
 
+On Linux systems, accessing *compressed* WFDB signal files requires installing `libsndfile`, by running `sudo apt-get install libsndfile1` or `sudo yum install libsndfile`.  Support for Apple M1 systems is a work in progess (see <https://github.com/bastibe/python-soundfile/issues/310> and <https://github.com/bastibe/python-soundfile/issues/325>).
+
 The development version is hosted at: <https://github.com/MIT-LCP/wfdb-python>. This repository also contains demo scripts and example data. To install the development version, clone or download the repository, navigate to the base directory, and run:
 
 ```sh

pyproject.toml

@@ -10,6 +10,7 @@ python = "^3.7"
 numpy = "^1.10.1"
 scipy = "^1.0.0"
 pandas = "^1.0.0"
+SoundFile = ">=0.10.0, <0.12.0"
 matplotlib = "^3.2.2"
 requests = "^2.8.1"
 pytest = {version = "^7.1.1", optional = true}

sample-data/flacformats.d0

@@ -0,0 +1,4 @@
+flacformats 3 200 499
+flacformats.d0 508 200/mV 8 0 -127 -484 0 sig 0, fmt 508
+flacformats.d1 516 200/mV 16 0 -32766 -750 0 sig 1, fmt 516
+flacformats.d2 524 200/mV 24 0 -8388605 8721 0 sig 2, fmt 524

sample-data/flacformats.d1

@@ -0,0 +1,7 @@
+mixedsignals 6 62.4725/999.56 14400
+mixedsignals_e.dat 516x4 200/mV 14 8192 0 24460 0 II
+mixedsignals_e.dat 516x4 200/mV 14 8192 0 19772 0 III
+mixedsignals_e.dat 516x4 200/mV 14 8192 0 22261 0 V
+mixedsignals_p.dat 516x2 16(800)/mmHg 12 2048 0 49347 0 ABP
+mixedsignals_p.dat 516x2 4096(0)/NU 12 2048 0 36026 0 Pleth
+mixedsignals_r.dat 516 4093(2)/Ohm 12 2048 0 35395 0 Resp

sample-data/flacformats.d2

@@ -218,6 +218,37 @@ def test_1f(self):
                             "Mismatch in %s" % name,
                         )
 
+    def test_read_flac(self):
+        """
+        All FLAC formats, multiple signal files in one record.
+
+        Target file created with:
+            rdsamp -r sample-data/flacformats | cut -f 2- |
+            gzip -9 -n > record-flac.gz
+        """
+        record = wfdb.rdrecord("sample-data/flacformats", physical=False)
+        sig_target = np.genfromtxt("tests/target-output/record-flac.gz")
+
+        for n, name in enumerate(record.sig_name):
+            np.testing.assert_array_equal(
+                record.d_signal[:, n], sig_target[:, n], f"Mismatch in {name}"
+            )
+
+        for sampfrom in range(0, 3):
+            for sampto in range(record.sig_len - 3, record.sig_len):
+                record_2 = wfdb.rdrecord(
+                    "sample-data/flacformats",
+                    physical=False,
+                    sampfrom=sampfrom,
+                    sampto=sampto,
+                )
+                for n, name in enumerate(record.sig_name):
+                    np.testing.assert_array_equal(
+                        record_2.d_signal[:, n],
+                        sig_target[sampfrom:sampto, n],
+                        f"Mismatch in {name}",
+                    )
+
     # ------------------ 2. Special format records ------------------ #
 
     def test_2a(self):

sample-data/flacformats.hea

@@ -196,6 +196,62 @@ def _test_binary(self, url, content, buffering):
             self.assertEqual(bf.tell(), len(content))
 
 
+class TestRemoteFLACFiles(unittest.TestCase):
+    """
+    Test reading FLAC files over HTTP.
+    """
+
+    def test_whole_file(self):
+        """
+        Test reading a complete FLAC file using local and HTTP APIs.
+
+        This tests that we can read the file 'sample-data/flacformats.d2'
+        (a 24-bit FLAC stream) using the soundfile library, first by
+        reading the file from the local filesystem, and then using
+        wfdb.io._url.openurl() to access it through a simulated web server.
+
+        This is meant to verify that the soundfile library works using only
+        the standard Python file object API (as implemented by
+        wfdb.io._url.NetFile), and doesn't require the input file to be an
+        actual io.FileIO object.
+
+        Parameters
+        ----------
+        N/A
+
+        Returns
+        -------
+        N/A
+
+        """
+        import soundfile
+        import numpy as np
+
+        data_file_path = "sample-data/flacformats.d2"
+        expected_format = "FLAC"
+        expected_subtype = "PCM_24"
+
+        # Read the file using standard file I/O
+        sf1 = soundfile.SoundFile(data_file_path)
+        self.assertEqual(sf1.format, expected_format)
+        self.assertEqual(sf1.subtype, expected_subtype)
+        data1 = sf1.read()
+
+        # Read the file using HTTP
+        with open(data_file_path, "rb") as f:
+            file_content = {"/foo.dat": f.read()}
+        with DummyHTTPServer(file_content) as server:
+            url = server.url("/foo.dat")
+            file2 = wfdb.io._url.openurl(url, "rb")
+            sf2 = soundfile.SoundFile(file2)
+            self.assertEqual(sf2.format, expected_format)
+            self.assertEqual(sf2.subtype, expected_subtype)
+            data2 = sf2.read()
+
+        # Check that results are equal
+        np.testing.assert_array_equal(data1, data2)
+
+
 class DummyHTTPServer(http.server.HTTPServer):
     """
     HTTPServer used to simulate a web server for testing.

sample-data/mixedsignals.hea

@@ -0,0 +1,65 @@
+from wfdb.io import _url
+
+
+def _open_file(
+    pn_dir,
+    file_name,
+    mode="r",
+    *,
+    buffering=-1,
+    encoding=None,
+    errors=None,
+    newline=None,
+    check_access=False,
+):
+    """
+    Open a data file as a random-access file object.
+
+    See the documentation of `open` and `wfdb.io._url.openurl` for details
+    about the `mode`, `buffering`, `encoding`, `errors`, and `newline`
+    parameters.
+
+    Parameters
+    ----------
+    pn_dir : str or None
+        The PhysioNet database directory where the file is stored, or None
+        if file_name is a local path.
+    file_name : str
+        The name of the file, either as a local filesystem path (if
+        `pn_dir` is None) or a URL path (if `pn_dir` is a string.)
+    mode : str, optional
+        The standard I/O mode for the file ("r" by default).  If `pn_dir`
+        is not None, this must be "r", "rt", or "rb".
+    buffering : int, optional
+        Buffering policy.
+    encoding : str, optional
+        Name of character encoding used in text mode.
+    errors : str, optional
+        Error handling strategy used in text mode.
+    newline : str, optional
+        Newline translation mode used in text mode.
+    check_access : bool, optional
+        If true, raise an exception immediately if the file does not
+        exist or is not accessible.
+
+    """
+    if pn_dir is None:
+        return open(
+            file_name,
+            mode,
+            buffering=buffering,
+            encoding=encoding,
+            errors=errors,
+            newline=newline,
+        )
+    else:
+        url = posixpath.join(config.db_index_url, pn_dir, file_name)
+        return _url.openurl(
+            url,
+            mode,
+            buffering=buffering,
+            encoding=encoding,
+            errors=errors,
+            newline=newline,
+            check_access=check_access,
+        )