ECGProcess 1.1.0__py3-none-any.whl

ecgprocess/__init__.py

@@ -0,0 +1 @@
+from ._version import __version__

ecgprocess/_version.py

@@ -0,0 +1 @@
+__version__ = '1.1.0'

ecgprocess/constants.py

@@ -0,0 +1,170 @@
+'''
+Constants used by ECGProcess
+'''
+
+from dataclasses import dataclass
+
+# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+class CoreData:
+    '''
+    Core variable names which are used internally by various modules in
+    `ECGProcess`.
+    '''
+    # /////////////////////////////////////////////////////////////////////////
+    class DataTypes:
+        '''
+        Contains constants representing high-level data categories used
+        in ECG processing, such as waveforms, median beats, and metadata.
+        '''
+        WaveForms   = 'WaveForms'
+        MedianBeats = 'MedianBeats'
+        MetaData    = 'MetaData'
+        OtherData   = 'OtherData'
+    # /////////////////////////////////////////////////////////////////////////
+    class Leads:
+        '''
+        The internally used lead names.
+        '''
+        I   = 'I'
+        II  = 'II'
+        III = 'III'
+        aVR = 'aVR'
+        aVL = 'aVL'
+        aVF = 'aVF'
+        V1  = 'V1'
+        V2  = 'V2'
+        V3  = 'V3'
+        V4  = 'V4'
+        V5  = 'V5'
+        V6  = 'V6'
+    # /////////////////////////////////////////////////////////////////////////
+    class MetaData:
+        '''
+        Contains constants representing metadata fields required for
+        ECG processing.
+        '''
+        UID     = 'unique identifier'
+        NLEADS  = 'number of leads'
+        RES_U_W = 'resolution unit (waveforms)'
+        RES_U_M = 'resolution unit (medianbeats)'
+        RES_W   = 'resolution (waveforms)'
+        RES_M   = 'resolution (medianbeats)'
+        SF      = 'sampling frequency (original)'
+        SF_U    = 'sampling frequency unit'
+        SN_W    = 'sampling number (waveforms)'
+        SN_M    = 'sampling number (medianbeats)'
+    # /////////////////////////////////////////////////////////////////////////
+    class ProcessingData:
+        '''
+        Contains constants for attributes and variables created by the process
+        modules.
+        '''
+        TAGS      = 'tags'
+        RAW       = 'raw_data'
+        Duration  = 'duration (sec)'
+        SF_NEW    = 'sampling frequency (processed)'
+        RESAMPLE  = 'resample_500'
+        AUG_LEADS = 'augment_leads'
+
+# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+class UtilsReaderNames(object):
+    '''
+    Names used in the Utils Reader Tools module.
+    '''
+    DICOM_WAVE_ARRAY     = 'waveform_array'
+
+# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+class UtilsGeneralNames(object):
+    '''
+    Names used in the Utils General module.
+    '''
+    LXML_ERROR         = 'expected'
+
+# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+class UtilsConfigData(object):
+    '''
+    Names used in the Utils Config Data module
+    '''
+    MetaData    = CoreData.DataTypes.MetaData
+    OtherData   = CoreData.DataTypes.OtherData
+    WaveForms   = CoreData.DataTypes.WaveForms
+    MedianBeats = CoreData.DataTypes.MedianBeats
+    path        = 'path'
+    data        = '_data'
+    MAPPER      = 'mapper'
+
+# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+class ProcessXMLNames(object):
+    '''
+    Names used in the process_xml module.
+    '''
+    RESAMPLE  = CoreData.ProcessingData.RESAMPLE
+    AUG_LEADS = CoreData.ProcessingData.AUG_LEADS
+
+# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+class ProcessDicomNames(object):
+    RESAMPLE  = CoreData.ProcessingData.RESAMPLE
+    AUG_LEADS = CoreData.ProcessingData.AUG_LEADS
+    
+# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+class TabularNames(object):
+    E_META         = 'extract_'+CoreData.DataTypes.MetaData
+    E_WAVE         = 'extract_'+CoreData.DataTypes.WaveForms
+    E_MEDIAN       = 'extract_'+CoreData.DataTypes.MedianBeats
+    ENG_META       = 'engineer_'+CoreData.DataTypes.MetaData
+    ENG_WAVE       = 'engineer_'+CoreData.DataTypes.WaveForms
+    ENG_MEDIAN     = 'engineer_'+CoreData.DataTypes.MedianBeats
+    META_DICT      = 'meta_dict'
+    SKIP_PERM      = 'ignore_permission'
+    SKIP_DATA      = 'ignore_data'
+    SKIP_INVALID   = 'ignore_invalid'
+    CONFIRM_META   = 'confirm_meta'
+    CONFIRM_WAVE   = 'confirm_wave'
+    CONFIRM_MEDIAN = 'confirm_median'
+    SCHEMA         = 'schema'
+    RPATH_L        = 'raw_path_list'
+    FPATH_L        = 'failed_path_list'
+    CPATH_L        = 'curated_path_list'
+    KEY_L          = 'key_list'
+    NO_DATA_L      = 'no_data_list'
+    INVALID_L      = 'invalid_list'
+    TABLE_CALLED   = 'table_called'
+    WRITE_TAB      = 'table'
+    WRITE_NUMPY    = 'numpy'
+    WRITE_TFLOW    = 'tensorflow'
+    WRITE_ECG_PATH = 'target_path'
+    WRITE_TYPE     = 'file_type'
+    ID_START       = '_id_start_number'
+    KEY            = 'key'
+    FILENAM        = 'filename'
+    SIG_LEN_W      = 'signal_length_w'
+    SIG_LEN_M      = 'signal_length_m'
+    PAD_VALUE      = 'pad_value'
+    SN_W_PADDED    = 'sampling number padded (waveforms)'
+    SN_M_PADDED    = 'sampling number padded (medianbeats)'
+    DURATION_PADDED = 'duration padded (sec)'
+
+# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+class PlotNames:
+    '''
+    Constants used by the ECGDrawing plotting module.
+    '''
+    MILLIVOLT       = 'millivolt'
+    MICROVOLT       = 'microvolt'
+    LEAD_VOLTAGES   = 'lead_voltages'
+    START_POS_FIRST = 'first'
+    # #### standard ECG paper grid dimensions (mm)
+    MINOR_GRID_MM   = 1.0
+    MAJOR_GRID_MM   = 5.0
+    # #### ECGDrawing slot names
+    DEFAULT_LEADS   = '_default_leads'
+    FIGURE          = 'figure'
+    AXES            = 'axes'
+    LAYOUT_MAPPER   = 'layout_mapper'
+    STYLE           = 'style'
+    MINOR_STEP_X    = 'minor_step_x'
+    MAJOR_STEP_X    = 'major_step_x'
+    MINOR_STEP_Y    = 'minor_step_y'
+    MAJOR_STEP_Y    = 'major_step_y'
+    PAPER_SPEED     = 'paper_speed'
+    MM_PER_MV       = 'mm_per_mv'

