The DetEdit package provides a set of tools designed to parse, manipulate, and visualize acoustic detections in a workflow format using a user-interface developed in MATLAB (Mathworks, Natick, MA). The package, which depends on the core detEdit function, implements a hierarchical pipeline that incorporates data preprocessing, visualization, and manipulation tools (Fig 1). The main functions and files found in the repository with a brief summary of their usage is described at https://github.com/MarineBioAcousticsRC/DetEdit/wiki/How-It-Works#Table. The processing pipeline begins by using DetEdit to navigate through successive encounters, with modifications made to annotation matrices based on user decisions. This process is repeated as needed and also supports manual assessment of false positive rates.

A set of pre-processing tools are provided to produce the input required to use detEdit, the central user-interface tool. A generic impulse detector (Edetect) is provided to detect signals and produce matrices of detection parameters for input into DetEdit. Others (mkLtsa, mkLTSAsessions), compute spectral averages. The primary tool, detEdit, allows users to visualize the data with specific acoustic features, interactively explore and manually annotate data. Other functions, including modDet and summaryParams are post-processing tools, manipulating detections based on user annotations and producing plot-based data summaries.

The process of editing detections involves following several steps to create the parameters needed for the interface (Fig 1):

Step 1: Create LTSA files. The DetEdit package relies on mkLtsa to read audio files (wav format) and compress these data into long-term spectral averages (LTSA), which are power spectra calculated at regular intervals for the entire audio file [11]. LTSA are produced for the audio files by specifying the time average and frequency-bin size. They facilitate exploration and provide an easily visualized overview for long-term acoustic data.

Step 2: Create TPWS files. The input to the DetEdit GUI is a MATLAB binary file labeled as “TPWS” (Time, Peak-to-peak received levels, Waveform and Spectra parameters) that contains matrices of the acoustic detection parameters. These matrices can be created manually by the user or with make_TPWS which builds the following four primary variables to visualize detections in the interface:

If no detections are given, the package provides Edetect to assist in detecting acoustic events in audio files. This generic detector applies a configurable band pass filter and returns events that meet or exceed a minimum received level threshold and satisfy other configurable acoustic criteria.

Step 3: Create LTSA Sessions files. Detections are grouped in user-defined time bouts, defined as periods of stereotyped signals separated from prior and subsequent detections by a minimum specified time gap. mkLTSAsessions takes an LTSA and produces the following two variables needed to represent subsets of the LTSA per bout:

After manually annotating all detections, decisions stored in different annotation file types are used to modify the detection parameters stored in TPWS files. modDet excludes all false detections and ID detections (if specified by the user) from the TPWS files and displays exploratory plots as histograms of RL_pp, peak frequency and time interval between detections for each file. The process of using detEdit and modDet can be repeated iteratively until all detections are labeled, or a sufficiently low percentage of false detections is obtained (Fig 1). For every iteration, new detection and annotation files are generated and stored together in a common directory to keep track of all changes.

When specified using a simple keyboard shortcut commands, detEdit allows rapid estimation of a detector’s false positive rate across a systematic random sample of detections (Fig 5). The estimation procedure can be done at the signal-level where selected individual signals are sequentially evaluated as true or false within a bout. Alternatively, the procedure can be conducted at the level of a time-bin. This process consists of deciding if at least one signal within the defined interval is a true detection, whereby the entire bin is considered “true”. Signals or intervals evaluated for false positive rate estimation are selected systematically (every Nth detection) across a file. A matrix with the false positive rate per bout is built and stored in true detection files (TD.mat).

Finally, a data summary is given with histogram plots of RL_pp, time interval between detections, and a time series of weekly presence of the true detections at the signal-level and the time-bin level (S1 Fig).

The acoustic features displayed in the panels of the interface are helpful parameters for distinguishing signals from multiple odontocete species. Odontocetes produce highly-directional echolocation clicks with species-specific characteristic spectral shape and duration. These characteristics can be distinguished from the panels that show averaged normalized spectral density and waveforms of all signals within bouts, and can be compared with individual selected detections.

Odontocetes often echolocate at a characteristic rate [16]. The time interval between detections (Fig 2C), also known as inter-click-interval (ICI), is most variable when multiple animals are recorded simultaneously and the received impulse trains become interleaved. When only a single animal is pointing at the sensor and echolocating, a consistent echolocation click rate is likely to be received. Since echolocation signals are directional, there may be variability in ICI even in the single animal case due to changes in behavior and the detectability associated with animal orientation. The ICI time series, together with RL_pp of the detections throughout the encounter, and the concurrent spectral characteristics displayed in the LTSA panel allow context-supported interpretation of the data and differentiation of signal types.

The RL_pp versus transformed RL_rms display is a unique feature of DetEdit that allows users to distinguish between signals with the similar maximum amplitude, but different pulse characteristics in the time domain. Signals of short duration appear on the right side of the plot and signals of long duration appear on the left side of the plot. The same transformed RL_rms is shown with respect to peak frequency into another display. These panels help distinguish between odontocete species’ clicks, as well as some human signals (e.g. echosounders, ship noise).

A routine for verifying candidate sperm whale echolocation clicks was developed to distinguish signals with a multi-step approach (S1 Text). This case study illustrates the versatility of DetEdit for different labeling purposes and manual labeling of false detections. A total of 202 TB of data (containing 34 million sperm whale clicks) was verified and corresponding false positive rates were calculated.

An example of editing acoustic data with sperm whale clicks within a mixed species time period is shown in Fig 2. The window panels of both RL_pp and peak frequencies with respect to transformed RL_rms were particularly useful in distinguishing sperm whale detections from other odontocetes. In this case, the removal of dolphin clicks was possible by selecting clicks with lower RMS. To accelerate the removal of low RMS detections, a RL_pp threshold was implemented to automatically label all detections below the threshold as false positives (Fig 2F). Also, noisy periods of time corresponding to impulsive shipping noise were visually identified and flagged with the brushing tool for exclusion.

This example shows how DetEdit supports the identification of distinct delphinid click types within large datasets (https://github.com/MarineBioAcousticsRC/DetEdit/wiki/Getting-Started). Unsupervised clustering tools were used to automatically classify signals into categories and to assist human analysts with processing multi-species acoustic encounters [12]. A total of 171 TB of data (with 115 million dolphin clicks) was verified, and corresponding false positive rates for each species were calculated. Clusters were evaluated using the interface, with different color codes distinguishing the multiple detection types identified (Fig 4). Multiple encounters of overlapping species were visually distinguishable and flagging clicks in different colors made identification of different species possible. The selection tool supported this process by allowing manual selection of individual or multiple detections to compare with the different color-coded detections.