wonambi.detect.agreement module

Module for agreement and consensus analysis between raters

class wonambi.detect.agreement.MatchedEvents(tp, fp, fn, detection, standard, threshold)

Bases: object

Class for storing matched events and producing statistics.

Parameters:

• tp (ndarray) – true positives as boolean array of shape len(detection) x len(standard)

• fp (ndarray) – indices of false positives in detection

• fn (ndarray) – indices of false negatives in standard

• detection (list of dict) – list of detected events tested against the standard, with ‘start’, ‘end’ and ‘chan’

• standard (list of dict) – list of ground-truth events, with ‘start’, ‘end’ and ‘chan’

• threshold (float) – minimum intersection-union score for events to be considered overlapping

all_to_annot(annot, names=['TPd', 'TPs', 'FP', 'FN'])

Convenience function to write all events to XML by category, showing overlapping TP detection and TP standard.

property f1score

property precision

property recall

to_annot(annot, category, name, s_freq=512)

Write matched events to Wonambi XML file for visualization.

Parameters:

• annot (instance of Annotations) – Annotations file

• category (str) – ‘tp_cons’, ‘tp_det’, ‘tp_std’, ‘fp’ or ‘fn’

• name (str) – name for the event type

• s_freq (int) – sampling frequency, in Hz, only required for ‘tp_cons’ category

wonambi.detect.agreement.consensus(events, threshold, s_freq, min_duration=None, weights=None)

Take two or more event lists and output a merged list based on consensus.

Parameters:

• events (tuple of lists of dict) – two or more lists of events from different raters, with ‘start’, ‘end’ and ‘chan’

• threshold (float) – value between 0 and 1 to threshold consensus. Consensus is computed on a per-sample basis. For a given rater, if an event is present at a sample, that rater-sample is assigned the value 1; otherwise it is assigned 0. The arithmetic mean is taken per sample across all raters, and if this mean exceeds ‘threshold’, the sample is counted as belonging to a merged event.

• s_freq (int) – sampling frequency, in Hz

• min_duration (float, optional) – minimum duration for merged events, in s.

• weights (list of float) – a vector of relative weights of each event type

Returns:

instance of wonambi.Graphoelement – events merged by consensus

wonambi.detect.agreement.consensus_exact(events, threshold, s_freq, window=None, min_duration=None, weights=None)

Take two or more event lists and output a merged list based on consensus, where agreement is exactly equal to a threshold. This is useful when combining >2 event types, and creating a consensus event type based on some combination of these events.

Parameters:

• events (tuple of lists of dict) – two or more lists of events from different raters, with ‘start’, ‘end’ and ‘chan’

• threshold (float) – value between 0 and 1 to threshold consensus. Consensus is computed on a per-sample basis. For a given rater, if an event is present at a sample, that rater-sample is assigned the value 1; otherwise it is assigned 0. The arithmetic sum is taken per sample across all raters, and if this exactly equals ‘threshold’, the sample is counted as belonging to a merged event.

• s_freq (int) – sampling frequency, in Hz

• min_duration (float, optional) – minimum duration for merged events, in s.

• weights (a dict containing event names (str) and their corresponding) – weighting (int) e.g. {‘low’ : 1,’med’ : 2,’high’ : 3}

Returns:

instance of wonambi.Graphoelement – events merged by consensus and named by confidence rating

Notes

This function is a modification of agreement.consensus contributed by Nathan Cross.

wonambi.detect.agreement.match_events(detection, standard, threshold)

Find best matches between detected and standard events, by a thresholded intersection-union rule.

Parameters:

• detection (list of dict) – list of detected events to be tested against the standard, with ‘start’, ‘end’ and ‘chan’

• standard (list of dict) – list of ground-truth events, with ‘start’, ‘end’ and ‘chan’

• threshold (float) – minimum intersection-union score to match a pair, between 0 and 1

Returns:

instance of MatchedEvents – indices of true positives, false positives and false negatives, with statistics (recall, precision, F1)