Skip to content

Commit 8a45306

Browse files
cx1111cx1111
committed
refactor annotations library and change many class attribute names
1 parent 646af3e commit 8a45306

File tree

3 files changed

+149
-134
lines changed

3 files changed

+149
-134
lines changed

‎README.rst

Lines changed: 93 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -107,29 +107,38 @@ file with 'rdann'.
107107
The attributes of the Annotation object give information about the annotation as specified
108108
by https://www.physionet.org/physiotools/wag/annot-5.htm:
109109

110-
- ``annsamp``: The annotation location in samples relative to the beginning of the record.
111-
- ``anntype``: The annotation type according the the standard WFDB codes.
112-
- ``subtype``: The marked class/category of the annotation.
113-
- ``chan``: The signal channel associated with the annotations.
114-
- ``num``: The labelled annotation number.
115-
- ``aux``: The auxiliary information string for the annotation.
116-
- ``fs``: The sampling frequency of the record if contained in the annotation file.
117-
- ``custom_anntypes``: The custom annotation types defined in the annotation file. A dictionary with {key:value} corresponding to {anntype:description}. eg. {'#': 'lost connection', 'C': 'reconnected'}
110+
- ``recordname``: The base file name (without extension) of the record that the annotation is attached to.
111+
- ``extension``: The file extension of the file the annotation is stored in.
112+
- ``sample``: The annotation locations in samples relative to the beginning of the record.
113+
- ``symbol``: The annotation type according the the standard WFDB codes.
114+
- ``subtype``: The marked class/category of each annotation.
115+
- ``chan``: The signal channel associated with each annotations.
116+
- ``num``: The labelled annotation number for each annotation.
117+
- ``aux_note``: The auxiliary information string for each annotation.
118+
- ``fs``: The sampling frequency of the record, if available.
119+
- ``label_store``: The integer value used to store/encode each annotation label
120+
- ``description``: The descriptive string of each annotation label
121+
- ``custom_labels``: The custom annotation labels defined in the annotation file.
122+
Maps the relationship between the three label fields.
123+
The data type is a pandas DataFrame with three columns: ['label_store', 'symbol', 'description']
124+
- ``contained_labels``: The unique labels contained in this annotation. Same structure
125+
as custom_labels.
126+
118127

119128
Constructor function:
120129
::
130+
def __init__(self, recordname, extension, sample, symbol=None, subtype=None,
131+
chan=None, num=None, aux_note=None, fs=None, label_store=None,
132+
description=None, custom_labels=None, contained_labels=None)
121133

122-
def __init__(self, recordname, annotator, annsamp, anntype, subtype = None,
123-
chan = None, num = None, aux = None, fs = None, custom_anntypes = None)
124-
125-
Call `showanncodes()` to see the list of standard annotation codes. Any text used to label annotations that are not one of these codes should go in the 'aux' field rather than the 'anntype' field.
134+
Call `showanncodes()` to see the list of standard annotation codes. Any text used to label annotations that are not one of these codes should go in the 'aux_note' field rather than the 'symbol' field.
126135

127136
Example usage:
128137
::
129138

130139
import wfdb
131-
ann1 = wfdb.Annotation(recordname='ann1', annotator='atr', annsamp=[10,20,400],
132-
anntype = ['N','N','['], aux=[None, None, 'Serious Vfib'])
140+
ann1 = wfdb.Annotation(recordname='ann1', annotator='atr', sample=[10,20,400],
141+
symbol = ['N','N','['], aux_note=[None, None, 'Serious Vfib'])
133142

134143
Reading Signals
135144
~~~~~~~~~~~~~~~
@@ -189,10 +198,10 @@ Output arguments:
189198

190199
- ``signals``: A 2d numpy array storing the physical signals from the record.
191200
- ``fields``: A dictionary specifying several key attributes of the read record:
192-
- ``fs``: The sampling frequency of the record
193-
- ``units``: The units for each channel
194-
- ``signame``: The signal name for each channel
195-
- ``comments``: Any comments written in the header
201+
- ``fs``: The sampling frequency of the record
202+
- ``units``: The units for each channel
203+
- ``signame``: The signal name for each channel
204+
- ``comments``: Any comments written in the header
196205

