ECGwrapper
==========
.. toctree::
:hidden:
:titlesonly:
Matlab file format <Matlab_format>
Adding your own formats <custom_formats>
This class allows the access to ECG recordings of several :ref:`formats <ECG_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 <http://www.physionet.org/physiotools/wag/signal-5.htm>`__,
`ISHNE <http://thew-project.org/THEWFileFormat.htm>`__,
`AHA <https://www.ecri.org/Products/Pages/AHA_ECG_DVD.aspx>`__, HES,
:doc:`MAT <Matlab_format>`) and lengths, from seconds to days. The
objective of this class is to provide :doc:`ECGtask <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 <ECGtask>` plugged in the
`ECGtaskHandle <#inputarg_ECGtask>`__ property. Some common tasks, such
as `QRS detection <examples.html#QRS_automatic_detection>`__ and `ECG
delineation <examples.html#ECG_automatic_delineation>`__, can be easily
invoked. Also other predefined tasks or your own code can be adapted as
is shown in the :doc:`examples <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 <extensions>`.
Finally the results produced by the :doc:`ECGtask <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 <examples.html>`__.
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 <Matlab_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 <http://www.physionet.org/physiotools/wag/header-5.htm>`__.
``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 <http://www.physionet.org/physiobank/annotations.shtml>`__.
``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 <http://marketplace.aami.org/eseries/scriptcontent/docs/Preview%20Files/EC57_1212_preview.pdf>`__ 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 <http://physionet.org/>`__
- `Telemetric and Holter ECG Warehouse
(THEW) <http://thew-project.org/>`__
- `Pablo Laguna research group at University of
Zaragoza <http://diec.unizar.es/~laguna/personal/publicaciones/publicaciones.htm>`__
- `Computing in Cardiology <http://cinc.org/>`__
See Also
--------
:doc:`ECGtask <ECGtask>` \| :doc:`Examples <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