
ECG delineation
===============

This document describes how to perform automatic delineation or wave
segmentation on ECG signals.

Description
-----------

Automatic wave segmentation or delineation is exclusively performed by 
`wavedet <http://diec.unizar.es/~laguna/personal/publicaciones/wavedet_tbme04.pdf>`__ algorithm.

Input Arguments
---------------

The properties that this task uses are the following:

``progress_handle`` — Used to track the progress within your function. ``[] (default)``

	progress\_handle, is a handle to a :doc:`progress\_bar <progress_bar>`
	object, that can be used to track the progress within your function.

``tmp_path`` — The path to store temporary data. ``tempdir() (default)``

	Full path to a directory with write privileges.

``delineators`` — The ECG delineation algorithms to use ``'all-delineators' (default)``

	This property controls which algorithms are used. A cell string or char with any of the following names

	- *'all-delineators'*

	- `'wavedet' <http://diec.unizar.es/~laguna/personal/publicaciones/wavedet_tbme04.pdf>`__

 

``only_ECG_leads`` — Process only ECG signals ``true (default)`` 

	Boolean value. Find out which signals are ECG based on their ``ECG_header.desc`` 
	description.

``wavedet_config`` — A structure for configuring wavedet algorithm. ``[] (default)`` 

	Undocumented yet, use it only if you know what you are doing.

``payload`` — An arbitrary format variable. ``[] (default)`` 

	This variable can be useful for passing data to your own delineation function
	(described :ref:`below <Adding_a_custom_delineation_algorithm>`) or to
	provide visually audited QRS detections to the delineation algorithm.

.. _Adding_a_custom_delineation_algorithm:

Adding a custom delineation algorithm
-------------------------------------

Adding your own delineator to the kit is very simple. Ensure that your
function implements this interface:

.. code::

    function [positions_single_lead, position_multilead] = 
	
		your_ECG_delineation( ECG_matrix, ECG_header, progress_handle, payload_in)  
                            

where the arguments are:

	**ECG\_matrix**, is a matrix size [ECG\_header.nsamp ECG\_header.nsig]

	.. _ECG_header_description:
	
	**ECG\_header**, is a struct with info about the ECG signal, such as:

		- *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>`__.

	**progress\_handle**, is a handle to a `progress\_bar <progress_bar.htm>`__
	object, that can be used to track the progress within your function.

	**payload\_in**, is a user variable, of arbitrary format, allowed to be sent
	to your function. It is sent via the :ref:`payload property <payload_prop>` 
	of this class, for example:

.. code::
	
	% One variable
	this_ECG_wrapper.ECGtaskHandle.payload = your_variable;
	
	% Several variables with a cell container
	this_ECG_wrapper.ECGtaskHandle.payload = {your_var1 your_var2};
	
	% Or the result of a previous task, in this case QRS manual correction (if available)
	% or the automatic detection if not.
	cached_filenames = this_ECG_wrapper.GetCahchedFileName({'QRS_corrector' 'QRS_detection'});
	this_ECG_wrapper.ECGtaskHandle.payload = load(cached_filenames);

and the output of your function must be:

.. _delineation_struct:

	**positions\_single\_lead**, is an **structure array** of ``ECG_header.nsig`` elements with *at least* the following wave fiducial points as fields:
	
	- ``'Pon'`` P wave onset
	- ``'P'`` P wave peak
	- ``'Poff'`` P wave offset
	- ``'QRSon'`` QRS complex onset
	- ``'qrs'`` QRS fiducial point, obtained from QRS detection.
	- ``'Q'`` Q wave peak
	- ``'R'`` R wave peak
	- ``'S'`` S wave peak
	- ``'QRSoff'`` QRS complex offset
	- ``'Ton'`` T wave onset
	- ``'T'`` T wave peak
	- ``'Toff'`` T wave offset

	**position\_multilead**, is a single structure with *at least* the wave fiducial points described above.
	This delineation is commonly calculated from the single lead delineations, in order to obtain a unique wave 
	fiducial point per heartbeat.
	

Examples
--------

Create the *ECGtask\_ECG\_delineation* object.

.. code::

    % with the task name
        ECG_w.ECGtaskHandle = 'ECG_delineation';
    % or create an specific handle to have more control
        ECGt = ECGtask_ECG_delineation();

and then you are ready to set the algorithms to use. In the following
example you have several possible set-ups.

.. code::

    % select an specific algorithm. Default: Run all detectors
            ECGt.delineators = 'wavedet'; % Wavedet algorithm based on
            % "your_delineator_func_name" can be your own delineator.
			ECGt.delineators = 'user:your_delineator_func_name';    
            ECGt.delineators = {'wavedet' 'user:your_delineator_func_name'};
                            

Finally set the task to the wrapper object, and execute the task.

.. code::

            ECG_w.ECGtaskHandle= ECGt; % set the ECG task
            ECG_w.Run();

You can check the result of this task, with either the :doc:`delineator
corrector <ECG_delineation_corrector>` or the :doc:`visualization
functions <plot_ecg_strip>`.

Also check this :ref:`example <ECG_automatic_delineation>`
for further information.

.. _Delineation_result_format:

Results format
--------------
 
The result file will have a ``struct`` variable with the name of the algorithm (only *wavedet* at the time of 
writing this). Inside this, it will contain one :ref:`delineation struct <delineation_struct>` per ECG lead 
in the ``ECG_header.desc`` field, plus another called ``multilead`` which is a delineation accounting with the 
information present in all leads.


More About
----------

This publication describes the
`wavedet <http://diec.unizar.es/~laguna/personal/publicaciones/wavedet_tbme04.pdf>`__
algorithm.

See Also
--------

 :doc:`ECGtask <ECGtask>` \| :doc:`QRS detection <QRS_detection>` \| :doc:`examples <examples>`