197206

198207
Writing Signals
@@ -245,7 +254,8 @@ Reading Annotations
245254

246255
::
247256

248-
annotation = rdann(recordname, annotator, sampfrom=0, sampto=None, shiftsamps=False, pbdir=None)
257+
annotation = rdann(recordname, extension, sampfrom=0, sampto=None, shiftsamps=False,
258+
pbdir=None, return_label_elements=['symbol'], summarize_labels=False)
249259

250260
Example Usage:
251261
::
@@ -256,66 +266,100 @@ Example Usage:
256266
Input arguments:
257267

258268
- ``recordname`` (required): The record name of the WFDB annotation file. ie. for file `100.atr`, recordname='100'
259-
- ``annotator`` (required): The annotator extension of the annotation file. ie. for
260-
file '100.atr', annotator='atr'
269+
- ``extension`` (required): The annotatator extension of the annotation file. ie. for
270+
file '100.atr', extension='atr'
261271
- ``sampfrom`` (default=0): The minimum sample number for annotations to be returned.
262272
- ``sampto`` (default=None): The maximum sample number for annotations to be returned.
263-
- ``shiftsamps`` (default=False): Boolean flag that specifies whether to return the sample indices relative to 'sampfrom' (True), or sample 0 (False). Annotation files store exact sample locations.
264-
- ``pbdir`` (default=None): Option used to stream data from Physiobank. The Physiobank database directory from which to find the required annotation file. eg. For record '100' in 'http://physionet.org/physiobank/database/mitdb', pbdir = 'mitdb'.
273+
- ``shiftsamps`` (default=False): Boolean flag that specifies whether to return the
274+
sample indices relative to 'sampfrom' (True), or sample 0 (False). Annotation files
275+
store exact sample locations.
276+
- ``pbdir`` (default=None): Option used to stream data from Physiobank. The Physiobank database
277+
directory from which to find the required annotation file.
278+
eg. For record '100' in 'http://physionet.org/physiobank/database/mitdb', pbdir = 'mitdb'.
279+
- ``return_label_elements`` (default=['symbol']): The label elements that are to be returned
280+
from reading the annotation file. A list with at least one of the following: 'symbol',
281+
'label_store', 'description'.
282+
- ``summarize_labels`` (default=False): Assign a summary table of the set of annotation labels
283+
contained in the file to the 'contained_labels' attribute of the returned object.
284+
This table will contain the columns: ['label_store', 'symbol', 'description', 'n_occurences']
265285

266286
Output arguments:
267287

268288
- ``annotation``: The Annotation object. Contains the following attributes:
269-
- ``annsamp``: The annotation location in samples relative to the beginning of the record.
270-
- ``anntype``: The annotation type according the the standard WFDB codes.
271-
- ``subtype``: The marked class/category of the annotation.
272-
- ``chan``: The signal channel associated with the annotations.
273-
- ``num``: The labelled annotation number.
274-
- ``aux``: The auxiliary information string for the annotation.
275-
- ``fs``: The sampling frequency of the record if contained in the annotation file.
289+
- ``recordname``: The base file name (without extension) of the record that the annotation is attached to.
290+
- ``extension``: The file extension of the file the annotation is stored in.
291+
- ``sample``: The annotation locations in samples relative to the beginning of the record.
292+
- ``symbol``: The annotation type according the the standard WFDB codes.
293+
- ``subtype``: The marked class/category of each annotation.
294+
- ``chan``: The signal channel associated with each annotations.
295+
- ``num``: The labelled annotation number for each annotation.
296+
- ``aux_note``: The auxiliary information string for each annotation.
297+
- ``fs``: The sampling frequency of the record, if available.
298+
- ``label_store``: The integer value used to store/encode each annotation label
299+
- ``description``: The descriptive string of each annotation label
300+
- ``custom_labels``: The custom annotation labels defined in the annotation file.
301+
Maps the relationship between the three label fields.
302+
The data type is a pandas DataFrame with three columns: ['label_store', 'symbol', 'description']
303+
- ``contained_labels``: The unique labels contained in this annotation. Same structure
304+
as custom_labels.
276305

