function examples(pid_str, examples_path, user_str)

% Example of how to use the ECGkit
% ---------------------------------
% 
% Description:
% 
% This script exemplifies the use of the most important features of the
% kit, which are:
% 
%  + QRS detection algorithms: (Wavedet - Pan&Tompkins - gqrs)
%  + QRS manual corrector graphical user interface (GUI)
%  + ECG waves delineator algorithm (Wavedet)
%  + Time-series manual corrector graphical user interface (GUI)
%  + Heartbeat classifier (a2hbc)
%  + ABP/PPG pulse detection/delineation ( WavePPG - wabp )
%  + Signal report generator
% 
%  This script is prepared to run locally without arguments, as well as in
%  a cluster environment by using "pid_str" argument. The pid_str
%  argument is a char with format 'N/M', being N <= M with default value
%  '1/1'. You can partition a big job into M pieces in cluster
%  architecture, by starting M processes with N ranging from 1 to M.
% 
%  You can watch a typical run of this script for small, local ECG
%  recording here:
% 
%    https://www.youtube.com/watch?v=8lJtkGhrqFw&list=PLlD2eDv5CIe9sA2atmnb-DX48FIRG46z7&index=1
% 
% Example:
% 
%    examples()
% 
% Author: Mariano Llamedo Soria (llamedom at {electron.frba.utn.edu.ar; unizar.es}
% Version: 0.1 beta
% Birthdate  : 11/2/2014
% Last update: 18/7/2014
% Copyright 2008-2015


%% Argument parsing

    if( nargin < 1 || ~ischar(pid_str) )
        % single PID run
        pid_str = '1/1';
    end
    
    if( nargin < 2 || ~exist(examples_path, 'dir') )
        % inspect ECG files in rootpath\example recordings\ folder
        root_path = fileparts(mfilename('fullpath'));
        root_path = fileparts(root_path);
        
        % default folder to look at
        
        examples_path = [root_path filesep 'recordings' filesep ];
        if(~exist(examples_path, 'dir'))
            disp_string_framed(2, 'Please provide a valid path with ECG recordings');
            return
        end
    else
        if( examples_path(end) ~= filesep )
            examples_path = [examples_path filesep];
        end
    end
    
    if( nargin < 3  )
        user_str = '';
    end
    
    %% Start
    
    % This script exemplifies the use of the toolbox in several typical
    % tasks
    
    filenames = dir(examples_path);
    recnames = {filenames(:).name};
    [~,recnames] = cellfun(@(a)(fileparts(a)), recnames, 'UniformOutput', false);
    recnames = unique(recnames);
    recnames = setdiff(recnames, {'' '.' '..' 'results' 'condor' });
%     recnames = {'ex_ABP_PPG_Registro_01M'};
%     recnames = recnames(1)
    lrecnames = length(recnames);

    % In case of running in a user-assisted fashion.
    bUseDesktop = usejava('desktop');

    if( bUseDesktop )
        tmp_path = tempdir;
        output_path = [ examples_path 'results' filesep ];
    else
        % For cluster or distributed environment processing.
        
        InstallECGkit();
        
        % this is a local path, usually faster to reach than output_path
        tmp_path = '/scratch/'; 
        
        % distributed or cluster-wide accesible path
        output_path = [ examples_path 'results' filesep ];
    end
    
% just for debugging, keep it commented.      
%     bUseDesktop = false
    
    %% QRS automatic detection
    
    % go through all files
    
    ECG_all_wrappers = [];
    jj = 1;
    
    for ii = 1:lrecnames
        
        rec_filename = [examples_path recnames{ii}];
        
        % task name, 
%         ECGt_QRSd = 'QRS_detection';
        % or create an specific handle to have more control
        ECGt_QRSd = ECGtask_QRS_detection(); 
%         % select an specific algorithm. Default: Run all detectors
%         ECGt_QRSd.detectors = 'wavedet'; % Wavedet algorithm based on
%         ECGt_QRSd.detectors = 'pantom';  % Pan-Tompkins alg.
         ECGt_QRSd.detectors = 'gqrs';    % WFDB gqrs algorithm.
%         ECGt_QRSd.detectors = 'user:example_worst_ever_QRS_detector';    % Example of how you can add your own QRS detector.
%         ECGt_QRSd.detectors = 'user:your_QRS_detector_func_name';    %
%         "your_QRS_detector_func_name" can be your own detector.
%         ECGt_QRSd.detectors = {'wavedet' 'gqrs' 'user:example_worst_ever_QRS_detector'};    
        
%         ECGt_QRSd.only_ECG_leads = false;    % consider all signals ECG
        ECGt_QRSd.only_ECG_leads = true;    % Identify ECG signals based on their header description.
        
        ECG_w = ECGwrapper( 'recording_name', rec_filename, ...
                            'this_pid', pid_str, ...
                            'tmp_path', tmp_path, ...
                            'output_path', output_path, ...
                            'ECGtaskHandle', ECGt_QRSd);
        
        % you can individualize each experiment with an external string
        ECG_w.user_string = user_str;
                        
        try
            
            % process the task
            ECG_w.Run;
            
            % collect object if were recognized as ECG recordings.
            if( jj == 1)
                ECG_all_wrappers = ECG_w;
            else
                ECG_all_wrappers(jj) = ECG_w;
            end
            jj = jj + 1;
            
        catch MException
            
            if( strfind(MException.identifier, 'ECGwrapper:ArgCheck:InvalidFormat') )
                disp_string_framed('*Red', sprintf( 'Could not guess the format of %s', ECG_w.recording_name) );
            else
                % report just in case 
                report = getReport(MException);
                fprintf(2, '\n%s\n', report);
            end
        end
    
    end
    
    % recognized recordings
    lrecnames = length(ECG_all_wrappers);
    
    % at the end, report problems if happened.
    for ii = 1:lrecnames
        ECG_all_wrappers(ii).ReportErrors;
    end
    
    %% QRS visual inspection and correction

    if( bUseDesktop )
        
        % other task can be performed on the same objects
        for ii = 1:lrecnames

            % last worker is the responsible of the visual correction.
            if( ECG_all_wrappers(ii).this_pid == ECG_all_wrappers(ii).cant_pids)

                % if there are not any previous error.
                if( ECG_all_wrappers(ii).Processed && ~ECG_all_wrappers(ii).Error ) 

                    % this is to use previous saved results as starting point,
                    % if any available
                    cached_filenames = ECG_all_wrappers(ii).GetCahchedFileName({'QRS_corrector' 'QRS_detection'});

                    % if no previous correction work, try the automatic
                    % detection task
                    
                    % if any, do the correction
                    if( ~isempty(cached_filenames) )

                        % this is to use previous saved results as starting point,
                        % if any available
                        ECG_all_wrappers(ii).ECGtaskHandle = 'QRS_corrector';
                        
                        % This task is supposed to be supervised, so only one pid is enough.
                        ECG_all_wrappers(ii).this_pid = '1/1';

                        % to avoid loading cached results and exit, this flag
                        % allows the re-editing of the current state of the
                        % detections.
                        ECG_all_wrappers(ii).cacheResults = false;

                        % maybe in your application you should run this for
                        % all files.
                        ECG_all_wrappers(ii).ECGtaskHandle.payload = load(cached_filenames{1});

                        % process the task
                        ECG_all_wrappers(ii).Run;

                        % restore the original pids configuration
                        ECG_all_wrappers(ii).this_pid = pid_str;

                        % As we changed for "QRS correction" task, we have to enable this
                        % value again in order to avoid performing the following tasks every time.
                        % If you want to recalculate any task, change it to false
                        ECG_all_wrappers(ii).cacheResults = true;
                        
                    end


                end

            end

        end

        % at the end, report problems if happened.
        for ii = 1:lrecnames
            ECG_all_wrappers(ii).ReportErrors;
        end

    end
    
    %% PPG/ABP pulse detection
    
    % other task can be performed on the same objects
    for ii = 1:lrecnames

        % set the delineator task name and run again.
        ECG_all_wrappers(ii).ECGtaskHandle = 'PPG_ABP_detector';

        % process the task
        ECG_all_wrappers(ii).Run;
        
    end

    % at the end, report problems if happened.
    for ii = 1:lrecnames
        ECG_all_wrappers(ii).ReportErrors;
    end
    
    %% PPG/ABP waves visual inspection and correction

    if( bUseDesktop )
        
        % other task can be performed on the same objects
        for ii = 1:lrecnames

            % last worker is the responsible of the visual correction.
            if( ECG_all_wrappers(ii).this_pid == ECG_all_wrappers(ii).cant_pids)

                % if there are not any previous error.
                if( ECG_all_wrappers(ii).Processed && ~ECG_all_wrappers(ii).Error ) 

                    % this is to use previous saved results as starting point,
                    % if any available
                    cached_filenames = ECG_all_wrappers(ii).GetCahchedFileName({'PPG_ABP_corrector' 'PPG_ABP_detector'});

                    % if no previous correction work, try the automatic
                    % detection task
                    
                    % if any, do the correction
                    if( ~isempty(cached_filenames) )

                        % this is to use previous saved results as starting point,
                        % if any available
                        ECG_all_wrappers(ii).ECGtaskHandle = 'PPG_ABP_corrector';
                        
                        % This task is supposed to be supervised, so only one pid is enough.
                        ECG_all_wrappers(ii).this_pid = '1/1';
                        
                        % to avoid loading cached results and exit, this flag
                        % allows the re-editing of the current state of the
                        % detections.
                        ECG_all_wrappers(ii).cacheResults = false;

                        % maybe in your application you should run this for
                        % all files.
                        ECG_all_wrappers(ii).ECGtaskHandle.payload = load(cached_filenames{1});

                        % process the task
                        ECG_all_wrappers(ii).Run;

                        % restore the original pids configuration
                        ECG_all_wrappers(ii).this_pid = pid_str;

                        % As we changed for "QRS correction" task, we have to enable this
                        % value again in order to avoid performing the following tasks every time.
                        % If you want to recalculate any task, change it to false
                        ECG_all_wrappers(ii).cacheResults = true;
                        
                    end


                end

            end

        end

        % at the end, report problems if happened.
        for ii = 1:lrecnames
            ECG_all_wrappers(ii).ReportErrors;
        end

    end
        
    %% ECG automatic delineation
    
    % other task can be performed on the same objects
    for ii = 1:lrecnames
        
        % this is to use previous cached results as starting point
        cached_filenames = ECG_all_wrappers(ii).GetCahchedFileName('QRS_corrector');

        % set the delineator task name and run again.
        ECG_all_wrappers(ii).ECGtaskHandle = 'ECG_delineation';
        
        % if corrected QRS detections are not available, wavedet
        % performs automatic QRS detection.
        if( ~isempty(cached_filenames) )
            % this is to use previous result from the automatic QRS
            % detection
            ECG_all_wrappers(ii).ECGtaskHandle.payload = load(cached_filenames{1});

        end

%         ECGt_QRSd.detectors = 'wavedet'; % Wavedet algorithm based on
%         ECGt_QRSd.detectors = 'user:example_worst_ever_ECG_delineator';
%         % Example of how you can add your own ECG delineator. 
%         ECGt_QRSd.detectors = 'user:your_ECG_delineator_func_name';    
%         "your_ECG_delineator_func_name" can be your own delineator.
        ECG_all_wrappers(ii).ECGtaskHandle.delineators = {'wavedet' 'user:example_worst_ever_ECG_delineator'};
        
        % process the task
        ECG_all_wrappers(ii).Run;
        
    end

    % at the end, report problems if happened.
    for ii = 1:lrecnames
        ECG_all_wrappers(ii).ReportErrors;
    end
    
    %% Visual inspection of the detection/delineation
    
    if( bUseDesktop )

        % other task can be performed on the same objects
        for ii = 1:lrecnames

            % last worker is the responsible of the visual correction.
            if( ECG_all_wrappers(ii).this_pid == ECG_all_wrappers(ii).cant_pids)

                % if there are not any previous error.
                if( ECG_all_wrappers(ii).Processed && ~ECG_all_wrappers(ii).Error ) 

                    % this is to use previous saved results as starting point,
                    % if any available
                    cached_filenames = ECG_all_wrappers(ii).GetCahchedFileName( {'ECG_delineation_corrector' 'ECG_delineation'} );

                    % if no previous correction work, try the automatic
                    % detection task
                    
                    % if any, do the correction
                    if( ~isempty(cached_filenames) )

                        % this is to use previous saved results as starting point,
                        % if any available
                        ECG_all_wrappers(ii).ECGtaskHandle = 'ECG_delineation_corrector';
                        
                        % This task is supposed to be supervised, so only one pid is enough.
                        ECG_all_wrappers(ii).this_pid = '1/1';

                        % to avoid loading cached results and exit, this flag
                        % allows the re-editing of the current state of the
                        % detections.
                        ECG_all_wrappers(ii).cacheResults = false;

                        % maybe in your application you should run this for
                        % all files.
                        ECG_all_wrappers(ii).ECGtaskHandle.payload = load(cached_filenames{1});

                        % process the task
                        ECG_all_wrappers(ii).Run;

                        % restore the original pids configuration
                        ECG_all_wrappers(ii).this_pid = pid_str;

                        % As we changed for "QRS correction" task, we have to enable this
                        % value again in order to avoid performing the following tasks every time.
                        % If you want to recalculate any task, change it to false
                        ECG_all_wrappers(ii).cacheResults = true;
                        
                    end

                end

            end

        end

        % at the end, report problems if happened.
        for ii = 1:lrecnames
            ECG_all_wrappers(ii).ReportErrors;
        end

    end
    
    %% Automatic Heartbeat classification
    
    % other task can be performed on the same objects
    for ii = 1:lrecnames
        
        % this is to use previous cached results as starting point
        cached_filenames = ECG_all_wrappers(ii).GetCahchedFileName({'QRS_corrector' 'QRS_detection'});
        % if corrected QRS detections are not available, wavedet
        % performs automatic QRS detection.
        
        if( ~isempty(cached_filenames) )
            
            ECG_all_wrappers(ii).ECGtaskHandle = 'ECG_heartbeat_classifier';

            ECG_all_wrappers(ii).ECGtaskHandle.payload = load(cached_filenames{1});

            % process the task
            ECG_all_wrappers(ii).Run;

        end

    end

    % at the end, report problems if happened.
    for ii = 1:lrecnames
        ECG_all_wrappers(ii).ReportErrors;
    end
    
    %% Visual inspection of the signal
    

    filename = []; % default setting. Let the report function decide.
%     filename = 'container_filename'; % to put everything in one big file.
    
    % other winlengths can be added to the array in order to further
    % explore the recordings, and the algorithm results.
%     winlengths = []; % default setting
    winlengths = [ 7 ]; %seconds
    
    % go through all files
    for ii = 1:lrecnames

        % last worker is the responsible of the reporting.
        if( ECG_all_wrappers(ii).this_pid == ECG_all_wrappers(ii).cant_pids)

            try

                reportECG(ECG_all_wrappers(ii), 'LowDetail', 'full', winlengths, 'pdf', [] );
        %         reportECG(ECG_all_wrappers(ii), 'LowDetail', 'full', winlengths, 'png', filename);
            catch MException

                report = getReport(MException);

                disp_string_framed(2, ECG_all_wrappers(ii).recording_name)
                fprintf(2, '\n%s\n', report);

            end

        end
        
    end
    
    %% other user-defined tasks ...
        
    if( ~bUseDesktop )
    
        UnInstallECGkit();
        
    end