ecgdatakit 2.0.2__tar.gz → 2.0.3__tar.gz

{ecgdatakit-2.0.2/src/ecgdatakit.egg-info → ecgdatakit-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ecgdatakit
-Version: 2.0.2
+Version: 2.0.3
 Summary: Multi-format ECG file parsing and signal processing library
 Author-email: Ahmad Fall <ahmad.fall@ird.fr>
 Maintainer-email: Ahmad Fall <ahmad.fall@ird.fr>

{ecgdatakit-2.0.2 → ecgdatakit-2.0.3}/src/ecgdatakit/__init__.py

@@ -1,6 +1,6 @@
 """ECGDataKit - Multi-format ECG file parsing and processing library."""
 
-__version__ = "2.0.2"
+__version__ = "2.0.3"
 
 from ecgdatakit.models import (
     AcquisitionSetup,

{ecgdatakit-2.0.2 → ecgdatakit-2.0.3}/src/ecgdatakit/parsing/parser.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import dataclasses
+import functools
 import importlib
 import pkgutil
 import warnings
@@ -52,31 +53,35 @@ class Parser(ABC):
         ...
 
 
-class FileParser:
-    """Auto-discovers parsers and dispatches files to the right one."""
+@functools.cache
+def _discover() -> tuple[type[Parser], ...]:
+    """Every Parser subclass of ``ecgdatakit.parsing.parsers``, in
+    detection order."""
+    package = importlib.import_module("ecgdatakit.parsing.parsers")
+    found: list[type[Parser]] = []
+    for _, name, _ in pkgutil.iter_modules(package.__path__):
+        module = importlib.import_module(f"ecgdatakit.parsing.parsers.{name}")
+        for attr in vars(module).values():
+            if (
+                isinstance(attr, type)
+                and issubclass(attr, Parser)
+                and attr is not Parser
+            ):
+                found.append(attr)
+    return tuple(sorted(found, key=lambda cls: (cls.PRIORITY, cls.__name__)))
 
-    def __init__(self) -> None:
-        self._parsers: list[type[Parser]] = []
-        self._discover_parsers()
 
-    def _discover_parsers(self) -> None:
-        """Find all Parser subclasses in ecgdatakit.parsers package."""
-        package = importlib.import_module("ecgdatakit.parsing.parsers")
-        for _, name, _ in pkgutil.iter_modules(package.__path__):
-            module = importlib.import_module(f"ecgdatakit.parsing.parsers.{name}")
-            for attr in vars(module).values():
-                if (
-                    isinstance(attr, type)
-                    and issubclass(attr, Parser)
-                    and attr is not Parser
-                ):
-                    self._parsers.append(attr)
-        self._parsers.sort(key=lambda cls: (cls.PRIORITY, cls.__name__))
+class FileParser:
+    """Auto-discovers parsers and dispatches files to the right one.
+
+    No method needs an instance: ``FileParser.parse(path)`` and
+    ``FileParser().parse(path)`` do the same.
+    """
 
     @property
     def parsers(self) -> list[type[Parser]]:
         """List of discovered :class:`Parser` subclasses."""
-        return list(self._parsers)
+        return list(_discover())
 
     @staticmethod
     def supported_formats() -> list[dict[str, str | list[str]]]:
@@ -112,8 +117,49 @@ class FileParser:
             for p in parsers
         ]
 
+    @staticmethod
+    def detect_format(file_path: str | Path) -> dict | None:
+        """Detect the format of an ECG file without parsing it.
+
+        Returns the format and the parser :meth:`parse` would use, or
+        ``None`` when no parser recognises the file. The dict holds
+        ``name``, ``description`` and ``extensions`` (as in
+        :meth:`supported_formats`), ``parser`` (the class name, e.g.
+        ``"SCPECGParser"``) and ``parser_class`` (the class itself)::
+
+            fmt = FileParser.detect_format("ecg.scp")
+            record = fmt["parser_class"]().parse("ecg.scp")
+
+        Raises
+        ------
+        FileNotFoundError
+            If the file does not exist.
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+        parser_cls = FileParser._find_parser(path)
+        if parser_cls is None:
+            return None
+        return {
+            "name": parser_cls.FORMAT_NAME or parser_cls.__name__,
+            "description": parser_cls.FORMAT_DESCRIPTION or (parser_cls.__doc__ or "").strip(),
+            "extensions": list(parser_cls.FILE_EXTENSIONS),
+            "parser": parser_cls.__name__,
+            "parser_class": parser_cls,
+        }
+
+    @staticmethod
+    def _find_parser(path: Path) -> type[Parser] | None:
+        """First parser, in detection order, that recognises *path*."""
+        header = b""
+        if path.is_file():
+            with open(path, "rb") as f:
+                header = f.read(_SNIFF_SIZE)
+        return next((p for p in _discover() if p.can_parse(path, header)), None)
+
+    @staticmethod
     def parse(
-        self,
         file_path: str | Path,
         auto_scale: bool = True,
         units: str = "mV",
@@ -159,12 +205,7 @@ class FileParser:
         path = Path(file_path)
         if not path.exists():
             raise FileNotFoundError(f"File not found: {path}")
-        header = b""
-        if path.is_file():
-            with open(path, "rb") as f:
-                header = f.read(_SNIFF_SIZE)
-
-        parser_cls = next((p for p in self._parsers if p.can_parse(path, header)), None)
+        parser_cls = FileParser._find_parser(path)
         if parser_cls is None:
             raise UnsupportedFormatError(f"No parser found for: {path.name}")
 
@@ -174,7 +215,7 @@ class FileParser:
         try:
             with warnings.catch_warnings(record=True) as caught:
                 warnings.simplefilter("always")
-                record = self._run_parser(parser_cls, path)
+                record = FileParser._run_parser(parser_cls, path)
                 if record.leads and all(len(lead.samples) == 0 for lead in record.leads):
                     raise CorruptedFileError(
                         f"{parser_cls.FORMAT_NAME or parser_cls.__name__}: "
@@ -182,7 +223,7 @@ class FileParser:
                     )
                 fill_signal_summary(record)
                 if auto_scale:
-                    record = self._auto_scale(record, target)
+                    record = FileParser._auto_scale(record, target)
         finally:
             for w in caught:
                 warnings.warn(w.message, w.category, stacklevel=2)

{ecgdatakit-2.0.2 → ecgdatakit-2.0.3}/src/ecgdatakit/parsing/parsers/xle.py

@@ -33,8 +33,11 @@ Not stored in the file, and taken from outside it:
 
 ``XLEParser(wilson_correction=True)`` refers the chest leads to Wilson's
 central terminal, ``V = CR - (I + II) / 3``, and names them ``V1`` to
-``V6``, with a warning. Leads III, aVR, aVL and aVF are not stored and not
-computed.
+``V6``, with a warning. Leads III, aVR, aVL and aVF are not stored.
+``XLEParser(wilson_correction=True, compute_missing_leads=True)`` also
+computes them from I and II (Einthoven and Goldberger), with a warning,
+so the record holds the standard 12 leads. ``compute_missing_leads``
+requires ``wilson_correction``.
 """
 
 from __future__ import annotations
@@ -150,10 +153,27 @@ class XLEParser(Parser):
     FILE_EXTENSIONS = [_EXT]
     PRIORITY = 45
 
-    def __init__(self, wilson_correction: bool = False) -> None:
+    def __init__(self, wilson_correction: bool = False,
+                 compute_missing_leads: bool = False) -> None:
         """*wilson_correction*: refer the chest leads, stored against the
-        right arm, to Wilson's central terminal (experimental)."""
+        right arm, to Wilson's central terminal (experimental).
+        *compute_missing_leads*: add III, aVR, aVL and aVF, computed from
+        I and II. Requires *wilson_correction*, so that the record holds
+        the standard 12 leads.
+
+        Raises
+        ------
+        ValueError
+            If *compute_missing_leads* is set without *wilson_correction*.
+        """
+        if compute_missing_leads and not wilson_correction:
+            raise ValueError(
+                "compute_missing_leads=True requires wilson_correction=True: "
+                "the 12 standard leads need the chest leads referred to "
+                "Wilson's central terminal."
+            )
         self.wilson_correction = wilson_correction
+        self.compute_missing_leads = compute_missing_leads
 
     @staticmethod
     def can_parse(file_path: Path, header: bytes) -> bool:
@@ -197,7 +217,24 @@ class XLEParser(Parser):
             )
             samples[:, 2:] -= (samples[:, :1] + samples[:, 1:2]) / 3
             chest = "V"
-        labels = ["I", "II"] + [f"{chest}{k}" for k in range(1, 7)]
+        lead_i, lead_ii = samples[:, 0], samples[:, 1]
+        leads = [("I", lead_i), ("II", lead_ii)]
+        computed: list[str] = []
+        if self.compute_missing_leads:
+            warnings.warn(
+                "Leads III, aVR, aVL and aVF are not stored in the XLE file: "
+                "they were computed from leads I and II.",
+                UserWarning,
+                stacklevel=2,
+            )
+            leads += [
+                ("III", lead_ii - lead_i),
+                ("aVR", -(lead_i + lead_ii) / 2),
+                ("aVL", lead_i - lead_ii / 2),
+                ("aVF", lead_ii - lead_i / 2),
+            ]
+            computed = ["III", "aVR", "aVL", "aVF"]
+        leads += [(f"{chest}{k}", samples[:, k + 1]) for k in range(1, 7)]
 
         fields = _fields(data)
         patient = PatientInfo(
@@ -215,10 +252,10 @@ class XLEParser(Parser):
         start, date_text, time_text = _recording_date(data)
         record.recording.date = start
         record.recording.duration = timedelta(seconds=frames / _SAMPLING_RATE)
-        for ch in range(_CHANNELS):
+        for label, values in leads:
             record.leads.append(Lead(
-                label=labels[ch],
-                samples=np.ascontiguousarray(samples[:, ch]),
+                label=label,
+                samples=np.ascontiguousarray(values),
                 sampling_rate=_SAMPLING_RATE,
                 resolution=_RESOLUTION_UV,
                 resolution_unit="uV",
@@ -244,6 +281,7 @@ class XLEParser(Parser):
         meta["wilson_correction"] = self.wilson_correction
         meta["chest_lead_reference"] = (
             "Wilson central terminal" if self.wilson_correction else "right arm")
+        meta["computed_leads"] = computed
         meta["header_size"] = _HEADER_SIZE
         meta["samples_per_channel"] = frames
         meta["wraps_undone"] = wraps

{ecgdatakit-2.0.2 → ecgdatakit-2.0.3}/src/ecgdatakit/processing/nn/weights/deepfade_exp_1_ddp.pt

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
-name: ecgdatakit-2.0.2/src/ecgdatakit/processing/nn/weights/deepfade_exp_1_ddp.pt
+name: ecgdatakit-2.0.3/src/ecgdatakit/processing/nn/weights/deepfade_exp_1_ddp.pt
 size: 64288532 bytes
 sha256: 80be2980936c57c00106dec23c01c9f51089d5dce724d4c99938dad5b2b92f13

{ecgdatakit-2.0.2 → ecgdatakit-2.0.3/src/ecgdatakit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ecgdatakit
-Version: 2.0.2
+Version: 2.0.3
 Summary: Multi-format ECG file parsing and signal processing library
 Author-email: Ahmad Fall <ahmad.fall@ird.fr>
 Maintainer-email: Ahmad Fall <ahmad.fall@ird.fr>

{ecgdatakit-2.0.2 → ecgdatakit-2.0.3}/tests/test_parser.py

@@ -77,6 +77,47 @@ class TestFileParserDiscovery:
         with pytest.raises(UnsupportedFormatError):
             fp.parse(unknown)
 
+    def test_parse_needs_no_instance(self, mortara_file: Path):
+        a = FileParser.parse(mortara_file)
+        b = FileParser().parse(mortara_file)
+        assert a.file_format.parser == b.file_format.parser == "MortaraEL250Parser"
+        assert [lead.label for lead in a.leads] == [lead.label for lead in b.leads]
+
+
+class TestDetectFormat:
+    @pytest.mark.parametrize("fixture, parser", [
+        ("hl7_aecg_file", "HL7aECGParser"),
+        ("mortara_file", "MortaraEL250Parser"),
+        ("ishne_file", "ISHNEHolterParser"),
+        ("edf_file", "EDFParser"),
+        ("scp_ecg_file", "SCPECGParser"),
+        ("ge_muse_xml_file", "GEMuseXMLParser"),
+        ("wfdb_file", "WFDBParser"),
+        ("mfer_file", "MFERParser"),
+    ])
+    def test_detects_the_parser_parse_uses(self, fixture, parser, request):
+        path = request.getfixturevalue(fixture)
+        fmt = FileParser.detect_format(path)
+        assert fmt["parser"] == parser
+        assert fmt["parser_class"].__name__ == parser
+        assert fmt["name"] == fmt["parser_class"].FORMAT_NAME
+        assert fmt["extensions"] == fmt["parser_class"].FILE_EXTENSIONS
+        assert FileParser.parse(path).file_format.parser == parser
+
+    def test_suggested_class_parses_the_file(self, mortara_file: Path):
+        fmt = FileParser.detect_format(mortara_file)
+        record = fmt["parser_class"]().parse(mortara_file)
+        assert record.leads
+
+    def test_unknown_format_gives_none(self, tmp_path: Path):
+        unknown = tmp_path / "data.xyz"
+        unknown.write_text("not an ecg file")
+        assert FileParser.detect_format(unknown) is None
+
+    def test_missing_file(self):
+        with pytest.raises(FileNotFoundError):
+            FileParser.detect_format("/nonexistent/file.xml")
+
 
 class TestCanParse:
     # --- Original 4 parsers ---

{ecgdatakit-2.0.2 → ecgdatakit-2.0.3}/tests/test_xle.py

@@ -20,6 +20,7 @@ FIELDS = (("Given name", 2673), ("Family name", 2712), ("ID", 2761), ("Birth Dat
 DATE_OFFSET, TIME_OFFSET = 182972, 182982
 CR_LEADS = ["I", "II", "CR1", "CR2", "CR3", "CR4", "CR5", "CR6"]
 V_LEADS = ["I", "II", "V1", "V2", "V3", "V4", "V5", "V6"]
+TWELVE_LEADS = ["I", "II", "III", "aVR", "aVL", "aVF", "V1", "V2", "V3", "V4", "V5", "V6"]
 
 
 def _swap16(data: bytes) -> bytes:
@@ -164,6 +165,50 @@ class TestXLE:
         assert meta["lead_order_stated"] is False
         assert meta["wilson_correction"] is False
         assert meta["chest_lead_reference"] == "right arm"
+        assert meta["computed_leads"] == []
+
+    def test_compute_missing_leads(self, tmp_path):
+        signal = ecg_like()
+        path = make_xle(tmp_path / "rec.xle", signal)
+        record, messages = caught_messages(
+            XLEParser(wilson_correction=True, compute_missing_leads=True).parse, path)
+        assert has(messages, "computed from leads I and II")
+        leads = {lead.label: lead.samples for lead in record.leads}
+        assert list(leads) == TWELVE_LEADS
+        i, ii = signal[:, 0], signal[:, 1]
+        np.testing.assert_allclose(leads["III"], ii - i)
+        np.testing.assert_allclose(leads["aVR"], -(i + ii) / 2)
+        np.testing.assert_allclose(leads["aVL"], i - ii / 2)
+        np.testing.assert_allclose(leads["aVF"], ii - i / 2)
+        # stored limb leads unchanged
+        np.testing.assert_array_equal(leads["I"], i)
+        np.testing.assert_array_equal(leads["II"], ii)
+        assert record.raw_metadata["computed_leads"] == ["III", "aVR", "aVL", "aVF"]
+        # computed leads are converted with the same scale
+        mv = record.to_physical().convert_units("mV")
+        np.testing.assert_allclose(mv.leads[2].samples, (ii - i) * 0.9375 / 1000)
+
+    def test_missing_leads_require_wilson(self):
+        with pytest.raises(ValueError, match="requires wilson_correction=True"):
+            XLEParser(compute_missing_leads=True)
+
+    def test_standard_twelve_leads(self, tmp_path):
+        signal = ecg_like()
+        path = make_xle(tmp_path / "rec.xle", signal)
+        record, messages = caught_messages(
+            XLEParser(wilson_correction=True, compute_missing_leads=True).parse, path)
+        assert [lead.label for lead in record.leads] == TWELVE_LEADS
+        assert has(messages, "Wilson correction applied")
+        assert has(messages, "computed from leads I and II")
+        wct = (signal[:, 0] + signal[:, 1]) / 3
+        np.testing.assert_allclose(record.leads[6].samples, signal[:, 2] - wct)
+        # Einthoven: I + III = II
+        np.testing.assert_allclose(record.leads[0].samples + record.leads[2].samples,
+                                   record.leads[1].samples)
+        # Goldberger: aVR + aVL + aVF = 0
+        np.testing.assert_allclose(
+            record.leads[3].samples + record.leads[4].samples + record.leads[5].samples, 0,
+            atol=1e-9)
 
     @pytest.mark.parametrize("date, time, expected", [
         ("27.04.99", "08:15", datetime(1999, 4, 27, 8, 15)),     # dots: day first