277-
\*\ **NOTE**: In annotation files, every annotation contains the ‘annsamp’ and ‘anntype’ field. All other fields default to 0 or empty if not present.
306+
\*\ **NOTE**: In annotation files, every annotation contains the ‘sample’ and ‘symbol’ field. All other fields default to 0 or empty if not present.
278307

279-
**showanncodes** - Display the annotation symbols and the codes they represent according to the standard WFDB library 10.5.24
308+
**show_ann_labels** - Display the annotation symbols and the codes they represent according to the standard WFDB library 10.5.24
280309

281310
::
282311

283-
showanncodes()
312+
show_ann_labels()
284313

285314
Writing Annotations
286315
~~~~~~~~~~~~~~~~~~~
287316

288-
The Annotation class has a **wrann** instance method.
289-
290317
The Annotation class has a **wrann** instance method for writing wfdb annotation files. Create a valid Annotation object and call ``annotation.wrsamp()``. In addition, there is also the following simpler module level **wrann** function.
291318

292319
**wrann** - Write a WFDB annotation file.
293320

294321
::
295322

296-
wrann(recordname, annotator, annsamp, anntype, num = None, subtype = None, chan = None, aux = None, fs = None)
323+
wrann(recordname, extension, sample, symbol=None, subtype=None, chan=None, num=None, aux_note=None, label_store=None, fs=None, custom_labels=None)
297324

298325
Example Usage:
299326

300327
::
301328

302329
import wfdb
303330
annotation = wfdb.rdann('b001', 'atr', pbdir='cebsdb')
304-
wfdb.wrann('b001', 'cpy', annotation.annsamp, annotation.anntype)
331+
wfdb.wrann('b001', 'cpy', annotation.sample, annotation.symbol)
305332

306333
Input Arguments:
307334

308335
- ``recordname`` (required): The string name of the WFDB record to be written (without any file extensions).
309-
- ``annotator`` (required): The string annotation file extension.
310-
- ``annsamp`` (required): The annotation location in samples relative to the beginning of the record. List or numpy array.
311-
- ``anntype`` (required): The annotation type according the the standard WFDB codes. List or numpy array.
312-
- ``subtype`` (default=None): The marked class/category of the annotation. List or numpy array.
313-
- ``chan`` (default=None): The signal channel associated with the annotations. List or numpy array.
314-
- ``num`` (default=None): The labelled annotation number. List or numpy array.
315-
- ``aux`` (default=None): The auxiliary information string for the annotation. List or numpy array.
336+
- ``extension`` (required): The string annotation file extension.
337+
- ``sample`` (required): The annotation location in samples relative to the beginning of the record. Numpy array.
338+
- ``symbol (default=None): The symbols used to display the annotation labels. List or numpy array. If this field
339+
is present, 'label_store' must not be present.
340+
- ``subtype`` (default=None): The marked class/category of each annotation. Numpy array.
341+
- ``chan (default=None): The signal channel associated with each annotation. Numpy array.
342+
- ``num ``(default=None): The labelled annotation number of each annotation. Numpy array.
343+
- ``aux_note`` (default=None): The auxiliary information strings. List or numpy array.
344+
- ``label_store`` (default=None): The integer values used to store the annotation labels. Numpy array.
345+
If this field is present, 'symbol' must not be present.
316346
- ``fs`` (default=None): The numerical sampling frequency of the record to be written to the file.
317-
318-
\*\ **NOTE**: Each annotation stored in a WFDB annotation file contains an annsamp and an anntype field. All other fields may or may not be present. Therefore in order to save space, when writing additional features such as 'aux' that are not present for every annotation, it is recommended to make the field a list, with empty indices set to None so that they are not written to the file.
347+
- ``custom_labels`` (default=None): The map of custom defined annotation labels used for this annotation, in
348+
addition to the standard WFDB annotation labels. The custom labels are defined by two or three fields:
349+
- The integer values used to store custom annotation labels in the file (optional)
350+
- Their short display symbols
351+
- Their long descriptions.
352+
This input argument may come in four formats:
353+
1. A pandas.DataFrame object with columns: ['label_store', 'symbol', 'description']
354+
2. A pandas.DataFrame object with columns: ['symbol', 'description']
355+
If this option is chosen, label_store values are automatically chosen.
356+
3. A list or tuple of tuple triplets, with triplet elements representing: (label_store, symbol, description).
357+
4. A list or tuple of tuple pairs, with pair elements representing: (symbol, description).
358+
If this option is chosen, label_store values are automatically chosen.
359+
If the 'label_store' field is given for this function, and 'custom_labels' is defined, 'custom_labels'
360+
must contain 'label_store' in its mapping. ie. it must come in format 1 or 3 above.
361+
362+
\*\ **NOTE**: Each annotation stored in a WFDB annotation file contains a sample and a label field. All other fields may or may not be present. Therefore in order to save space, when writing additional string features such as 'aux_note' that are not present for every annotation, it is recommended to make the field a list, with empty indices set to None so that they are not written to the file.
319363

