Preparing a Challenge 2014 Entry in m-code

The new PhysioNet website is available at: https://physionet.org. We welcome your feedback.

The file entry.zip (a zip archive) is a version of a sample entry to the PhysioNet/CinC 2104 challenge written in m-code. If you wish to submit an entry written using MATLAB/Octave m-code, use the sample entry as a model. Note the tree structure in which the files are stored in the sample entry, and reproduce it in your entry.

The sample entry uses GNU Octave, version 3.6.4 (which is preinstalled in the test environment), and the WFDB Toolbox for MATLAB and Octave version 0.9.6.1 (which is installed by the sample entry's setup.sh script).

Contents of an m-code Challenge entry

The basic requirements for an m-code entry include all of those for any other entry in the Challenge. As detailed in Preparing an Entry for the Challenge on the Challenge 2014 main page, these include:

setup.sh, a bash script run once before any other code from the entry. The sample entry's setup.sh contains this code:
```
#! /bin/bash
#
# file: setup.sh
#
# Last Modified: July 25, 2014
#
# This bash script performs any setup necessary in order to test your entry.
# It is run only once, before running any other code belonging to your entry.

#Install the WFDB Toolbox in octave
unzip -o wfdb-app-toolbox-*.zip

#Change toolbxo configuration to use custom 
#native libs, which was build on Debian Wheezy
sed -i 's/WFDB_CUSTOMLIB=0;/WFDB_CUSTOMLIB=1;/' ./mcode/wfdbloadlib.m

OCTAVE='octave --quiet --eval '
STR="${OCTAVE} \"cd('mcode');addpath(pwd);savepath;quit;\""
echo "$STR"
eval ${STR}
stty sane
```
The setup.sh script in the sample entry can be used unmodified in most cases. It installs the WFDB Toolbox for MATLAB and Octave, version 0.9.6.1, which is also included in the sample entry. If you wish to use a later version of the Toolbox, simply replace the Toolbox zip file in the sources directory. The sources for the Toolbox are not required to be included in your entry if you use an unmodified Toolbox as downloaded from PhysioNet.
You will need to modify setup.sh if your entry uses a modified Toolbox that must be built from sources, or if your entry includes other code that must be compiled.

next.sh, a bash script run once per training or test record; it should analyze the record using your code, saving the results as a beat annotation file with the annotator name qrs. The sample entry's next.sh simply invokes an m-code file (challenge.m), passing it the record name as the input argument:

#! /bin/bash

# file: next.sh

# This bash script analyzes the record named in its command-line argument ($1),
# saving the results as an annotation file for the record, with annotator 'qrs'.
# This script is run once for each record in the Challenge test set.

# For example, if invoked as
#    next.sh 100
# it analyzes record 100 using 'gqrs', and saves the results as an annotation
# file named '100.qrs'.

OCTAVE='octave --quiet --eval '
RECORD=$1
RPATH=`pwd`
STR="${OCTAVE} \"challenge('$RECORD'); quit;\" 2>&1"
echo "$STR"
eval ${STR}

The next.sh script in the sample entry can also be used unmodified in your entry, provided that the signature (the set of input and output arguments) used by your version of challenge.m matches that of the sample entry's challenge.m.

AUTHORS, a plain text file listing the members of your team who contributed to your code, and their affiliations
sources/, a directory containing your code in source form; this should include the zip file containing the WFDB Toolbox (wfdb-app-toolbox-0-9-6-1.zip, or a later version) as well as sources for any custom or non-standard libraries needed (and setup.sh should include commands for building and linking any such libraries to your code)
challenge/2014/set-p/, a directory containing annotation files that you have generated using your entry on your own computer for each record in the training set; these must be named 100.qrs, 101.qrs, ..., 199.qrs. During stage 2 of the evaluation of your entry, your code generates a second set of these files on a PhysioNet evaluation server, and they are compared with the set that you submit in order to verify that your code is working as intended. If discrepancies are discovered, they are reported to you and your entry is not scored.
An Octave script, generateValidationSet.m, is provided here to help you generate the annotation files to be included in your challenge/2014/set-p directory. This script is not used during the evaluation of your entry, and you do not need to include it in your submitted zip file or tarball.

The sample entry includes an m-code file named challenge.m, which is invoked by next.sh to analyze a single test record and to write a beat annotation file for the record. Its contents are:

function challenge(recordName)
%
% challenge(recordName)
%
% Sample entry for the 2014 PhysioNet/CinC Challenge.
% This function should takes three parameters:
%
% recordName
%       String specifying the record name to process
%
% This function has no output arguments, its writes an "recordName.qrs" annotation file
% at the current directory. Do not include file extensions on the recordName string.
%
% The annotations file should contain all the beats that you were able
% to detect in the record.
%
% Dependencies:
%
%       1) This function requires that you have the WFDB
%       App Toolbox installed. For information on how to install the toolbox
%       please see:
%           http://www.physionet.org/physiotools/matlab/wfdb-app-matlab/
%
%         Please note that the Toolbox is supported only on MATLAB 2013a
%         and 2013b. Supported operating systems are 64 bit versions of:
%         Linux, Mac OS X, and Windows.
%
%       2) The CHALLENGE function requires that you have downloaded the challenge
%       data 'set-p' in a subdirectory of the current directory. The subdirectory
%       should be called '/challenge/2014/set-p/' . The 'set-p' dataset can
%       be downloaded from PhysioNet at:
%           http://physionet.org/physiobank/database/challenge/2014/
%          
%         This dataset is used by the generateValidationSet.m script to
%         create the annotations on your traing set that will be used to 
%         verify that your entry works properly in the PhysioNet testing 
%         environment. 
%
% Version 0.9
%
% See also: RDSAMP, RDANN, WRANN, GQRS, ECGPUWAVE, SQRS, WQRS, WABP
%
% Written by Ikaro Silva, December 10, 2013.
% Last Modified: February 11, 2014
%
%
%
% %Example using training data- 
% challenge('100')
%

