ECGProcess 1.1.0__py3-none-any.whl

ecgprocess/utils/ecg_tools.py

@@ -0,0 +1,311 @@
+'''
+Collecting established tools for ECG derivation or cleaning.
+'''
+
+import numpy as np
+from ecgprocess.constants import (
+    CoreData as Core,
+)
+from scipy import signal
+from ecgprocess.errors import (
+    is_type,
+)
+from typing import Any
+import warnings
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# constants
+CLeads = Core.Leads
+_STANDARD_LEADS: tuple[str, ...] = (
+    'I', 'II', 'III', 'V1', 'V2', 'V3', 'V4', 'V5', 'V6', 'aVF', 'aVL', 'aVR'
+)
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def resampling_500hz(signals:dict[str, np.array],
+                     duration: int | float | None=None,
+                     median:bool=False) -> dict[str, np.array]:
+    """
+    Re-sample an ECG signal to 500 hz.
+    
+    Parameters
+    ----------
+    signals : `dict` [`str`, np.array]
+        A dictionary with the lead names as string keys and the signals
+        as a 1D np.array.
+    duration : `int` or `float`
+        The represents the duration of the ECG in seconds, which is calculated
+        based on the fraction of number of samples by the sampling frequency
+        in seconds.  For raw wavefomrs duration determines the number of
+        samples needed to get a 500hz sample: duration times 500.
+    median : `bool`, default `False`
+        Set to true to resample a median beat ECG to 500hz. The duration of a
+        median beat signal is 1.2 seconds, hence the number of samples is fixed
+        at: 1.2 times 500 = 600.
+    
+    """
+    is_type(signals, dict)
+    is_type(duration, (type(None), int, float))
+    is_type(median, bool)
+    # #### get number of samples
+    num_samples = 600
+    if median == False:
+        if duration is None:
+            raise ValueError('`duration` should not be `NoneType` when `median` '
+                             'is `False`.')
+        num_samples = int(duration * 500)
+    # #### resample
+    new_dict = {}
+    for l, sig in signals.items():
+        new_dict[l] = signal.resample(sig, num_samples)
+    # return
+    return new_dict
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def get_limb_leads(signals:dict[str, np.array],
+                   lead_I:str=CLeads.I,
+                   lead_II:str=CLeads.II,
+                      ) -> dict[str, np.array]:
+    """
+    Calculate the derived limb leads (III, aVR, aVL, aVF) from leads I and II.
+    
+    Parameters
+    ----------
+    signals : `dict` [`str`, np.array]
+        A dictionary with the lead names as string keys and the signals
+        as a 1D np.array.
+    lead_I : `str`, default 'I'
+        The key name for lead I in `signals`
+    lead_II : `str`, default 'II'
+        The key name for lead II in `signals`
+    
+    Returns
+    -------
+    dict
+        A dictionary including limb lead signals.
+    
+    Notes
+    -----
+    please see this
+    `url <https://ecgwaves.com/topic/ekg-ecg-leads-electrodes-systems-limb-chest-precordial/>`_
+     for the relevant explanation about the relationships between leads I and II
+    and the limb leads.
+    """
+    # #### check input and set constants
+    is_type(signals, dict)
+    is_type(lead_I, str)
+    is_type(lead_II, str)
+    missing_src = [l for l in (lead_I, lead_II) if signals.get(l) is None]
+    if missing_src:
+        raise KeyError(
+            f'Source leads {missing_src} are not available in `signals`.'
+        )
+    # making sure we do not affect the original parsed signals
+    signals = dict(signals)
+    # #### get limb leads
+    if signals.get(CLeads.III) is None:
+        signals[CLeads.III] = np.subtract(signals[CLeads.II],
+                                              signals[CLeads.I])
+    if signals.get(CLeads.aVR) is None:
+        signals[CLeads.aVR] = np.add(signals[CLeads.I],
+                                        signals[CLeads.II]) * (-0.5)
+    if signals.get(CLeads.aVL) is None:
+        signals[CLeads.aVL] = np.subtract(signals[CLeads.I],
+                                   0.5 * signals[CLeads.II])
+    if signals.get(CLeads.aVF) is None:
+        signals[CLeads.aVF] = np.subtract(signals[CLeads.II],
+                                   0.5 * signals[CLeads.I])
+    # return
+    return signals
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def signal_dicts_to_numpy_array(
+    signals: list[dict[str, np.ndarray]],
+    leads: list[str] | tuple[str, ...] | None = _STANDARD_LEADS,
+    padding: bool = True,
+) -> np.ndarray:
+    """
+    Convert a list of ECG signal dictionaries to a 3D NumPy array suitable
+    for deep learning.
+    
+    Parameters
+    ----------
+    signals : `list` [`dict` [`str`, `np.ndarray`]]
+        List where each dictionary represents an ECG sample with lead names
+        as keys and numpy arrays as values.
+    leads : `list` [`str`] or `tuple` [`str`, ...] or `None`, \
+default ``_STANDARD_LEADS``
+        Lead names to include and their order. Defaults to the standard
+        12-lead set defined in ``_STANDARD_LEADS`` (an immutable tuple).
+        Pass `None` to collect all unique leads found across samples in
+        sorted order.
+    padding : `bool`, default `True`
+        Whether to pad shorter signals to the length of the longest signal.
+        If `False`, all signals must have the same length. Default is `True`.
+    
+    Returns
+    -------
+    np.ndarray
+        3D NumPy array with shape `(num_samples, num_leads, signal_length)`
+        containing the ECG data.
+    
+    Raises
+    ------
+    ValueError
+        If `ecg_data` is empty.
+        If any sample is missing leads specified in `leads`.
+        If `padding` is `False` and signals have varying lengths.
+    
+    Notes
+    -----
+    The numpy array column matches the order of the supplied leads.
+    """
+    # check input
+    is_type(signals, list)
+    if not signals:
+        raise ValueError("The signals list is empty.")
+    # Determine the list of leads
+    if leads is None:
+        # Collect all unique leads across samples
+        unique_leads: set[str] = set()
+        for sample in signals:
+            unique_leads.update(sample.keys())
+        leads = sorted(unique_leads)
+    else:
+        # Ensure leads is a sequence of strings
+        if not isinstance(leads, (list, tuple)) or not all(
+            isinstance(lead, str) for lead in leads
+        ):
+            raise TypeError("`leads` must be a list or tuple of strings.")
+        leads = list(leads)
+    # set the samples and lead numbers
+    num_samples = len(signals)
+    num_leads = len(leads)
+    # do we want to pad the signals if needed.
+    if padding:
+        # Find the maximum length among all leads in all samples
+        signal_length = max(
+            len(sample.get(lead, [])) for sample in signals for lead in leads
+        )
+    else:
+        # Ensure all signals have the same length
+        lengths = [
+            len(sample.get(lead, [])) for sample in signals for lead in leads
+        ]
+        unique_lengths = set(lengths)
+        if len(unique_lengths) != 1:
+            raise ValueError(
+                "All signals must have the same length when padding is False."
+            )
+        signal_length = unique_lengths.pop()
+    # Initialize the array with NaNs
+    data_array = np.full(
+        (num_samples, num_leads, signal_length), np.nan, dtype=np.float32
+    )
+    for i, sample in enumerate(signals):
+        for j, lead in enumerate(leads):
+            lead_data = sample.get(lead, np.array([]))
+            # Validate that lead_data is a np.array
+            if not isinstance(lead_data, np.ndarray):
+                raise TypeError(
+                    f"Lead '{lead}' in sample {i} is not a NumPy array."
+                )
+            current_length = len(lead_data)
+            if current_length == 0:
+                # If lead data is missing or empty, leave it as NaN
+                continue
+            elif padding:
+                if current_length > signal_length:
+                    # Truncate the signal if it's longer than signal_length
+                    warnings.warn('Signal is longer than the max length '
+                                  'this is unexpected, please check input.')
+                    data_array[i, j, :] = lead_data[:signal_length]
+                else:
+                    # Pad the signal with NaNs if it's shorter than
+                    # signal_length
+                    data_array[i, j, :current_length] = lead_data
+            else:
+                if current_length != signal_length:
+                    raise ValueError(
+                        f"Signal length for lead '{lead}' in sample {i} "
+                        f"({current_length}) does not match signal_length "
+                        f"({signal_length})."
+                    )
+                data_array[i, j, :] = lead_data
+    # return
+    return data_array
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def signal_calibration(signal:np.ndarray,
+                       correctionfactor: float,
+                       baseline: float,
+                       ) -> np.ndarray:
+    """
+    Adjusts the ECG signal by subtracting the channel baseline from the signal,
+    followed by multiplying the adjusted signal by the channel correction
+    factor.
+    
+    Parameters
+    ----------
+    signal : `np.ndarray`
+        The lead-specific ECG signal.
+    correctionfactor : `float`
+        The channel correction factor.
+    baseline : `float`
+        The channel baseline.
+    
+    Returns
+    -------
+    np.ndarray
+        The recalibrated signal.
+    """
+    is_type(signal, np.ndarray)
+    is_type(correctionfactor, float)
+    is_type(baseline, float)
+    # algorithm
+    new_signal = (signal - baseline) * correctionfactor
+    # return
+    return new_signal
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def signal_resolution(signal:np.ndarray,
+                      resolution_current: float,
+                      resolution_target: float,
+                       ) -> np.ndarray:
+    """
+    Adjust the amplitude scale of an ECG signal to match a desired resolution.
+    
+    Parameters
+    ----------
+    signal : `np.ndarray`
+        The lead-specific ECG signal.
+    resolution_current : `float`
+        The current resolution.
+    resolution_target : `float`
+        The target resolution.
+    
+    Returns
+    -------
+    np.ndarray
+        The rescaled signal.
+    
+    Example
+    -------
+    >>> import numpy as np
+    >>> ecg_signal = np.array([10, 20, 30, 40, 50])
+    >>> current_res = 2.0  # each digital unit equals 2 μV
+    >>> new_signal = adjust_resolution(
+    ...     ecg_signal,
+    ...     resolution_current=current_res,
+    ...     resolution_target=5
+    ... )
+    >>> print(new_signal)
+    [ 25.  50.  75. 100. 125.]
+    """
+    is_type(signal, np.ndarray)
+    is_type(resolution_current, float)
+    is_type(resolution_target, float)
+    # algorithm
+    new_signal = signal * resolution_target/resolution_current
+    # return
+    return new_signal
+