320364

321365
Plotting Data
@@ -342,7 +386,7 @@ Input Arguments:
342386

343387
- ``record`` (required): A wfdb Record object. The p_signals attribute will be plotted.
344388
- ``title`` (default=None): A string containing the title of the graph.
345-
- ``annotation`` (default=None): A list of Annotation objects or numpy arrays. The locations of the Annotation objects' 'annsamp' attribute, or the locations of the numpy arrays' values, will be overlaid on the signals. The list index of the annotation item corresponds to the signal channel that each annotation set will be plotted on. For channels without annotations to plot, put None in the list. This argument may also be just an Annotation object or numpy array, which will be plotted over channel 0.
389+
- ``annotation`` (default=None): A list of Annotation objects or numpy arrays. The locations of the Annotation objects' 'sample' attribute, or the locations of the numpy arrays' values, will be overlaid on the signals. The list index of the annotation item corresponds to the signal channel that each annotation set will be plotted on. For channels without annotations to plot, put None in the list. This argument may also be just an Annotation object or numpy array, which will be plotted over channel 0.
346390
- ``timeunits`` (default='samples'): String specifying the x axis unit. Allowed options are: 'samples', 'seconds', 'minutes', and 'hours'.
347391
- ``sigstyle`` (default=''): String, or list of strings, specifying the styling of the matplotlib plot for the signals. If 'sigstyle' is a string, each channel will have the same style. If it is a list, each channel's style will correspond to the list element. ie. sigtype=['r','b','k'].
348392
- ``annstyle`` (default='r*'): String, or list of strings, specifying the styling of the matplotlib plot for the annotations. If 'annstyle' is a string, each channel will have the same style. If it is a list, each channel's style will correspond to the list element.
@@ -373,9 +417,9 @@ Example Usage:
373417

374418
Input Arguments:
375419

376-
- ``annotation`` (required): An Annotation object. The annsamp attribute locations will be overlaid on the signal.
420+
- ``annotation`` (required): An Annotation object. The sample attribute locations will be overlaid on the signal.
377421
- ``title`` (default=None): A string containing the title of the graph.
378-
- ``annotation`` (default=None): An Annotation object. The annsamp attribute locations will be overlaid on the signal.
422+
- ``annotation`` (default=None): An Annotation object. The sample attribute locations will be overlaid on the signal.
379423
- ``timeunits`` (default='samples'): String specifying the x axis unit. Allowed options are: 'samples', 'seconds', 'minutes', and 'hours'.
380424
- ``returnfig`` (default=False): Specifies whether the figure is to be returned as an output argument
381425

0 commit comments

Comments
 (0)