%This line is required in order to properly load the WFDB Toolbox
%in the Octave testing framework
[~,config]=wfdbloadlib;
if(config.inOctave)
crash_dumps_octave_core(0);
end

%Used for discarding annotations that dont have a minimum number of beats
annName='qrs'; %All competitors are expected to save their annotation as *.qrs


%Get all ECG and blood pressure signals
siginfo=wfdbdesc(recordName);
description=squeeze(struct2cell(siginfo));
description=description(5,:);
ecg_ind=get_index(description,'ECG'); %Call subfunction to get channel indices
Mecg=length(ecg_ind);

%%Users can access the raw samples of the record by running the following
%command:
%[tm,signal]=rdsamp(recordName);
%
%%For more information please see the help in RDSAMP

%Annotated  the first ECG channel with GQRS and default values to generare QRS file
N=[];
N0=[];
threshold=[];
gqrs(recordName,N,N0,ecg_ind(1),threshold,annName);



%Run WABP on the record, which by default will analyze the first ABP, ART, or BP signal
bp_ind=get_index(description,'BP');
if(~isempty(bp_ind))
   wabp(recordName);
   
   %Read annotations back to compare with ECG annotations to find the one
   %with smallest RR variance (our best estimate)
  [rr_abp,~]=ann2rr(recordName,'wabp');
  [rr_ecg,~]=ann2rr(recordName,'qrs');
  [~,best]=min([var(rr_abp) var(rr_ecg)]);
   
   %If ABP has smallest annotation, overwrite the qrs file from GQRS
   if(best==1)
     movefile([recordName '.wabp'],[recordName '.' annName]);
   end
end





%%%%%%%%%%%% Helper Function %%%%%%%%%%%%%%%%%%%%%
function ind=get_index(description,pattern)
M=length(description);
tmp_ind=strfind(description,pattern);
ind=[];
for m=1:M
    if(~isempty(tmp_ind{m}))
        ind(end+1)=m;
    end
end

Together with setup.sh, next.sh, and AUTHORS, challenge.m is at the top level of the submission's file tree, not within a subdirectory (folder). You should modify challenge.m to incorporate your own methods for addressing the Challenge problem. If it makes use of other m-files, add them to the entry's top level as well.

For questions or support, please contact challenge@physionet.org.

Any updates to this sample entry will be posted here.

Setting up your computer for developing and debugging an m-code entry

Although you may develop an m-code entry using MATLAB, you should install Octave on your computer in order to test your entry for compatibililty with the test environment on PhysioNet. To do this, you will need

Octave 3.6.4 or later
Octave's Java package (liboctave-dev) 1.2.9 or later
WFDB Toolbox for MATLAB and Octave 0.9.6.1 or later

Installing Octave's Java package

To install the required Octave Java package on Debian GNU/Linux Wheezy (as on the Challenge test environment), run these commands:

apt-get install liboctave-dev
octave --eval  "setenv(\"JAVA_HOME\",\"/usr/lib/jvm/java-7-openjdk-amd64\");pkg install -forge java;quit;"

These commands have already been run in the virtual machines used to evaluate Challenge entries; do not include them in your setup.sh.

For installation on other platforms, including FreeBSD, Mac OS X, MS-Windows, OpenBSD, and other GNU/Linux distributions, see Download GNU Octave on the Octave web site.

Installing the WFDB Toolbox for MATLAB and Octave

To install the WFDB Toolbox for Octave please follow the Quick Start instructions.

You can replace wfdb-app-matlab-0-9-6-1.zip in the sources directory of your entry with any later version downloaded from the URL above.

Packaging and submitting your m-code entry

To package your entry for submission, arrange all of the files for your entry in a tree structure that matches that of the sample entry. For example, you might have these files:

/home/alice/entry/setup.sh
/home/alice/entry/next.sh
/home/alice/entry/AUTHORS
/home/alice/entry/challenge.m
/home/alice/entry/sources/wfdb-app-toolbox-0-9-6-1.zip
/home/alice/entry/challenge/2014/set-p/100.qrs
/home/alice/entry/challenge/2014/set-p/101.qrs
  ...
/home/alice/entry/challenge/2014/set-p/199.qrs

Use the cd command to set the current directory to the top level of your entry. In the case above, type:

cd /home/alice/entry

Remove any .dat or .hea files in challenge/2014/set-p (these may have been left there by generateValidationSet.m if you used it to make the .qrs annotation files). On most platforms, do this with the command:

rm -f challenge/2014/set-p/*.dat challenge/2014/set-p/*.hea

Then (on Linux, Mac OS X, or MS-Windows with Cygwin or MinGW) use either this command (to make a tarball):

tar cfvz ../entry.tar.gz .

... or this command (to make a zip archive):

zip -r ../entry.zip .

On Windows without Cygwin or MinGW, use any zip-compatible tool to make a zip archive, being careful to keep the setup.sh, etc., files on the top level (i.e., when your entry is unzipped, you should not have entry as your top directory; see the sample entry.zip file if this is not clear).