ecgprocess/errors.py

@@ -0,0 +1,380 @@
+'''
+Error handling for ECGProcess.
+'''
+import os
+import inspect
+import warnings
+import pandas as pd
+
+from os import PathLike
+from typing import Any, Type, Union
+
+# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+class InputValidationError(Exception):  # pragma: no cover
+    pass
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def get_param_name(param:Any) -> str | None:  # pragma: no cover
+    '''
+    Gets the name of `param` from the caller's local scope.
+    
+    Parameters
+    ----------
+    param : `Any`
+        The object whose variable name is to be resolved.
+    
+    Returns
+    -------
+    name : `str` or `None`
+        The variable name as a string, or `None` if it cannot be resolved.
+    '''
+    frame = inspect.currentframe().f_back.f_back
+    param_names =\
+        [name for name, value in frame.f_locals.items() if value is param]
+    return param_names[0] if param_names else None
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def is_type(param: Any, types: tuple[Type] | Type,
+            param_name: str | None=None) -> bool:
+    """
+    Checks if a given parameter matches any of the supplied types.
+    
+    Parameters
+    ----------
+    param : `Any`
+        Object to test.
+    types : `Type` or `tuple` [`Type`]
+        Either a single type, or a tuple of types to test against.
+    param_name : `str` or `None`, optional
+        Name of the parameter, used in the error message. Resolved
+        automatically from the caller's scope when not supplied.
+    
+    Returns
+    -------
+    result : `bool`
+        `True` if the parameter is an instance of any of the given types.
+    
+    Raises
+    ------
+    InputValidationError
+        If `param` is not an instance of any type in `types`.
+    """
+    if not isinstance(param, types):
+        if param_name is None:
+            param_name = get_param_name(param)
+        raise InputValidationError(
+            f"Expected any of [{types}], "
+            f"got {type(param)}; Please see parameter: `{param_name}`."
+        )
+    return True
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def is_df(df: Any) -> bool:  # pragma: no cover
+    """
+    Checks if object is a pd.DataFrame.
+    
+    Parameters
+    ----------
+    df: `Any`
+    
+    Returns
+    -------
+    True if the df is a pd.DataFrame. Raises InputValidationError otherwise.
+    """
+    return is_type(df, pd.DataFrame)
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def is_series_type(column: pd.Series | pd.DataFrame,
+                   types: tuple[Type] | Type,
+                   ) -> bool:
+    """
+    Checks if a `pd.DataFrame` or `pd.Series` contains the supplied type.
+    
+    Parameters
+    ----------
+    column : `pd.Series` or `pd.DataFrame`
+        The column or frame whose elements are to be tested.
+    types : `Type` or `tuple` [`Type`]
+        Either a single type, or a tuple of types to test against.
+    
+    Returns
+    -------
+    result : `bool`
+        `True` if all elements match any of the given types.
+    
+    Raises
+    ------
+    InputValidationError
+        If any element is not an instance of any type in `types`.
+    
+    Notes
+    -----
+    Tests each element individually rather than relying on dtype inference.
+    """
+    # check input
+    is_type(column, (pd.DataFrame, pd.Series))
+    # run tests
+    if isinstance(column, pd.Series):
+        [is_type(col, types) for col in column]
+    elif isinstance(column, pd.DataFrame):
+        for _, col in column.items():
+            [is_type(co, types) for co in col]
+    # return
+    return True
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def same_len(object1: Any, object2: Any,
+             object_names:list[str] | None=None,
+             ) -> bool:
+    """
+    Check if two objects have the same length.
+    
+    Parameters
+    ----------
+    object1, object2 : `Any`
+        Any type of object with a `__len__` method.
+    object_names : `list` [`str`] or `None`, optional
+        Names of the two objects, included in the error message when
+        lengths differ.
+    
+    Returns
+    -------
+    result : `bool`
+        `True` if both objects have the same length.
+    
+    Raises
+    ------
+    ValueError
+        If the lengths differ, or if `object_names` does not contain
+        exactly two strings.
+    """
+    n1 = len(object1)
+    n2 = len(object2)
+    if object_names is None:
+        object_names = ['object1', 'object2']
+    elif len(object_names) !=2:
+        raise ValueError('`object_names` should be `NoneType` or contain '
+                         'two strings')
+    # the actual test
+    if n1 != n2:
+        raise ValueError(
+            "The length of `{0}`: {1}, does not match "
+            "the length of `{2}`: {3}.".format(
+                object_names[0], n1, object_names[1], n2)
+        )
+    return True
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def are_columns_in_df(
+    df: pd.DataFrame, expected_columns: list[str] | str,
+    warning: bool=False
+) -> bool:
+    """
+    Checks if all expected columns are present in a `pandas.DataFrame`.
+    
+    Parameters
+    ----------
+    df : `pandas.DataFrame`
+        The DataFrame to inspect.
+    expected_columns : `list` [`str`] or `str`
+        A single column name or a list of column names to check for.
+    warning : `bool`, default `False`
+        If `True`, issue a `UserWarning` instead of raising an error.
+    
+    Returns
+    -------
+    result : `bool`
+        `True` if all expected columns are present; `False` if any are
+        missing and `warning` is `True`.
+    
+    Raises
+    ------
+    InputValidationError
+        If any expected columns are absent and `warning` is `False`.
+    """
+    # constant
+    message = "The following columns are missing from the pandas.DataFrame: {}"
+    res = True
+    # tests
+    expected_columns_set: set[str] = set(expected_columns) if isinstance(
+        expected_columns, list
+    ) else set([expected_columns])
+    
+    missing_columns = expected_columns_set - set(df.columns)
+    # return
+    if missing_columns:
+        if warning == False:
+            raise InputValidationError(
+                message.format(missing_columns)
+            )
+        else:
+            warnings.warn(
+                message.format(missing_columns)
+            )
+            res = False
+    return res
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def string_to_list(object:Any) -> Any | list[str]:
+    '''
+    Checks if `object` is a string and wraps this in a list, returns the
+    original object if it is not a string.
+    
+    Parameters
+    ----------
+    object : `Any`
+        Any object that might be a string.
+    
+    Returns
+    -------
+    string wrapped in a list or the original object type.
+    '''
+    if isinstance(object, str):
+        return [object]
+    else:
+        return object
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def _check_readable(path: str | PathLike) -> None:  # pragma: no cover
+    """
+    Do we have read access. Note this should work on a directory or file.
+    
+    Parameters
+    ----------
+    path: `str` or `PathLike`
+        A path to a directory or file.
+    """
+    if os.access(path, os.R_OK) == False:
+        raise PermissionError('You do not have read-access to: `{}`'.\
+                              format(path))
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def _check_presence(path: str | PathLike) -> None:
+    """
+    Check if a directory path exists.
+    
+    Parameters
+    ----------
+    path : `str` or `PathLike`
+        Path to a directory.
+    
+    Raises
+    ------
+    FileNotFoundError
+        If the path does not exist.
+    NotADirectoryError
+        If the path exists but is not a directory.
+    """
+    if not os.path.exists(path):
+        raise FileNotFoundError(
+            f'The path `{path}` does not exist.'
+        )
+    if not os.path.isdir(path):
+        raise NotADirectoryError(
+            f'The path `{path}` exists but is not a directory.'
+        )
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+def _check_is_file(path: str | PathLike) -> None:
+    """
+    Check if a file path exists.
+    
+    Parameters
+    ----------
+    path : `str` or `PathLike`
+        Path to a file.
+    
+    Raises
+    ------
+    FileNotFoundError
+        If the path does not exist.
+    IsADirectoryError
+        If the path exists but is not a regular file.
+    """
+    if not os.path.exists(path):
+        raise FileNotFoundError(
+            f'The file `{path}` does not exist.'
+        )
+    if not os.path.isfile(path):
+        raise IsADirectoryError(
+            f'The path `{path}` exists but is not a regular file.'
+        )
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# error messages
+class Error_MSG(object):  # pragma: no cover
+    '''
+    A collection of error messages.
+    '''
+    MISSING_SIGNAL = 'There is no `{}` data available.'
+    MISSING_DICOM='`{}` not found in DICOM file.'
+    MISSING_XML='`{}` not found in XML file.'
+    MISSING_KEY='key `{}` not found in object `{}`.'
+    MISSING_ATTR='attribute `{}` not found in object `{}`.'
+    CHOICE_PARM='`{}` is constrained to `{}`.'
+    MISSING_PATH_INSTANCE="Please supply either `path` or `{}`, but not both."
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+class Warn_MSG(object):  # pragma: no cover
+    '''
+    A collection of warning messages.
+    '''
+    MISSING_TAG='The following tags could not be found: {}.'
+    NUMB_IS_NONE = '`{}` is NoneType, cannot convert to numerical.'
+    DROP_NONE_NUMERIC = ('The following non-numerical columns were '
+                         'dropped when converting data to numpy '
+                         'arrays: %s.')
+    RESAMPLE_NO_DURATION = (
+        'Resampling to 500 Hz was requested but `duration` could not '
+        'be calculated (sampling number or sampling frequency is '
+        'None); resampling skipped for this file.'
+    )
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# error messages
+class STDOUT_MSG(object):  # pragma: no cover
+    '''
+    A collection of stdout messages.
+    '''
+    PROCESSING_PATH = 'Processing file: {}'
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+class MissingTagError(Exception):  # pragma: no cover
+    '''
+    Raises an error identifying the missing DICOM tag.
+    '''
+    def __init__(self, tag_name):
+        self.tag_name = tag_name
+        super().__init__(f"Tag '{tag_name}' is missing.")
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+class NotCalledError(Exception):  # pragma: no cover
+    """
+    Exception raised when a required __call__ method has not been used.
+    """
+    def __init__(self, message="__call__ method has not been invoked."):
+        self.message = message
+        super().__init__(self.message)
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+class FileValidationError(Exception):  # pragma: no cover
+    '''
+    General exception raised when a file was not valid
+    '''
+    def __init__(self, message="File failed to validate."):
+        self.message = message
+        super().__init__(self.message)
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+class XMLValidationError(FileValidationError):
+    """
+    Exception raised when the XML and XSD file are incompatible.
+    """
+    def __init__(self, errors: list[str]):
+        custom_message = (
+            "XML validation failed due to the following issues:\n"
+            + "\n".join(errors)
+        )
+        super().__init__(custom_message)

ecgprocess/example_data/__init__.py

@@ -0,0 +1 @@
+