ecgprocess/utils/engineering_tools.py

@@ -0,0 +1,385 @@
+"""
+A module containing a collection of function or classes which can be used
+as engineering functions in the Tabular module.
+
+The listed programs are meant to provide an idea of potentially relevant
+solutions. Users can use these functions out of the box, adapt them, or
+simply write their own custom code.
+
+When writing your own engineering solution remember that the first argument
+will take the metadata, waveforms, or metadata. The waveforms and metadata
+functions should have a kwargs argument which will be used internally by
+Tabular to pass meta_dict (the metadata of the file being processed) to the
+function environment making it available to alter the signal data.
+"""
+
+# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+# imports
+import re
+import logging
+import numpy as np
+from typing import (
+    Callable, Self, Optional, Any, Literal,
+)
+from ecgprocess.errors import (
+    FileValidationError,
+    InputValidationError,
+    is_type,
+)
+from ecgprocess.utils.ecg_tools import(
+    signal_dicts_to_numpy_array,
+    signal_calibration,
+    signal_resolution,
+)
+from ecgprocess.constants import (
+    TabularNames as TabNames,
+)
+
+# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+_log = logging.getLogger(__name__)
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def metadata_checkversion(
+    metadata:dict[str, Any],
+    expected_version = ['1.02 SP03', 'MUSE_9.0.9.18167'],
+    expected_manufacturer = 'GE Healthcare',
+    expected_model = 'MV360',
+    version_name:str = "Softwave version",
+    manufacturer_name:str = "Manufacturer",
+    model_name = "Model name",
+    **kwargs,
+) -> dict[str, Any]:
+    """
+    Validates the DICOM file against the specified software version,
+    manufacturer, and model. If any of these do not match, a
+    FileValidationError is raised.
+    
+    Parameters
+    ----------
+    metadata : `dict` [`str`, `any`]
+        A dictionary containing the metadata for a DICOM file. It must include:
+          - "Softwave version": The software version associated with the file.
+          - "Manufacturer": The manufacturer of the device.
+          - "Model name": The model name of the device.
+    expected_version : `str` or `list` [`str`], default ['1.02 SP03', 'MUSE_9.0.9.18167']
+        The software version.
+    expected_manufacturer : `str` or `list` [`str`], default 'GE Healthcare'
+        The manufacturer.
+    expected_model : `str` or `list` [`str`],  'MV360'
+        The model.
+    version_name : `str`
+        The key name for version in meta_dict.
+    manufacturer_name : `str`
+        The key name for manufacturer in meta_dict.
+    moel_name : `str`
+        The key name for version in meta_dict.
+    
+    Returns
+    -------
+    dict [`str`, `any`]
+        The input `metadata` dictionary if validation is successful.
+    
+    Raises
+    ------
+    FileValidationError
+        If the DICOM metadata's software version, manufacturer, or model
+        does not match the respective expected values.
+    
+    Notes
+    -----
+    Depending on the `ignore_invalid` parameter of `Tabular` the failed
+    filenames will be added to the `invalid_list` attribute.
+    """
+    is_type(manufacturer_name, str)
+    is_type(version_name, str)
+    is_type(model_name, str)
+    # constant
+    version = version_name
+    manufact = manufacturer_name
+    model_name = model_name
+    # the algorithm: check each expected field independently so the error
+    # message identifies which field failed. expected_* may be a single
+    # string or a list of strings; normalise to a list so membership tests
+    # work in both cases.
+    def _check(field_label: str, got: Any, expected: Any) -> None:
+        expected_list = expected if isinstance(expected, list) else [expected]
+        if got not in expected_list:
+            raise FileValidationError(
+                f"{field_label} `{got}` failed to validate; "
+                f"expected one of {expected_list}."
+            )
+    _check("Version", metadata[version], expected_version)
+    _check("Manufacturer", metadata[manufact], expected_manufacturer)
+    _check("Model", metadata[model_name], expected_model)
+    # if all correct simply return metadata
+    return metadata
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def signal_correction(
+    signals:dict[str, np.ndarray], baseline_name:str='wave_channel_baseline_',
+    correctionfactor_name:str='wave_channel_correctionfactor_',
+    **kwargs) -> dict[str, np.ndarray]:
+    """
+    Adjusts the signals by subtracting the channel baseline multiplied
+    by the channel correction factor.  These parameters must be provided in
+    `kwargs[TabNames.META_DICT]`.
+    
+    Parameters
+    ----------
+    signals : `dict` [`str`, `np.ndarray`]
+        A dictionary mapping channel names (strings) to waveform arrays.
+    baseline_name : str
+        The dictionary key name for the channel baseline. Will internally add
+        a numeric suffix ranging from 0 to 11 (inclusive).
+    correctionfactor_name : str
+        The dictionary key name for the channel correctionfactor. Will
+        internally add a numeric suffix ranging from 0 to 11 (inclusive).
+    **kwargs
+        Additional keyword arguments, which must include a dictionary under
+        the key `TabNames.META_DICT`. This dictionary should contain:
+        - wave_channel_correctionfactor_i : float
+            Correction factor for channel i.
+        - wave_channel_baseline_i : float
+            Baseline offset for channel i.
+    
+    Returns
+    -------
+    dict [`str`, `np.ndarray`]
+        The input signals dictionary with corrected signals.
+    
+    Raises
+    ------
+    KeyError
+        If `TabNames.META_DICT` is not found in **kwargs.
+    """
+    # constants - these values should be in meta_dict
+    corr = correctionfactor_name
+    base = baseline_name
+    # TODO
+    # add a check/raise error for the presence or absence of these keys in
+    # meta_dict.
+    # the algorithm
+    if not TabNames.META_DICT in kwargs:
+        raise KeyError(f"`{TabNames.META_DICT}` should be included as kwargs")
+    else:
+        meta_dict = kwargs[TabNames.META_DICT]
+    signals = dict(signals)
+    for i, (k, v) in enumerate(signals.items()):
+        # skip of None
+        if v is None:
+            signals[k] = v
+            continue
+        # confirming this is a np.array
+        is_type(v, np.ndarray)
+        _log.debug(
+            'Applying baseline: %s and factor: %s corrections to lead: %s.',
+            meta_dict[base+str(i)], meta_dict[corr+str(i)], k,
+        )
+        signals[k] = signal_calibration(
+            v, correctionfactor=meta_dict[corr+str(i)],
+            baseline=meta_dict[base+str(i)],
+        )
+    return signals
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def signal_standardise_res(
+    signals:dict[str, np.ndarray], resolution_name:str = 'wave_channel_sens_',
+    target_resolution:float = 5., **kwargs,
+) -> dict[str, np.ndarray]:
+    """
+    Standardise the resolution signal by adjusting the amplitude scale by the
+    ratio of the source and target solution.
+    
+    Parameters
+    ----------
+    signals : `dict` [`str`, `np.ndarray`]
+        A dictionary mapping channel names (strings) to waveform arrays.
+    resolution_name : str
+        The dictionary key name for the channel sensitivity/resolution. Will
+        internally add a numeric suffix ranging from 0 to 11 (inclusive).
+    target_resolution : `float`, default 5
+        The target resolution.
+    **kwargs
+        Additional keyword arguments, which must include a dictionary under
+        the key `TabNames.META_DICT`. This dictionary should contain:
+        - wave_channel_sens : float
+            The wave channel sensitivity/resolution for channel i.
+    
+    Returns
+    -------
+    dict [`str`, `np.ndarray`]
+        The input signals dictionary with corrected signals.
+    
+    Raises
+    ------
+    KeyError
+        If `TabNames.META_DICT` is not found in **kwargs.
+        If resolution_name+str(i) is not found in `TabNames.META_DICT`.
+    
+    Notes
+    -----
+    The function will apply a scaling factor of
+    source_resolution/target_resolution to ensure the returned signal has the
+    desired target uV.
+    """
+    # constants - these values should be in meta_dict
+    sens = resolution_name
+    # the algorithm
+    if not TabNames.META_DICT in kwargs:
+        raise KeyError(f"`{TabNames.META_DICT}` should be included as kwargs")
+    else:
+        meta_dict = kwargs[TabNames.META_DICT]
+    signals = dict(signals)
+    for i, (k, v) in enumerate(signals.items()):
+        # skip of None
+        if v is None:
+            signals[k] = v
+            continue
+        # confirming this is a np.array
+        is_type(v, np.ndarray)
+        # check key is in dict
+        key_name = sens+str(i)
+        if not key_name in meta_dict:
+            raise KeyError(f"`{key_name}` not found in `{TabNames.META_DICT}`.")
+        if target_resolution/meta_dict[key_name] != 1.0:
+            _log.debug(
+                'Rescaling lead `%s` by factor `%s`.',
+                k, target_resolution/meta_dict[key_name],
+            )
+        signals[k] = signal_resolution(
+            v, resolution_current=meta_dict[key_name],
+            resolution_target=target_resolution,
+        )
+    return signals
+
+# @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+class LeadMapper(object):
+    """
+    Normalise ECG lead ordering when a device writes channels out of sequence.
+    
+    Some DICOM devices store channels in a non-standard order (e.g. Lead II
+    data in channel-0 slot). ``LeadMapper`` reads ``signal name X`` entries
+    from ``meta_dict``, builds an actual-label-to-key mapping, then reassigns
+    each canonical key in ``signals`` to the correct array.
+    
+    Parameters
+    ----------
+    accepted_mappings : `dict` [`str`, `list` [`str`]]
+        Maps each canonical lead key (e.g. ``'I'``) to a list of device
+        label strings that are acceptable for that lead
+        (e.g. ``['I', 'Lead I', 'Lead I (Einthoven)']``).
+    
+    Attributes
+    ----------
+    accepted_mappings : `dict` [`str`, `list` [`str`]]
+        The accepted lead label mappings supplied at initialisation.
+    
+    Methods
+    -------
+    __call__(signals, **kwargs)
+        Reassign signal arrays to their canonical lead keys.
+    
+    Raises
+    ------
+    InputValidationError
+        If ``accepted_mappings`` is not a ``dict``, or if any value is
+        not a ``list``.
+    
+    Notes
+    -----
+    The callable works for both ``engineer_wave`` and ``engineer_median``
+    call sites in ``tabular.py`` since both share the same signature
+    ``(signals, meta_dict=meta_temp)``.
+    """
+    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    def __init__(self, accepted_mappings: dict[str, list[str]]) -> None:
+        """Initialise LeadMapper."""
+        is_type(accepted_mappings, dict)
+        for key, val in accepted_mappings.items():
+            if not isinstance(val, list):
+                raise InputValidationError(
+                    f"accepted_mappings values must be lists; "
+                    f"key '{key}' has type {type(val)}"
+                )
+        self.accepted_mappings = accepted_mappings
+    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    def __call__(
+        self,
+        signals: dict[str, np.ndarray],
+        **kwargs,
+    ) -> dict[str, np.ndarray]:
+        """
+        Reassign signal arrays to their canonical lead keys.
+        
+        Parameters
+        ----------
+        signals : `dict` [`str`, `np.ndarray`]
+            Dict mapping canonical key names to waveform arrays, as parsed
+            by the config parser (keys correct, values potentially in wrong
+            channel order).
+        **kwargs
+            Must include ``meta_dict`` (keyed by ``TabNames.META_DICT``),
+            a dict containing ``'signal name N'`` entries that map channel
+            indices to device lead labels.
+        
+        Returns
+        -------
+        mapped_signals : `dict` [`str`, `np.ndarray`]
+            Shallow copy of ``signals`` with arrays reassigned to the correct
+            canonical keys.
+        
+        Raises
+        ------
+        KeyError
+            If ``TabNames.META_DICT`` is absent from ``kwargs``, or if no
+            device label matches a required canonical key.
+        """
+        # check input
+        is_type(signals, dict)
+        if TabNames.META_DICT not in kwargs:
+            raise KeyError(
+                f"`{TabNames.META_DICT}` should be included as kwargs"
+            )
+        # map data
+        meta_dict = kwargs[TabNames.META_DICT]
+        mapped_signals = dict(signals)
+        signal_keys = list(mapped_signals.keys())
+         # Map each canonical slot key to the device label the device wrote
+         # there; e.g. {'I': 'Lead II'} means channel 0 holds 'Lead II' data.
+        actual_mappings = {
+            signal_keys[int(re.sub(r"^signal name\s*", "", k))]: v
+            for k, v in meta_dict.items()
+            if k.startswith('signal name')
+        }
+        _log.debug('Accepted lead mappings: %s', self.accepted_mappings)
+        _log.debug('Actual lead mappings: %s', actual_mappings)
+        # Now apply the mappings
+        for accepted_key, accepted_vals in self.accepted_mappings.items():
+            match = False
+            for actual_key, actual_val in actual_mappings.items():
+                if actual_val in accepted_vals:
+                    _log.debug(
+                        "Mapping '%s' (%s) <- actual '%s' (%s)",
+                        accepted_key, accepted_vals, actual_key, actual_val,
+                    )
+                    mapped_signals[accepted_key] = signals[actual_key]
+                    match = True
+                    break
+            if not match:
+                raise KeyError(
+                    f"No device label found for canonical key '{accepted_key}' "
+                    f"(accepted: {accepted_vals})"
+                )
+        return mapped_signals
+    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    def __repr__(self) -> str:
+        """Return unambiguous string representation."""
+        CLASS_NAME = type(self).__name__
+        return f"{CLASS_NAME}(accepted_mappings={self.accepted_mappings!r})"
+    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    def __str__(self) -> str:
+        """Return human-readable string representation."""
+        CLASS_NAME = type(self).__name__
+        leads = list(self.accepted_mappings.keys())
+        return f"{CLASS_NAME} with {len(leads)} canonical leads: {leads}"
+