Plotting signal mosaics
=======================
Low level function to produce mosaic charts of signals and annotations.
This function plots several subplots in the same figure in order to do a
mosaic with the different leads available in ECG. Annotations can be
provided individually or for all the mosaics.
Prototype
---------
The function prototype is the following.
.. code::
[ ECG_hdl axes_hdl fig_hdl all_yranges ] = plot_ecg_mosaic( ECG, varargin )
This function accepts as arguments the arg_name/arg_val method described below.
Arguments
---------
- ECG: [numeric or cell] REQUIRED
- [numeric]: signal matrix of dimension ``[sig_length sig_size repetitions_size]`` where:
- sig_length: time length in samples
- sig_size: number of ECG leads or number of signals.
- repetitions_size: number of repetitions of the same
signals. Typically used when time-synchronized events, like
heartbeats.
- [cell]: cell array of length repetitions_size, where each cell
is (probably a time alligned event) a signal of dimension
``[sig_length sig_size]``
- QRS_locations: [numeric] OPTIONAL. Synchronization sample. In ECG context, this values are
the QRS fiducial point. ``[] (default)``
- WinSize: [numeric] OPTIONAL. Width of the window around each fiducial point provided in
QRS_locations. ``[] (default)``
- ECG_header: [struct] OPTIONAL. Description of the ECG typically available in the
ECG_header as described :ref:`here<ECG_header_description>`.
- MaxECGrange: [numeric or string] OPTIONAL. Force a vertial range in order to ease visual
comparison of signals in the mosaic.
[string]
'max': force the maximum range to be the range
for all mosaics.
'min', 'mean', 'median': are also available options.
'none': Each mosaic with a different range. (Default).
- RowsCols: [numeric] OPTIONAL. Number of rows and columns of the mosaic. If ommited or if
``rows * cols ~= ECG_header.nsig``, these values are automatically adapted to the best fit
mosaic in relation to the aspect ratio of the screen.
- FigureHdl: [figure handle] OPTIONAL. Choose the figure to be produced the mosaic. ``gcf (default)``
- ECG_delineation: [struct] OPTIONAL. Annotation struct described :ref:`here<delineation_struct>`.
- ECG_annotations: [cell] OPTIONAL. Annotations to be included in the mosaic. The function accepts 2
type of annotations: points and lines. An example below shows how to define both annotations.
Output:
- ECG_hdl: handle to the plotted signals.
- axes_hdl: handle to the axes.
- fig_hdl: handle to fig.
- all_yranges: vertical ranges of the plotted signals.
Example
-------
The following example shows some typical use of the function
.. code::
win_size = 100;
sig_samp = 10000;
sig_size = 12;
event_size = 50;
x = 0.1*randn(sig_samp,sig_size);
event_locations = randsample(win_size:sig_samp-win_size, event_size);
x(event_locations-1,:) = x(event_locations-1,:) + 1;
x(event_locations+1,:) = x(event_locations+1,:) - 1;
x_packed = pack_signal(x, event_locations, win_size);
figure(1)
% estimation of the signal averaged event
plot_ecg_mosaic( mean(x_packed,3) );
Here ,,,
.. image:: mosaic1.png
.. code::
figure(2)
% visualization of all events. In this case previous pack_signal call is
% not needed.
plot_ecg_mosaic(x, 'QRS_locations', event_locations, 'WinSize', win_size);
Here ,,,
.. image:: mosaic2.png
.. code::
figure(3)
% introducing several kind of marks to the plot
h_line = cell(sig_size,7);
h2_line = cell(sig_size,7);
v_line = cell(sig_size,7);
v2_line = cell(sig_size,7);
point = cell(sig_size,7);
a_line = cell(sig_size,7);
h_line(:,1) = {'line'};
h_line(:,2) = { [ { 'String' 'LineStyle' 'LineWidth' 'Color' 'TextColor' }; ...
{ 'horizontal line text' '--' 1.5 'r' 'r' } ]'};
h_line(1:sig_size, [6 7]) = num2cell( repmat(-0.5,sig_size,2) );
h2_line(:,1) = {'line'};
h2_line(:,2) = { [ { 'String' 'LineStyle' 'LineWidth' 'Color' 'TextColor' }; ...
{ 'other h-line' '--' 1.5 'm' 'm' } ]'};
h2_line(1:sig_size, 4:7) = num2cell( [ repmat(60,sig_size,1) repmat(70,sig_size,1) repmat(0.5,sig_size,2) ] );
v_line(:,1) = {'line'};
v_line(:,2) = { [ { 'String' 'LineStyle' 'LineWidth' 'Color' 'TextColor' }; ...
{ 'vertical line text' '--' 1.5 'g' 'g' } ]'};
v_line(1:sig_size, [4 5]) = num2cell( repmat(20,sig_size,2) );
v2_line(:,1) = {'line'};
v2_line(:,2) = { [ { 'String' 'LineStyle' 'LineWidth' 'Color' 'TextColor' }; ...
{ 'other v-line' '--' 1.5 'b' 'b' } ]'};
v2_line(1:sig_size, 4:7) = num2cell( [ repmat(80,sig_size,2) repmat(-0.8,sig_size,1) repmat(-0.3,sig_size,1) ] );
point(:,1) = {'point'};
point(:,2) = { [ { 'String' 'Color' 'TextColor' }; ...
{ 'one-point' [0.2 0.3 0.4] [0.2 0.3 0.4] } ]'};
point(1:sig_size,4) = num2cell( repmat(50,sig_size,1) );
a_line(:,1) = {'line'};
a_line(:,2) = { [ { 'String' 'LineStyle' 'LineWidth' 'Color' 'TextColor' }; ...
{ 'line text' '--' 1.5 'k' 'k' } ]'};
a_line(1:sig_size,4:7) = num2cell( [ repmat(30,sig_size,1) repmat(40,sig_size,1) repmat(0.5,sig_size,1) repmat(-0.5,sig_size,1) ] );
aux_anns = cat(3,h_line,v_line,h2_line,v2_line,point,a_line);
plot_ecg_mosaic(mean(x_packed,3), 'ECG_annotations', aux_anns );
Here ,,,
.. image:: mosaic3.png
See Also
--------
:doc:`Plot ECG strip <plot_ecg_strip>`