LabelVis
Welcome to LabelVis!
LabelVis is a piece of MATLAB software developed as a remora for Triton. It was created to facilitate easy visualization of labelled data from a variety of sources and allows the user to perform any of three main actions: creating labels that are compatible with visualization in Triton (tLabs), loading/visualizing tLab labels overlaid on open plots (LTSA, spectrogram, timeseries), and editing existing labels/saving edited labels.
Learn how to download or clone the Triton repository with the LabelVis Remora in the quick setup section and how to add the Remora to Triton.
The extension .tLab stands for ‘Triton labels’ which are compatible with the Triton software. This portion of LabelVis allows the user to convert labels of various other types into .tLab files.
From the LabelVis remora drop down menu, choose ‘create tLabs from Text File’.
A window will open allowing the user to select the desired text file with detection times/labels. These must be stored in one file.
Once the text file has been chosen, a second window will open allowing the user to specify a save location.
Labels will be saved to that location using whatever nomenclature was employed in the original text file to name the labels within. The name of the newly saved file will have the same prefix as the original text file.
If .cTg files are being used to create output labels, a third window will open asking the user to select the raw file that corresponds to the .cTg file used. This is not necessary when using text files with the .txt extension.
From the drop down menu, choose ‘create tLabs from detEdit output’. This allows the user to create tLabs based on any detEdit-compatible file type (ID files, FD (false detection) files, TD (true detection) files, or a full TPWS file). If TPWS is chosen, an additional option to remove false detections from the TPWS file before creating labels becomes available. The full TPWS option will create a .tLab file of all detections stored in TPWS files with the specified file prefix.
For all files except ID, the name of the output labels is defined by the user by changing ‘label name’. For ID files, label name is overridden by whatever labels are stored in the ID file (numbers corresponding to the color that the data was brushed in detEdit). Duration of clicks is set to a value generally appropriate for dolphins and should be modified with caution. Click duration value is only used to calculate end times; detEdit files only store the start of each detection of interest while tLab file creation requires both a start and an end time. The time offset is set to a default of 2000 to account for the discrepancy between MATLAB date times and Triton date times, i.e., Triton date times begin with the year 2000.
Once ‘create tLab File’ is pressed, the status of the label creation will show in the MATLAB console.
Labels will be stored with the specified file prefix (input file prefix)/name (label name) in the specified output directory.
This is the main functionality of LabelVis and allows users to plot and consider their current labels against the LTSA as well as the raw data (spectrogram and timeseries plots), primarily to provide greater context for labels and permit fine-scale examination of labelled data.
When visualize labels is chosen from the dropdown menu, a window appears that allows up to eight labels to be loaded simultaneously. By pressing each ‘load labels’ button, the user will be able to select the file of labels they want to load.
Selected files will then appear as loaded labels with the check box next to each loaded label set to ‘visible’.
Once labels are loaded, check boxes next to each label toggle whether labels are being plotted on open Triton windows. If labels are checked as ‘on’ they should appear in open Triton plots (LTSA, timeseries, and spectrogram). On timeseries and spectrogram plots, the start times of each detection will be plotted. On the LTSA, plotting of labels depends on how close subsequent detections are to one another-- if detections are within 5 minutes, they will be grouped together and the start/end of the combined detection will be shown as two dots connected by a continuous line.
Pressing ‘Refresh’ on the LabelVis visualization window will refresh the current plots with the checked labels; the forward and backward buttons on the window will move to the previous/next LTSA or spectrogram/timeseries plot and continue to show checked labels. It is also possible to move through the LTSA/raw file using the main Triton navigation buttons; labels will remain visible when navigating this way.
The ‘prev’ and ‘next’ buttons in the visualization window allow the user to move to the previous or next detection in the LTSA or raw file. It should be noted that these buttons will take the user to previous or next detections only of labels that are currently displayed.
This functionality allows the user to edit open labels to any other loaded type, or to ‘false’. Edited labels will remain in the same y-location as labels of their previous type, but color will be updated to match the color of the new type. Regardless of the plot in which labels are edited, edited labels will display as the color of their new type in open Triton plots. All edited labels, regardless of which plot they were edited on, are stored in one structure within MATLAB (and, if saved, in one file).
To edit labels on the LTSA plot, the user presses the ‘L' key on their keyboard. This will initialize use of the MATLAB function ginput(). The user must then select four points around the points they wish to edit (i.e., top left, top right, bottom left, bottom right) and press enter. A window will appear that allows the user to edit the labels within the selected points to whatever options are checked in the ‘edit open labels’ box.
Clicking ‘refresh’ in the main LabelVis visualization window will then display edited labels.
Choosing ‘save changed label files’ in the LabelVis editing window will allow the user to define an output location for changed labels.
Any labels that have been changed within this session will be saved in a .mat file with both old label and new label information and a file name in the format ‘label prefix_old label_modID’.
If changed labels are not saved in this way, they will continue to be visible within this session of Triton but will NOT remain changed if Triton is closed and labels are re-loaded.
Editing labels on the spectrogram/timeseries plots works in the same way as editing on the LTSA plot, but in this case the user must use the key command ‘c’ in order to initialize ginput(). The rest of the process is the same. Editing labels in this way is advantageous in that it allows for edits at finer scales (i.e. <1 minute).