ECGwrapper ========== .. toctree:: :hidden: :titlesonly: Matlab file format Adding your own formats This class allows the access to ECG recordings of several :ref:`formats ` and length. Syntax ------ You can create an object without arguments, configuring its properties later. Or you can create it via pairs of PropertyName-PropertyValue pairs. .. code:: ECGw = ECGwrapper() ECGw = ECGwrapper( 'PropertyName', PropertyValue )   Description ----------- This is the main class of the toolbox since it allows access to cardiovascular signal recordings of several formats (`MIT `__, `ISHNE `__, `AHA `__, HES, :doc:`MAT `) and lengths, from seconds to days. The objective of this class is to provide :doc:`ECGtask `  class, a common interface to access data and perform specific tasks. Briefly, this class sequentially reads data and passes to the Process method of the :doc:`ECGtask ` plugged in the `ECGtaskHandle <#inputarg_ECGtask>`__ property. Some common tasks, such as `QRS detection `__ and `ECG delineation `__, can be easily invoked. Also other predefined tasks or your own code can be adapted as is shown in the :doc:`examples `. A more detailed description of this class, together with an explanation of how you can easily hook your algorithms to this class is :doc:`here `. Finally the results produced by the :doc:`ECGtask ` are stored in order to ease reproducibility and backup of your experiments, or to be used of subsequent tasks as shown in the `examples `__.   Input Arguments --------------- Specify optional comma-separated pairs of ``'Name', Value`` arguments. ``'Name'`` is the argument/property name and ``Value`` is the corresponding value. ``'Name'`` must appear inside single quotes ``' '``. You can specify several name and value pair arguments in any order as ``Name1,Value1,...,NameN,ValueN``. **Example:** .. code:: % specifies to create an ECGwrapper to detect % heartbeats in recording '/ecg_recordings/rec1.dat' ECGwrapper('recording_name','/ecg_recordings/rec1.dat', 'ECGtaskHandle', 'QRS_detection') The available arguments for the class constructor are listed below: ``'recording_name'`` — The ECG recording full name. ``'' (default)`` The full path filename of the ECG recording. ``'recording_format'`` — ECG recording format. ``auto-detect format (default)`` .. _ECG_formats: The format of the ECG recording. By default or if not specified, the wrapper will attempt to auto-detect the format among the following table: +---------+--------------------------------------------------------------------+ | String | Description | +=========+====================================================================+ | MIT | `MIT format`_ | +---------+--------------------------------------------------------------------+ | ISHNE | `ISHNE format`_ | +---------+--------------------------------------------------------------------+ | AHA | `American Heart Association ECG Database`_ or `AHA in Physionet`_ | +---------+--------------------------------------------------------------------+ | HES | Biosigna format | +---------+--------------------------------------------------------------------+ | MAT | :doc:`Matlab file format ` | +---------+--------------------------------------------------------------------+ | Mortara | Mortara SuperECG format | +---------+--------------------------------------------------------------------+ ``'this_pid'`` — Process identification for multiprocess batch jobs. ``'1/1' (default)`` In case working in a multiprocess environment, this value will identify the current process. Can be a numeric value, or a string of the form 'N/M'. This pid is N and the total amount of pid's to divide the whole work is M. ``'tmp_path'`` — The path to store temporary data. ``tempdir() (default)`` Full path to a directory with write privileges. ``'output_path'`` — The output path to store results. ``fileparts(recording_name) (default)`` Full path to a directory with write privileges. By default will be the same path of the recordings. ``'ECGtaskHandle'`` — The task to perform. ``'' (default)`` The task to perform, can be the name of the task, or an ECGtask object. Available ECGtasks can be listed with ```list_all_ECGtask()`` command. ``'partition_mode'`` — The way that this object will partition lengthy signals. ``'ECG_overlapped' (default)`` The way to do batch partition in lengthy signals: - 'ECG\_contiguous' no overlapp between segments. - 'ECG\_overlapped' overlapp of 'overlapping\_time' among segments. This can be useful if your task have a transient period to avoid. - 'QRS' do the partition based on the annotations provided in ECG\_annotations.time property. This option is useful if your task works in the boundaries of a fiducial point (commonly a heartbeat), and not in the whole signal. This partition mode ignores those parts of the recording without annotations. ``'overlapping_time'`` — Time in seconds of overlapp among consequtive segments. ``30 (default)`` Time in seconds of overlapp among consequtive segments. This segment is useful for ensuring the end of all transients within a task. ``'cacheResults'`` — Save intermediate results to recover in case of failure. ``true (default)`` Save intermediate results to recover in case of errors. Useful for long jobs or recordings. ```'syncSlavesWithMaster'`` — Time in seconds of overlapp among consequtive segments. ``false (default)`` In multiprocess environments sometimes it is useful to terminate all pid's together in order to start subsequent tasks synchronously. This value forces all parts of a multipart process to wait until all other parts finish. ``'repetitions'`` — Times to repeat the ECGtask. ``1 (default)`` In case the ECGtask is not deterministic, the repetition property allows to repeat the task several times. Other public properties to configure the object, or to access recording's data are: ``Error`` — Did the ECGtask produce any Error ? ``false (default)`` You can check this value after executing a task. ``Processed`` — Was the task already processed ? ``false (default)`` You can check if you have already issued a Run method for the current configuration. ``NoWork2Do`` — Has this PID work to do ? In a multi-PID environment, certain tasks are too short to provide work to all configured PIDs. You can check to this flag to deal with it in your code. .. _ECG_header_description: ``ECG_header`` — The gathered information about the ECG recording. **ECG\_header**, is a struct with the following information: - *freq*, is the sampling frequency of ECG\_matrix signal. - *desc*, description strings about each of the leads/signals. - *nsamp* is the number of samples of ECG\_matrix. - *nsig* is the amount of leads or signals of ECG\_matrix. - *gain* is a vector of [nsig × 1] with the gain of each lead ( ADCsamples / μV ). - *adczero* is a vector of [nsig × 1] with the offset of each lead in ADC samples. and others described in the `Physionet header `__. ``ECG_annotations`` — Annotations provided with the recording. Commonly QRS detections, signal quality annotations or other type of measurements included with the recordings. Some documentation about annotations in `Physionet `__. ``class_labeling`` — Class conversion for heartbeat annotations. In case the annotations includes heartbeat types, this property indicates the class-labeling convention used. The `EC-57 AAMI recommendation `__ is de default value. The possible values are ``'AAMI'`` or ``AAMI2``. The ``AAMI2`` is equal to ``AAMI`` except that only consider three heartbeat classes, *normal* (N), *ventricular* (V) and *supraventricular* (S). ``user_string`` — A string to individualize each experiment. ``'' (default)`` ``Result_files`` — The result filenames produced by an ECGtask. Once the task is completed, this property records the filenames of the results. Methods ------- Some useful methods are described below.   ``Run`` — Execute the ECG task This method executes the configured ECG task. ``read_signal`` — Read signal samples This method allows to easily reads samples from a recording .. code:: % function prototype          function ECG = read_signal(ECG_start_idx, ECG_end_idx) where the arguments are: **ECG\_start\_idx**, is the first sample to read. ``1 (default)``. **ECG\_end\_idx**, is the last sample to read. ``ECG\_header.nsamp (default)`` and as a result, it returns: **ECG**, which is a matrix of size ``[(ECG\_end\_idx - ECG\_start\_idx + 1) ECG\_header.nsig] (default)`` as it is exemplified below .. code:: % reads ECG 100 samples ECG = ECG_w.read_signal(1, 99); ``ReportErrors`` — Display the error report generated during the task execution This method reports error generated during task execution. ``GetCahchedFileName`` — Find the result files of an specific recording/task This method returns the cached filename for an specific recording, and task, if available. .. code:: % Get result filename of previous QRS detection. % The corrected/audited version has precedence if available. cached_filenames = ECGw.GetCahchedFileName({'QRS_corrector' 'QRS_detection'});   Examples -------- Create the simplest ECG wrapper object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Create the ECGwrapper object. .. code:: >> ECG_w = ECGwrapper() ECG_w = ############################ # ECGwrapper object config # ############################ +ECG recording: None selected +PID: 1/1 +Repetitions: 1 +Partition mode: ECG_overlapped +Function name: Null task +Processed: false Then, in your script or in the command window you can type: .. code:: >> ECG_w.recording_name = 'some_path\100'; >> ECG_w.ECGtaskHandle = 'QRS_detection' ECG_w = ############################ # ECGwrapper object config # ############################ +ECG recording: some_path\100 (auto) +PID: 1/1 +Repetitions: 1 +Partition mode: ECG_overlapped +Function name: QRS_detection +Processed: false Now, you just want to run the task by executing: .. code:: >> ECG_w.Run(); Create an ECGwrapper object for an specific recording and task ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In this case, we create the same object of the previous example but using the name-value . .. code:: >> ECG_w = ECGwrapper( ... 'recording_name', 'some_path\100', ... 'recording_format', 'MIT', ... 'ECGtaskHandle', 'QRS_detection', ... ) ECG_w = ############################ # ECGwrapper object config # ############################ +ECG recording: some_path\100 (auto) +PID: 1/1 +Repetitions: 1 +Partition mode: ECG_overlapped +Function name: QRS_detection +Processed: false >> ECG_w.Run();   Create an ECGwrapper and access the recording data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In this case, we create an object and access to the ``ECG_header`` property. .. code-block:: none >> ECGw = ECGwrapper( 'recording_name', 'd:\mariano\misc\ecg-kit\recordings\208') ECGw = ############################ # ECGwrapper object config # ############################ +ECG recording: d:\mariano\misc\ecg-kit\recordings\208 (auto) +PID: 1/1 +Repetitions: 1 +Partition mode: ECG_overlapped +Function name: Null task +Processed: false >> ECGw.ECG_header ans = recname: '208' nsig: 2 freq: 360 nsamp: 650000 btime: '00:00:00' bdate: '01/01/2000' spf: [2x1 double] baseline: [2x1 double] units: [2x2 char] fname: [2x7 char] group: [2x1 double] fmt: [2x1 double] gain: [2x1 double] adcres: [2x1 double] adczero: [2x1 double] initval: [2x1 double] cksum: [2x1 double] bsize: [2x1 double] desc: [2x5 char] Then we get the first 1000 signal samples using the ``read_signal`` method. .. code-block:: none >> plot(ECGw.read_signal(1,1000)) as result we obtain the following plot .. image:: read_signal_example.png Other resources --------------- - `Physionet.org `__ - `Telemetric and Holter ECG Warehouse (THEW) `__ - `Pablo Laguna research group at University of Zaragoza `__ - `Computing in Cardiology `__ See Also -------- :doc:`ECGtask ` \| :doc:`Examples ` .. _`MIT format`: http://www.physionet.org/physiotools/wag/signal-5.htm .. _`ISHNE format`: http://thew-project.org/THEWFileFormat.htm .. _`American Heart Association ECG Database`: https://www.ecri.org/Products/Pages/AHA_ECG_DVD.aspx .. _`AHA in Physionet`: http://www.physionet.org/physiotools/old/dbpg/dbu_84.htm