+ this is a page of help text
+ + + \ No newline at end of file diff --git a/target/classes/books/BinaryFileStructure.html b/target/classes/books/BinaryFileStructure.html new file mode 100644 index 00000000..e77abb42 --- /dev/null +++ b/target/classes/books/BinaryFileStructure.html @@ -0,0 +1,1679 @@ + + + + + +Binary file structure for PAMGUARD detector +output.
+ +Douglas Gillespie, 2010
+ +The primary storage site for PAMGUARD +output data is a relational database (currently either MS Access or MySQL +although other types may be added in the future).
+ +Pre 2010, the only other storage +solutions comes from the click detector which writes binary files in the +RainbowClick (*.clk) file format since click data is often additionally +processed using RainbowClick offline. Over the next year or so, this offline +nalysis functionality will be added to PAMGUARD, making RainbowClick redundant. +Long term support for the .clk format is therefore not required.
+ +Current annoyances are
+ +1. +The database is not suitable for storage of +variable record length data (e.g. a snip of click waveform as used by +RainbowClick or the time/amplitude/frequency contour of a whistle)
+ +2. +The RainbowClick file binary format is awful +works OK from C, but is a nightmare in Java and is not practical to evolve.
+ +3. +The click files need to be written with a random +access file writer which is more complicated than a simple data stream output +(most Java output types)
+ +4. +Databases often have limited size
+ +Therefore:
+ +1. +We need a replacement for the .clk file format.
+ +2. +We need something similar for other PAMGUARD +output tasks.
+ +Therefore we +need some new binary format storage solution which can be used by many +different PAMGUARD modules for storing detector (and other) data.
+ +Java serialisation: Fast and easy to +write out Java objects but cannot open these files with anything but Java (e.g. +could not write a Matlab function to access the data).
+ +Pure binary storage (like .clk files) : +Need to translate data from each stored object from its Java form into a byte +array prior to storage and convert back the other way afterwards. However, data +would be readable in Matlab or any other program so long as you knew the format +of each object.
+ +A common file format for All PAMGUARD +module output, pgdf for PAMGUARD Data File.
+ +Output (from PAMGUARD) will assume one +way output and input streams rather than random access, although other programs +could of course open the files in any way they wish. This means that the files +will know their start time, which will be encoded in both the file name and the +header, but the end time will only be accessible as the last object in the file + which may take time to read.
+ +Smaller index files (.pgdx) will be +written to accompany each pgdf file which contain just the start header and end +footer of each file, so that PAMGUARD can rapidly query a file repository to +see whats in it.
+ +Files will have a common structure, which +PAMGUARD will always be able to understand, although specific objects within +the file will require information specific to a particular module.
+ +For a specific PAMGUARD configuration, +all output files will be stored in the same master directory, although its possible +that this may contain multiple sub folders, e.g. one sub folder per day.
+ +There will be a 1:1 correspondence +between PAMGUARD data blocks and binary data streams (i.e. all objects in a +given file should be of the same type).
+ +Output will be a series of binary +objects. Every object will start with an int32 (long) integer giving the size +of that object in bytes. This number includes itself in the size calculation. +So it will always be possible to skip through the file using the following +pseudocode:
+ +While +not eof
+ +objectSize += ReadLong()
+ +SkipForwardBytes(objectSize-4)
+ +Next
+ +The objects for the header and footer +will be rigidly defined. However the data objects can be in any format (it +being the responsibility of individual module developers to ensure backwards +compatibility should anything change).
+ +Following the standard PAMGUARD header, +is an optional control structure or module header. For example, a detector may +which to write out its detection parameters at this point, probably as a Java +serialised object, although anything is allowed, it being the stream that +writes the datas responsibility to read it back in in a sensible way.
+ +All numbers +(short, int, long, float, double) are written using Big Endians, i.e. big byte +first. This is the standard for the platform independent Java DataOutputStream +class and the C default for Linux and Mac. Matlab can read these files by +setting the file format, e.g. f = fopen(fileName, 'r', 'ieee-be.l64');
+ +Windows C +programmes processing the files would need to re-order bytes.
+ ++ +
+ +
|
+ + |
+
+ + |
+
+ Format + |
+
+ Notes + |
+
|
+ File Header + |
+
+ Length of file + header in bytes + |
+
+ Int32 + |
+
+ Every object + will start with this number. + |
+
|
+ Object + Identifier + |
+
+ Int32 + |
+
+ -1 + |
+ |
|
+ Header / + general file Format + |
+
+ Int32 + |
+
+ Hope this + changes very very rarely + |
+ |
|
+ PAMGUARDDATA + |
+
+ Char(12) + |
+
+ Just so its + obvious that this really is a P file + |
+ |
|
+ PAMGUARD + Version + |
+
+ CharUTF* + |
+
+ e.g. 1.8.00 + |
+ |
|
+ PAMGUARD + Branch + |
+
+ CharUTF* + |
+
+ e.g. Core, + Beta, etc. + |
+ |
|
+ Data Date + |
+
+ Long (int64) + |
+
+ Data time at + start of file in Java millis + |
+ |
|
+ Analysis Date + |
+
+ Long (int64) + |
+
+ Time at which + analysis started (same as data time for real time) + |
+ |
|
+ File Start + Sample + |
+
+ Long (int64) + |
+
+ Current sample + number for this data stream + |
+ |
|
+ Module type + |
+
+ CharUTF* + |
+
+ Module type + |
+ |
|
+ Module Name + |
+
+ CharUTF* + |
+
+ Module name + |
+ |
|
+ Stream Name + |
+
+ CharUTF* + |
+
+ Data stream + name + |
+ |
|
+ Extra info + length + |
+
+ Int32 + |
+
+ Length of + additional data + |
+ |
|
+ Extra info + |
+
+ byte[] + |
+
+ Additional + data + |
+ |
|
+ Module specific Control Structure + |
+
+ Length in File + |
+
+ Int32 + |
+
+ Length of this + object = 16 + object binary length + |
+
|
+ Object + Identifier + |
+
+ Int32 + |
+
+ -3 + |
+ |
|
+ Module version + Info + |
+
+ Int32 + |
+
+ Version info + specific to the pamguard module writing data to this stream. + |
+ |
|
+ Object binary + Length + |
+
+ Int32 + |
+
+ = Length in + File 16 (a bit of redundancy) ! Can be zero if there is no additional data + |
+ |
|
+ Object Data + |
+
+ Byte[] + |
+
+ Length = + Object binary Length + |
+ |
|
+ Object 1 + |
+
+ Length in File + |
+
+ Int32 + |
+
+ Length of this + object + |
+
|
+ Object + Identifier + |
+
+ Int32 + |
+
+ class + identifier which must be unique to this data stream, not across PAMGUARD + |
+ |
|
+ Time milliseconds + |
+
+ Int32 + |
+
+ Timestamp in + milliseconds relative to start of file Data Date + |
+ |
|
+ Object binary + Length + |
+
+ Int32 + |
+
+ = Length in + File 12 (a bit of redundancy) ! + |
+ |
|
+ Object Data + |
+
+ Byte[] + |
+
+ Length = + Object binary Length + |
+ |
|
+ Object 2 + |
+
+ Length in File + |
+
+ Int32 + |
+
+ Length of this + object + |
+
|
+ Object + Identifier + |
+
+ Int32 + |
+
+ class + identifier which must be unique to this data stream, not across PAMGUARD + |
+ |
|
+ Time + milliseconds + |
+
+ Int32 + |
+
+ Timestamp in + milliseconds relative to start of file Data Date + |
+ |
|
+ Object binary + Length + |
+
+ Int32 + |
+
+ = Length in + File 12 (a bit of redundancy) ! + |
+ |
|
+ Object Data + |
+
+ Byte[] + |
+
+ Length = + Object binary Length. Need not be same as Object 1. + |
+ |
|
+ Etc + |
+
+ + |
+
+ + |
+
+ + |
+
|
+ Module footer + |
+
+ Length in File + |
+
+ Int32 + |
+
+ Length of this + object = 16 + object binary length + |
+
|
+ Object + Identifier + |
+
+ Int32 + |
+
+ -3 + |
+ |
|
+ Object binary + Length + |
+
+ Int32 + |
+
+ = Length in + File 16 (a bit of redundancy) ! Can be zero if there is no additional data + |
+ |
|
+ Object Data + |
+
+ Byte[] + |
+
+ Length = + Object binary Length + |
+ |
|
+ File Footer + |
+
+ Length of + footer in bytes + |
+
+ Int32 + |
+
+ + |
+
|
+ Object + identifier + |
+
+ Int32 + |
+
+ -2 + |
+ |
|
+ Total number + of objects in file + |
+
+ Int32 + |
+
+ Not counting + header, control struct and footer (i.e. can be = 0) + |
+ |
|
+ Data Date + |
+
+ Long (int64) + |
+
+ Data time at end + of file in Java millis + |
+ |
|
+ Analysis Date + |
+
+ Long (int64) + |
+
+ Time at which + analysis ended (same as data time for real time) + |
+ |
|
+ File End + Sample + |
+
+ Long (int64) + |
+
+ Sample number + at end of file + |
+ |
|
+ File length + |
+
+ Long (int64) + |
+
+ Total length + of the file (will be more use when this is repeated in an index file) + |
+ |
|
+ File End + Reason + |
+
+ Int32 + |
+
+ Reason file + ended + |
+ |
|
+ EOF + |
+
+ + |
+
+ + |
+
+ + |
+
*Strings are +often written with the DataOutputStream.writeUTF() function. For standard ASCII +characters, this will simply be a two bytes (written as a short) giving the +length of the string followed by one byte per character. Unicode characters are +also supported in this format for details see the JAVA Help and Wikipedia.
+ +Smaller indexing files (.pgdx) will +contain the header, control structures and footer from the pgdf files, but none +of the objects.
+ +Object identifiers used by the file +management system are negative
+ +-1 = Header;
+ +-2 = Footer;
+ +-3 = Module header
+ +-4 = Module footer
+ +Individual modules can use any positive +number and these numbers need only be unique within the module reading and +writing the data.
+ +Example data formats for specific modules
+ +Click Detector Version 0
+ +|
+ + |
+
+ Time millis + |
+
+ Int64 + |
+
+ + |
+
|
+ + |
+
+ Start sample + |
+
+ Int64 + |
+
+ + |
+
|
+ + |
+
+ Channel map + |
+
+ Int32 + |
+
+ + |
+
|
+ + |
+
+ Triggered channels + |
+
+ Int32 + |
+
+ + |
+
|
+ + |
+
+ Num delay measurements + |
+
+ Int16 + |
+
+ + |
+
|
+ + |
+
+ Delay measurements + |
+
+ Float[] + |
+
+ Usually nChan*(nChan-1)/2 + |
+
|
+ + |
+
+ Num angle measurements + |
+
+ Int16 + |
+
+ (0, 1 or 2) + |
+
|
+ + |
+
+ Angle measurements + |
+
+ Float[] + |
+
+ + |
+
|
+ + |
+
+ Duration (samples) + |
+
+ Int16 + |
+
+ + |
+
|
+ + |
+
+ WaveData + |
+
+ Int16[][] + |
+
+ + |
+
+ +
Click Detector Version 1
+ +|
+ + |
+
+ Time millis + |
+
+ Int64 + |
+
+ + |
+
|
+ + |
+
+ Start sample + |
+
+ Int64 + |
+
+ + |
+
|
+ + |
+
+ Channel map + |
+
+ Int32 + |
+
+ + |
+
|
+ + |
+
+ Triggered channels + |
+
+ Int32 + |
+
+ + |
+
|
+ + |
+
+ Click Type + |
+
+ Int16 + |
+
+ + |
+
|
+ + |
+
+ Num delay measurements + |
+
+ Int16 + |
+
+ Usually nChan*(nChan-1)/2 + |
+
|
+ + |
+
+ Delay measurements + |
+
+ Float[] + |
+
+ + |
+
|
+ + |
+
+ Num angle measurements + |
+
+ Int16 + |
+
+ (0, 1 or 2) + |
+
|
+ + |
+
+ Angle measurements + |
+
+ Float[] + |
+
+ + |
+
|
+ + |
+
+ Duration (samples) + |
+
+ Int16 + |
+
+ + |
+
|
+ + |
+
+ Wave Max Amplitude + |
+
+ float + |
+
+ Max amplitude of wave data. + |
+
|
+ + |
+
+ WaveData + |
+
+ Int8[][] + |
+
+ Wavedata scaled by 127/max amplitude so + if uses full dynamic range of 8 bit data + |
+
+ +
+ +
Binary Storage Manager (BSM) is a plugin +module in the utilities group (next to database, since the two things perform +similar function). Only one BSM module will be allowed
+ +BSM will control:
+ +1. +The folder data are stored in.
+ +2. +Opening new files at program start and closing +them at program end. Will set file names based on the data stream name and the +time.
+ +3. +Reopening files on the hour (or at some other +set time interval, e.g. when analysing wav file data offline, it may make a new +file every time a file starts)
+ +4. +Reloading data for the PAMGUARD viewer.
+ +5. +Rewriting data files changed during offline +analysis
+ ++ +
For data streams modify PamDataBlock, +and also make possibility of other objects sending data to BSM
+ +Need to:
+ +1. +register with BSM
+ +2. +hand BSM settings data, which will be requested +each time a new file is created (see format above).
+ +3. +send BSM references to all new data units
+ +4. +know how to recreate data units from data that +have been read back in with PAMGUARD viewer.
+ +PAMGUARD Data Units
+ +1. +Need functions to return their binary data +object (which may just be a serialised version of themselves
+ +2. +Need to be able to identify themselves in +agreement with a central registry
+ ++ +
PAMGUARD Settings
+ +PAMGUARD Settings are written to the +binary store whenever PAMGUARD starts from the Start menu or from the Network +controller. They are not written when PAMGUARD restarts due to a buffer +overflow in acquisition. Settings are written to .psfx files. These encapsulate +the current psf format used for more general settings, but individual +serialised Java objects are wrapped up in a similar way to other binary data so +that other programmes (e.g. Matlab) can at least read a list of modules.
+ +
+To make a PAMGUARD plug-in available to PAMGUARD users it is necessary to edit
+the java file pammodel/PamModel.java.
+
+First you register the module with PAMGUARD using
+
PamModuleInfo myModule = PamModuleInfo.registerControlledUnit(String className, String description);+where className is the class name of the class PamControlledUnit and description is the descriptive name +of the module. +
+For example +
PamModuleInfo myModule = PamModuleInfo.registerControlledUnit("GPS.GPSControl", "GPS Processing");+adds the GPS module. +
+The module will now be listed in the PAMGUARD File/Add Modules menu from where the user can create instances of the module. +
The PAMGUARD settings manager will be aware of the new module and will automatically create the module +the next time PAMGUARD is run.
+myModule.setModulesMenuGroup(mapsGroup);+ +
+You can set module dependencies using +
+PamModuleInfo.addDependency(PamDependency dependancy) ++for example +
+myModule.addDependency(new PamDependency(NMEADataUnit.class, "NMEA.NMEAControl")); ++tells PAMGUARD that myModule is dependent on some source of NMEADataUnit and that a possible +source of this type of data is the NMEA.NMEAControl module. +
+Note that some types of data may be produced by many different modules, so here you should specify the +most common source of the data your module will use. +
+
+PamModuleInfo.setMinNumber(int minNumber) +and +PamModuleInfo.setMaxNumber(int maxNumber) ++to set the minimum and maximum numbers of a given module type. +
+If these are not set (which is generally the case), then the minimum number defaults to zero and there is no +maximum number. +
+If you set a minimum number, then PAMGUARD will automatically create that number of modules at start up. +
+If you set a maximum number then PAMGUARD will prevent you from creating more than that number of modules. + + + +
+ +
Previous: How to make PAMGUARD plug-ins
+ + + diff --git a/target/classes/books/HowToMakeOverlays.html b/target/classes/books/HowToMakeOverlays.html new file mode 100644 index 00000000..c18d96cc --- /dev/null +++ b/target/classes/books/HowToMakeOverlays.html @@ -0,0 +1,133 @@ + + + ++Graphic overlays all make use of sub classes of the +Pamview.GeneralProjector which +provides functions to convert units such as Latitude, Longitude, Frequency, Time, etc. +into screen coordinates. +
+The programmer wishing to overlay information must implement the +Pamview.PanelOverlayDraw +interface and attach that implementation to a +PamDataBlock +using the command +setOverlayDraw. +
+Each display that implements graphic overlays will check which +PamDataBlocks are +capable of drawing with their +Projector. This is +done using the +canDraw +command in +PanelOverlayDraw. +
+Generally, this decision is made based on the axis types for the +Projector. +
+For example, the following code is taken from the whistle detector which +is capable of overlaying graphics on spectrogram displays having time and +frequency as their axis. +
+ public boolean canDraw(GeneralProjector projector) {
+ if (projector.getParmeterType(0) == ParameterType.TIME
+ && projector.getParmeterType(1) == ParameterType.FREQUENCY)
+ return true;
+ return false;
+ }
+
++Each display should also have implemented a menu or dialog box which will allow +the user to set which graphics to overlay on a particular display. +
+The contents of
+this menu or dialog box will have been populated by examining all
+PamDataBlocks
+and including all those that returned true to
+canDraw
+for the given
+projector.
+
+The display will then subscribe to
+PamDataBlocks
+that it wishes to use as graphic overlays.
+
+
+
+It is possible for data from a single data block to be drawn on several different types +of display, for example maps and spectrograms. +
If data are to be drawn on multiple +display types, then the +canDraw +function should return true for all of those display types. +
+At the top of the +drawDataUnit +function, check the types of coordinates being used by the projector to determine the +display type and then call appropriate drawing routines depending on the axis. +
+For example, the following code can be found in +WhistleGraphics which +allows drawing on both the map and spectrogram displays. +
+
public Rectangle drawDataUnit(Graphics g, PamDataUnit pamDataUnit,
+ GeneralProjector projector) {
+ if (projector.getParmeterType(0) == ParameterType.LONGITUDE
+ && projector.getParmeterType(1) == ParameterType.LATITUDE) {
+ return drawWhistleOnMap(g, pamDataUnit, projector);
+ } else if (projector.getParmeterType(0) == ParameterType.TIME
+ && projector.getParmeterType(1) == ParameterType.FREQUENCY) {
+ return drawWhistleShape(g, pamDataUnit, projector);
+ }
+ return null;
+ }
+
+ Rectangle drawWhistleOnMap(Graphics g, PamDataUnit pamDataUnit,
+ GeneralProjector projector) {
+ ...
+ etc.
+
+
+
+
diff --git a/target/classes/books/HowToMakePluginDisplays.html b/target/classes/books/HowToMakePluginDisplays.html
new file mode 100644
index 00000000..cbbb3e67
--- /dev/null
+++ b/target/classes/books/HowToMakePluginDisplays.html
@@ -0,0 +1,30 @@
+
+
+
++plug in displays take their time axis directly from the spectrogram display +so that whatever is displayed is time aligned with the spectrogram data. +
+To create plug in displays, the developer must create two separate classes +
+All PAMGUARD plug-ins are subclasses of PamControlledUnit
+
+To make a plug in, first create a subclass of PamControlledUnit,
+adding to the subclass the various components described below. Then add your new plug-in the the PAMGUARD
+data model. See How to add plug-ins to learn how to do this.
+
+Available components of a PAMGUARD plug-in are +
+Although the default constructor for PamControlledUnit is +
+public PamControlledUnit(String unitType, String unitName) ++you must provide a constructor in your sub class that takes just the unitName, e.g. +
+public class MyDetectorController extends PamControlledUnit {
+ public MyDetectorController(String unitName) {
+ super("My detector", unitName);
+ etc...
+
+Pamguard will search for and use this single parameter constructor when creating modules and adding them to the Pamguard data model.
+
++Pamguard Processes are subclasses of PamProcess. +A PamProcess will subscribe to one or more PamDataBlock(s). +A PamProcess will generally also create one or more new + PamDataBlock(s). + +When new data arrive from the PamDataBlock, the process will manipulate those data in some way and create information +that is added to the output data blocks. +
+Each Pamguard plug-in may have any number of processes, for example, most displays do not have a process at all. The whistle +detector, on the other hand, has separate processes for peak detection and whistle linking. +
+To add a process to a plug in, use the addPamProcess +function in PamControlledUnitUnit. +
+
+
+
+PAMGUARD Tab panels are added as separate tabs on the main PAMGUARD GUI display. +A tab panel may contain graphics or tables to display information of any type. +
+Each PAMGUARD plug-in may currently only have a single tab panel per plug in. +however, since the developer can put anything they like into that one tab panel, +it is of course possible to place a tab panel in that one tab panel and for the inner +tab panel to contain multiple tabs ! +
+To add a tab panel to a plug in, use the setTabPanel +function in PamControlledUnit. +
+
+
+
+Note that a new detection menu may be created multiple times as modules are added and removed from +the PAMGUARD system. Therefore the implementation of +createDetectionMenu +should contain only a minimum amount of code required to make the actual menu and should avoid +calling constructors for additional objects. +
+Detection menus will automatically be incorporated as sub-menus in PAMGUARD's main detection menu. +They will also be shown as separate menu items in the main menu bar when the tab panel (if one exists) for the +plug-in is selected. + +
+
+
+
+Note that a new display menu may be created multiple times as modules are added and removed from +the PAMGUARD system. Therefore the implementation of +createDisplayMenu +should contain only a minimum amount of code required to make the actual menu and should avoid +calling constructors for additional objects. +
+Display menus will automatically be incorporated as sub-menus in PAMGUARD's main display menu. +They will also be shown as separate menu items in the main menu bar when the tab panel (if one exists) for the +plug-in is selected. +
+
+
+
+Note that a new display menu may be created multiple times as modules are added and removed from +the PAMGUARD system. Therefore the implementation of +createFileMenu +should contain only a minimum amount of code required to make the actual menu and should avoid +calling constructors for additional objects. +
+File menus will automatically be incorporated as sub-menus in PAMGUARD's main file menu. +
+
+
+
+Side panels are generally used to display summary information +for the PamControlledUnit or to provide quick access controls. +
+To add a side panel to a plug in, use the setSidePanel +function in PamControlledUnit. +
+
+
+
+In general, the +PamDataBlock(s) +are created +at the same time as the PamProcess. +PamDataUnits +are then added to the +PamDataBlock(s) as and when they +become available. +
+For some processes, such as the FFT Engine, +PamDataUnits will be added to the output +PamDataBlock at regular intervals. +For other processes, such as the +Click Detector +new +PamDataUnits will be only be added if +and when detections are made. +
+
+
+
+Displays that currently support graphic overlays are (as of December 2006) +
+For details of how to make graphic overlays in PAMGUARD see +How to make graphic overlays +
+
+
+
+Scroll speed of plug-in panels is controlled by the spectrogram display so that +the plug-in panel data remain in line with the spectrogram data. +
+For details on how to make plug in display panels see +How to make plug in display panels + +
+
+
+
+
Next: Adding plug-ins to the PAMGUARD model
+ + + diff --git a/target/classes/books/images/plugintable.png b/target/classes/books/images/plugintable.png new file mode 100644 index 00000000..f6b00e46 Binary files /dev/null and b/target/classes/books/images/plugintable.png differ diff --git a/target/classes/books/pamHelpStylesheet.css b/target/classes/books/pamHelpStylesheet.css new file mode 100644 index 00000000..2e857bbd --- /dev/null +++ b/target/classes/books/pamHelpStylesheet.css @@ -0,0 +1,34 @@ +BODY { + BACKGROUND-COLOR: FFFFFF +} +H1 { + FONT-FAMILY: Arial; + FONT-SIZE: 21; + COLOR: #6698FE; + BACKGROUND-COLOR: #DCFEEC; + margin-bottom: 0 +} +H2 { + FONT-FAMILY: Arial; + FONT-SIZE: 17; + COLOR: #6698FE; + BACKGROUND-COLOR: #CBDAEB; + margin-top: 0; +} +H3 { + FONT-FAMILY: Arial; + FONT-SIZE: 15; +} + +H4 { + FONT-FAMILY: Arial; + FONT-SIZE: 14; +} + +p { + FONT-FAMILY: Arial; + FONT-SIZE: 14; + margin-top: 10; + margin-left: 0; + margin-bottom: 0 +} diff --git a/target/classes/doc/books/HowToAddPlugins.html b/target/classes/doc/books/HowToAddPlugins.html new file mode 100644 index 00000000..9a9dc220 --- /dev/null +++ b/target/classes/doc/books/HowToAddPlugins.html @@ -0,0 +1,77 @@ + + + +
+To make a Pamguard plug-in avialable to Pamguard users it is necessary to edit
+the java file pammodel/PamModel.java.
+
+First you register the module with Pamguard using
+
PamModuleInfo myModule = PamModuleInfo.registerControlledUnit(String className, String description);+where className is the class name of the class PamControlledUnit and description is the descriptive name +of the module. +
+For example +
PamModuleInfo myModule = PamModuleInfo.registerControlledUnit("GPS.GPSControl", "GPS Processing");+adds the GPS module. +
+The module will now be listed in the Pamguard File/Add Modules menu from where the user can create instances of the module. +
The Pamguard settings manager will be aware of the new module and will automatically create the module +the next time Pamguard is run.
+myModule.setModulesMenuGroup(mapsGroup);+ +
+You can set module dependencies using +
+PamModuleInfo.addDependency(PamDependency dependancy) ++for example +
+myModule.addDependency(new PamDependency(NMEADataUnit.class, "NMEA.NMEAControl")); ++tells Pamguard that myModule is dependent on soume source of NMEADataUnit and that a possible +source of this type of data is the NMEA.NMEAControl module. +
+Note that some types of data may be produced by many different modules, so here you should specify the +most common source of the data your module will use. +
+
+PamModuleInfo.setMinNumber(int minNumber) +and +PamModuleInfo.setMaxNumber(int maxNumber) ++to set the minimum and maximum numbers of a given module type. +
+If these are not set (which is generally the case), then the minimum number defaults to zero and there is no +maximum number. +
+If you set a minimum number, then Pamgaurd will automatically create that number of modules at start up. +
+If you set a maximum number then Pamgaurd will prevent you from creating more than that number of modules. + + + +
+ +
Previous: How to make Pamguard plugins
+ + + diff --git a/target/classes/doc/books/HowToMakeOverlays.html b/target/classes/doc/books/HowToMakeOverlays.html new file mode 100644 index 00000000..cf393c13 --- /dev/null +++ b/target/classes/doc/books/HowToMakeOverlays.html @@ -0,0 +1,133 @@ + + + ++Graphic overlays all make use of sub classes of the +Pamview.GeneralProjector which +provides functions to convert units such as Latitude, Longitude, Frequency, Time, etc. +into screen coordinates. +
+The programmer wishing to overlay information must implement the +Pamview.PanelOverlayDraw +interface and attach that implementation to a +PamDataBlock +using the command +setOverlayDraw. +
+Each display that implements graphic overlays will check which +PamDataBlocks are +capable of drawing with their +Projector. This is +done using the +canDraw +command in +PanelOverlayDraw. +
+Generally, this decision is made based on the axis types for the +Projector. +
+For example, the following code is taken from the whsitle detector which +is capable of overlaying graphics on spectrogram displays having time and +frequency as their axis. +
+ public boolean canDraw(GeneralProjector projector) {
+ if (projector.getParmeterType(0) == ParameterType.TIME
+ && projector.getParmeterType(1) == ParameterType.FREQUENCY)
+ return true;
+ return false;
+ }
+
++Each display should also have implemented a menu or dialog box which will allow +the user to set which graphics to overlay on a particular display. +
+The contents of
+this menu or dialog box will have been populated by examining all
+PamDataBlocks
+and including all those that returned true to
+canDraw
+for the given
+projector.
+
+The display will then subscribe to
+PamDataBlocks
+that it wishes to use as graphic overlays.
+
+
+
+It is possible for data from a single data block to be drawn on several different types +of display, for example maps and spectrograms. +
If data are to be drawn on multiple +display types, then the +canDraw +function should return true for all of those display types. +
+At the top of the +drawDataUnit +function, check the types of coordinates being used by the projector to determine the +dipslay type and then call appropriate drawing routines depending on the axis. +
+For example, the following code can be found in +WhistleGraphics which +alows drawing on both the map and spectrogram displays. +
+
public Rectangle drawDataUnit(Graphics g, PamDataUnit pamDataUnit,
+ GeneralProjector projector) {
+ if (projector.getParmeterType(0) == ParameterType.LONGITUDE
+ && projector.getParmeterType(1) == ParameterType.LATITUDE) {
+ return drawWhistleOnMap(g, pamDataUnit, projector);
+ } else if (projector.getParmeterType(0) == ParameterType.TIME
+ && projector.getParmeterType(1) == ParameterType.FREQUENCY) {
+ return drawWhistleShape(g, pamDataUnit, projector);
+ }
+ return null;
+ }
+
+ Rectangle drawWhistleOnMap(Graphics g, PamDataUnit pamDataUnit,
+ GeneralProjector projector) {
+ ...
+ etc.
+
+
+
+
diff --git a/target/classes/doc/books/HowToMakePluginDisplays.html b/target/classes/doc/books/HowToMakePluginDisplays.html
new file mode 100644
index 00000000..9e350775
--- /dev/null
+++ b/target/classes/doc/books/HowToMakePluginDisplays.html
@@ -0,0 +1,30 @@
+
+
+
++plug in diplays take their time axis directly fromt he spectrogram display +so that whatever is displayed is time aligned with the spectrogram data. +
+To create plug in displays, the developer must create two separate classes +
+All Pamguard plug-ins are subclasses of PamControlledUnit
+
+To make a plug in, first create a subclass of PamControlledUnit,
+adding to the subclass the various components described below. Then add your new plug-in the the Pamguard
+data model. See How to add plug-ins to learn how to do this.
+
+Available components of a Pamguard plug-in are +
+Although the default constructor for PamControlledUnit is +
+public PamControlledUnit(String unitType, String unitName) ++you must provide a constructor in your sub class that takes just the unitName, e.g. +
+public class MyDetectorController extends PamControlledUnit {
+ public MyDetectorController(String unitName) {
+ super("My detector", unitName);
+ etc...
+
+Pamguard will search for and use this single parameter constructor when creating modules and adding them to the Pamguard data model.
+
++Pamguard Processes are subclasses of PamProcess. +A PamProcess will subscribe to one or more PamDataBlock(s). +A PamProcess will generally also create one or more new + PamDataBlock(s). + +When new data arrive from the PamDataBlock, the process will manipulate those data in some way and create information +that is added to the output data blocks. +
+Each Pamguard plug-in may have any number of processes, for example, most displays do not have a process at all. The whistle +detector, on the other hand, has separate processes for peak detection and whistle linking. +
+To add a process to a plug in, use the addPamProcess +function in PamControlledUnitUnit. +
+
+
+
+Pamguard Tab panels are added as separate tabs on the main Pamguard GUI display. +A tab panel may contain graphics or tables to display information of any type. +
+Each Pamguard plug-in may currently only have a single tab panel per plug in. +however, since the developer can put anything they like into that one tab panel, +it is of course possible to place a tab panel in that one tab panel and for the innter +tab panel to contain multiple tabs ! +
+To add a tab panel to a plug in, use the setTabPanel +function in PamControlledUnit. +
+
+
+
+Note that a new detection menu may be created multiple times as modules are added and removed from +the Pamguard system. Therefore the implementation of +createDetectionMenu +should contain only a mimimum amount of code required to make the actual menu and should avoid +calling constructors for additional objects. +
+Detection menus will automatically be incorporated as sub-menus in Pamguards main detection menu. +They will also be shown as separate menu items in the main menu bar when the tab panel (if one exists) for the +plug-in is selected. + +
+
+
+
+Note that a new display menu may be created multiple times as modules are added and removed from +the Pamguard system. Therefore the implementation of +createDisplayMenu +should contain only a mimimum amount of code required to make the actual menu and should avoid +calling constructors for additional objects. +
+Display menus will automatically be incorporated as sub-menus in Pamguards main display menu. +They will also be shown as separate menu items in the main menu bar when the tab panel (if one exists) for the +plug-in is selected. +
+
+
+
+Note that a new display menu may be created multiple times as modules are added and removed from +the Pamguard system. Therefore the implementation of +createFileMenu +should contain only a mimimum amount of code required to make the actual menu and should avoid +calling constructors for additional objects. +
+File menus will automatically be incorporated as sub-menus in Pamguards main file menu. +
+
+
+
+Side panels are generally used to display summary information +for the PamControlledUnit or to provide quick access controls. +
+To add a side panel to a plug in, use the setSidePanel +function in PamControlledUnit. +
+
+
+
+In general, the +PamDataBlock(s) +are created +at the same time as the PamProcess. +PamDataUnits +are then added to the +PamDataBlock(s) as and when they +become available. +
+For some processes, such as the FFT Engine, +PamDataUnits will be added to the output +PamDataBlock at regular intervals. +For other processes, such as the +Click Detector +new +PamDataUnits will be only be added if +and when detections are made. +
+
+
+
+Displays that currently support graphic overlays are (as of December 2006) +
+For details of how to make graphic overlays in Pamguard see +How to make graphic overlays +
+
+
+
+Scroll speed of plug-in panels is contrlled by the spectrogram display so that +the plugin panel data remain in line with the specgtrgram data. +
+For details on how to make plug in display panels see +How to make plug in display panels + +
+
+
+
+
Next: Adding plug-ins to the Pamguard model
+ + + diff --git a/target/classes/doc/books/images/plugintable.png b/target/classes/doc/books/images/plugintable.png new file mode 100644 index 00000000..f6b00e46 Binary files /dev/null and b/target/classes/doc/books/images/plugintable.png differ diff --git a/target/classes/doc/books/pamHelpStylesheet.css b/target/classes/doc/books/pamHelpStylesheet.css new file mode 100644 index 00000000..b8403246 --- /dev/null +++ b/target/classes/doc/books/pamHelpStylesheet.css @@ -0,0 +1,34 @@ +BODY { + BACKGROUND-COLOR: FFFFFF +} +H1 { + FONT-FAMILY: Arial; + FONT-SIZE: 21; + COLOR: #6698FE; + BACKGROUND-COLOR: #DCFEEC; + margin-bottom: 0 +} +H2 { + FONT-FAMILY: Arial; + FONT-SIZE: 17; + COLOR: #6698FE; + BACKGROUND-COLOR: #CBDAEB; + margin-top: 0; +} +H3 { + FONT-FAMILY: Arial; + FONT-SIZE: 15; +} + +H4 { + FONT-FAMILY: Arial; + FONT-SIZE: 13; +} + +p { + FONT-FAMILY: Arial; + FONT-SIZE: 13; + margin-top: 10; + margin-left: 0; + margin-bottom: 0 +} \ No newline at end of file diff --git a/target/classes/help/JavaHelpSearch/DOCS b/target/classes/help/JavaHelpSearch/DOCS new file mode 100644 index 00000000..be8310ab Binary files /dev/null and b/target/classes/help/JavaHelpSearch/DOCS differ diff --git a/target/classes/help/JavaHelpSearch/DOCS.TAB b/target/classes/help/JavaHelpSearch/DOCS.TAB new file mode 100644 index 00000000..2ce4d447 Binary files /dev/null and b/target/classes/help/JavaHelpSearch/DOCS.TAB differ diff --git a/target/classes/help/JavaHelpSearch/OFFSETS b/target/classes/help/JavaHelpSearch/OFFSETS new file mode 100644 index 00000000..b4adef98 Binary files /dev/null and b/target/classes/help/JavaHelpSearch/OFFSETS differ diff --git a/target/classes/help/JavaHelpSearch/POSITIONS b/target/classes/help/JavaHelpSearch/POSITIONS new file mode 100644 index 00000000..709830a2 Binary files /dev/null and b/target/classes/help/JavaHelpSearch/POSITIONS differ diff --git a/target/classes/help/JavaHelpSearch/SCHEMA b/target/classes/help/JavaHelpSearch/SCHEMA new file mode 100644 index 00000000..44f1bb2d --- /dev/null +++ b/target/classes/help/JavaHelpSearch/SCHEMA @@ -0,0 +1,2 @@ +JavaSearch 1.0 +TMAP bs=2048 rt=1 fl=-1 id1=6559 id2=1 diff --git a/target/classes/help/JavaHelpSearch/TMAP b/target/classes/help/JavaHelpSearch/TMAP new file mode 100644 index 00000000..db83ebc0 Binary files /dev/null and b/target/classes/help/JavaHelpSearch/TMAP differ diff --git a/target/classes/help/JavaHelpSearch/compacted b/target/classes/help/JavaHelpSearch/compacted new file mode 100644 index 00000000..b08bc956 Binary files /dev/null and b/target/classes/help/JavaHelpSearch/compacted differ diff --git a/target/classes/help/Map.jhm b/target/classes/help/Map.jhm new file mode 100644 index 00000000..3ba894b0 --- /dev/null +++ b/target/classes/help/Map.jhm @@ -0,0 +1,863 @@ + + + + \ No newline at end of file diff --git a/target/classes/help/PAMGUARD.hs b/target/classes/help/PAMGUARD.hs new file mode 100644 index 00000000..b7d5a8e9 --- /dev/null +++ b/target/classes/help/PAMGUARD.hs @@ -0,0 +1,413 @@ + + +PAMGuard's deep learning module allows users to deploy a + large variety of deep learning models natively in PAMGuard. It is core + module, fully integrated into PAMGuard's display and data + management system and can be used in real time or for post processing + data. It can therefore be used as a classifier for almost any acoustic + signal and can integrate into multiple types of acoustic analysis + workflows, for example post analysis of recorder data or used as part + of real time localisation workflow.
+ +The deep learning module accepts raw data from different types + of data sources, e.g. from the Sound Acquisition module, clicks and + clips. It segments data into equal sized chunks with a specified + overlap. Each chunk is passed through a set of transforms which + convert the data into a format which is accepted by the specified deep + learning model. These transforms are either manually set up by the + user or, if a specific type of framework has been used to train a deep + learning model, then can be automatically set up by PAMGuard. + Currently there are three implemented frameworks
+
+
+
+ A diagram of how the deep learning module works in PAMGuard. + An input waveform is segmented into chunks. A series of transforms + are applied to each chunk creating the input for the deep learning + model. The transformed chunks are sent to the model. The results from + the model are saved and can be viewed in real time (e.g. mitigation) + or in post processing (e.g. data from SoundTraps). +
++ A generic model allows a user to load any model compatible with the djl (PyTorch (JIT), Tenserflow, ONXX) + library and then manually set up a series of transforms using + PAMGuard's transform library. It is recommended that users use an + existing framework instead of a generic model as these models will + automatically generate the required transforms. +
++ ANIMAL-SPOT + is a deep learning based framework which was initially designed for killer + whale sound detection) in noise heavy underwater recordings (see Bergler + et al. (2019)). It has now been expanded to a be species independent + framework for training acoustic deep learning models using PyTorch and Python. Imported + AnimalSpot models will automatically set up their own data transforms + and output classes. +
++ Ketos is an + acoustic deep learning framework based on Tensorflow and developed by + MERIDIAN. It has excellent + resources and tutorials and Python libraries can be installed easily + via pip. Imported Ketos model will automatically set up their own data + transforms and output classes. +
++ The module can be added from the File> Add modules > + Classifier > Raw deep learning classifier menu or by right + clicking in the data model. More than one instance of the module can + be added if multiple deep learning models are required. +
++ The module settings are opened by selecting the Settings > + Raw deep learning classifier menu. The main settings pane is shown + below and is split into three sections, Raw Sound Data, Segmentation + and Deep Learning Model +
+
+ 
+
+ The main settings pane for the deep learning module with + descriptions +
+The deep learning module accepts any raw data source i.e., any + data source that contains raw waveform data.
+If the data is continuous, e.g. from the Sound Acquisition + module then deep learning detections are saved to PAMGuard's data + management system if they pass a user defined prediction threshold. + The raw waveform data for segments which pass prediction threshold is + saved and the detection is annotated with the deep prediction results. +
+If the data source is an existing detection data stream, e.g. + clicks or clips, then the deep learning results are saved as an + annotation attached each detection. The data is segmented in exactly + the same way as continuous data and thus, depending on the length of + raw data within the detection, there can be more than one prediction + per detection.
+Channel grouping controls are used to arrange channels into + groups. Channels in the same group are saved together for downstream + processes. So, for example if channels 0 and 2 are in a group, then + the raw waveform data from both channel 0 and 2 will be saved and can + be used in downstream processes, e.g., for localisation.
++ The segmentation section defines how the raw data is segmented. Some + deep learning models require a specific segment size and others can be + run with different segment sizes. The Window Length is the + size of the segment in samples. The Hop Length is the overlap + (from the start of the segment) in samples. A Hop Length + which is the same as the segment length means no overlap. If a + prediction passes threshold, then the raw data from segments is saved + to PAMGuard binary files. If concurrent segments pass a prediction + threshold, then they are saved as one data unit. The Max. + re-merge is the maximum number of segments that can form a single + data unit before a new data unit is automatically created. +
+The deep learning model section is used to select the deep + learning model. The drop down menu is used to select the framework the + model is from e.g. Generic model. Note that each model type has a + unique user interface which appears just below the drop down menu - + currently these all look fairly similar.
+All frameworks require a model file to be selected using the + browse button (File icon). A wait icon will appear and the model will + be loaded. If the deep learning model loading is successful then the + filename of the model will appear (e.g. saved_model.pb)
++ Note: when a model is first loaded, the computer must be + connected to the internet as PAMGuard will download the correct + libraries for the computer to open the specific model. On Windows + machine these libraries are found in a hidden folder called ai.djl. + in the user account folder. +
+Once the model has loaded there some unique options depending on + the currently selected framework.
++ A generic model must be set up via the Advanced menu button. +
+
+ 
+
+ Before a sound segment can be classified it must be converted + into a format suitable for the deep learning model. This is achieved + by a list of transforms which convert a raw sound data into + an appropriate format. Usually this involves converting to a + spectrogram image and then performing a series of noise reductions + and interpolation step. For the generic model users either have to + manually add transforms and input the correct settings for each, or + load a transforms *.pgtr setting file + +
++ The Model Transforms tab in the advanced menu pane allows a + user to set up a set of transforms. The Add transfrom + + button adds a transforms and these can be dragged in order using the + drag handles on the left of each transform. Each transform has + it's own settings pane which can be expanded to show transform + specific settings. The bottom of the advanced settings pane shows a + preview of the data that will be input into the deep learning model, + including the shape of the input data e.g. a 100x50 image. +
+
+ 
+
+ The Model Settings tab allows the model inputs and outputs to + be defined +
++ The Model Settings tab allows the model input shape and + output shape/classes to be defined. Most models will have metadata on + the input and output data and these can be set by selecting the Use + default model shape and Use default model out switches + respectively. Otherwise, the input and output shape and the output + classes must be defined manually +
+The import and export buttons on the bottom of the advanced + settings pane can be used to export and import settings for the + generic model. This means that users do not have to manually set up + transforms and input and output data whenever settings up a new + PAMGuard data model and allow easier sharing of classifiers amongst + researchers.
++ If using an AnimalSpot or Ketos model then all transforms are + automatically set up. The transforms can be viewed and altered via the + Advanced menu button but in the majority of cases these settings + should not be used. It is advisable to select "Use default + segment length" to change the Window length to the + default for the selected model. Note that this is often necessary for + Ketos models but usually not a requirement for AnimalSpot models. +
+
+ 
+
+ An AnimalSpot or Ketos model will automatically create a list + of transforms with the appropriate settings. These is no need to use + the advanced pane but it is there in case users wish to change + transform settings for some reason +
+In real time, the deep learning model runs automatically when + processing starts. A warning will appear if there are issues with the + model and/or it cannot cope with real time speeds.
++ The deep learning module can be re-run on detector data (e.g. + click or clip detections) in PAMGuard viewer mode. Detections + can be reclassified by selecting the Settings > Raw Deep + Learning Classifier > Reclassify detections. Select the data range + in the reprocessing dialog e.g. Loaded Data and select Start. + Detections without a deep learning annotation will have one added and + detections with an existing annotation will have it overwritten. +
+Output from the deep learning module can be viewed in PAMGuard + viewer mode, or extracted from binary files using MATLAB or R.
+Detections form continuous raw data are shown in the datagram in + the same way as all data streams in PAMGuard.
+The Time base display FX is best way to view detailed data + outputs from the deep learning algorithm. The time base display can + display almost all data types in PAMGuard on a large variety of + different data axis. For example, click detections can be displayed on + an amplitude, bearing, ICI, waveform and/or frequency axis. Deep + learning detections (i.e. data units which have been saved from raw + data using the deep learning detector) can be displayed on the time + base display in the same way as many other detections and in addition, + there is a symbol manager options which allows the deep learning + detections or other detections which have been classified by the deep + learning module to be coloured by prediction class. This means that a + manual analyst can quickly navigate to detections with high prediction + values for a certain class. Hovering over or right clicking on a data + unit in the time display and selecting the information button, will + show the data unit’s metadata, including the prediction values for all + output classes from the deep learning model.
+
+ 
+
+ An example click detection module output coloured by deep + learning annotations. Click detections are annotated with the results + from the deep learning module. The symbol manager in the time base + display can be used to colour the clicks by the prediction for a + selected class +
+Other displays also show outputs from the deep learning module. + Hovering over data units in the click display will, for example, show + deep learning prediction values. The spectrogram will also show deep + learning detections as translucent blue boxes (these must be selected + in the right click menu).
+The easiest way to export to MATLAB is to select the desired + units in the time base display, right click and select the MATLAB + icon. Data units will be exported to a .mat file as list of structures + which is then saved to the clipboard. This file can be saved and then + dragged into MATLAB to open.
+
+ Where it is necessary to further analyse large datasets produced by
+ PAMGuard, there is a MATLAB-PAMGuard library which can directly import
+ the binary files which store PAMGaurd detection data. The library is
+ simple to use with the primary function being
+ loadPAMGuardBinaryFile.m.
+ This will load any binary file type (e.g. clicks, whistles, deep
+ learning detections) and return a list of data structures with the
+ detection data. The structures include annotations where deep learning
+ predictions are stored.
+
Here is a simple example loading up all the deep learning + detections for a right whale classifier.
+
+ % the folder containing PAMGuard binary files
+folder = '/Users/me/right_whale_project_1/PAMBinary/';
+
+ %load all the detections in the folder
+dldetections = loadPamguardBinaryFolder(folder, 'Deep_Learning_Classifier_Raw_Deep_Learning_Classifier_DL_detection_*.pgdf')
+
+
+ The predicitons for each class (in this case the classes are + noise and right whale) are easily accessed in the structure via;
+
+
+ %% access the prediciton form the first detection
+predicitons = dldetections(1).annotations.dlclassification(j).predictions;
+
+
+ The loaded detections can then be plotted by accessing the + waveform data in each structure;
+
+
+% plot all the spectrograms.
+clf
+tiledlayout(5,5)
+for i=1:length(dldetections)
+
+ nexttile
+
+ % generate the data for a spectrgram
+ [s, w, t] = spectrogram(dldetections(i).wave,512, 384,[],sR,'yaxis');
+
+ % create the time and frequency matrices required to plot a surface
+ [X, Y] = meshgrid(t,w);
+ % plot the surface (divide and multiply by 1000 to show milliseconds and kHz respectively)
+ surf(X*1000, Y/1000, 20*log10(abs(s))-140, 'EdgeColor', 'None')
+ view([0,90])
+
+ caxis([70, 140]-140)
+ ylim([0,0.5]);
+ xlabel('')
+ ylabel('')
+
+ if (mod(i,5)==0)
+ c = colorbar;
+ c.Label.String = 'Amplitude (dB)';
+ end
+
+ %x axis only on bottom plots
+ if (i>=20)
+ xlabel('Time (ms)')
+ end
+
+ %y axis only on left most plots
+ if (mod(i-1,5)==0)
+ ylabel('Frequency (kHz)')
+ end
+
+
+
+ 
+
+ Right whale detections from a deep learning model imported + and then plotted in MATLAB +
+In the same way as MATLAB export, the PAMGuard time base display + and export selected data units directly to an R struct which can be + imported easily into R..
++ R also has a well supported PAMGuard library with like for like + functions compared to the MATLAB library. The PAMBinaries R library + can be found here. +
+You should always have deep learning models in their own folder. + Do not have any additional jar files or other programming related + things (like .dll files) in the same or sub folders. This has been + known to cause issues with loading models which we have not got to the + bottom of yet.
+Pytorch models must be saved using jit to be compatible with + PAMGuard.
+Tensorflow models must be saved as .pb files to be opened in + PAMGuard.
+ + \ No newline at end of file diff --git a/target/classes/help/classifiers/rawDeepLearningHelp/docs/rawDeepLearning_Bugs.html b/target/classes/help/classifiers/rawDeepLearningHelp/docs/rawDeepLearning_Bugs.html new file mode 100644 index 00000000..2139a1b1 --- /dev/null +++ b/target/classes/help/classifiers/rawDeepLearningHelp/docs/rawDeepLearning_Bugs.html @@ -0,0 +1,32 @@ + + + + +You should always have deep learning models in their own folder. + Do not have any additional jar files or other programming related + things (like .dll files) in the same or sub folders. This has been + known to cause issues with loading models which we have not got to the + bottom of yet.
+Pytorch models must be saved using jit to be compatible with + PAMGuard.
+Tensorflow models must be saved as .pb files to be opened in + PAMGuard.
+Previous: + Viewing and Exporting Results
++ The module can be added from the File> Add modules > + Classifier > Raw deep learning classifier menu or by right + clicking in the data model. More than one instance of the module can + be added if multiple deep learning models are required. +
++ The module settings are opened by selecting the Settings > + Raw deep learning classifier menu. The main settings pane is shown + below and is split into three sections, Raw Sound Data, Segmentation + and Deep Learning Model +
+
+
+
+ The main settings pane for the deep learning module with + descriptions +
+The deep learning module accepts any raw data source i.e., any + data source that contains raw waveform data.
+If the data is continuous, e.g. from the Sound Acquisition + module then deep learning detections are saved to PAMGuard's data + management system if they pass a user defined prediction threshold. + The raw waveform data for segments which pass prediction threshold is + saved and the detection is annotated with the deep prediction results. +
+If the data source is an existing detection data stream, e.g. + clicks or clips, then the deep learning results are saved as an + annotation attached each detection. The data is segmented in exactly + the same way as continuous data and thus, depending on the length of + raw data within the detection, there can be more than one prediction + per detection.
+Channel grouping controls are used to arrange channels into + groups. Channels in the same group are saved together for downstream + processes. So, for example if channels 0 and 2 are in a group, then + the raw waveform data from both channel 0 and 2 will be saved and can + be used in downstream processes, e.g., for localisation.
++ The segmentation section defines how the raw data is segmented. Some + deep learning models require a specific segment size and others can be + run with different segment sizes. The Window Length is the + size of the segment in samples. The Hop Length is the overlap + (from the start of the segment) in samples. A Hop Length + which is the same as the segment length means no overlap. If a + prediction passes threshold, then the raw data from segments is saved + to PAMGuard binary files. If concurrent segments pass a prediction + threshold, then they are saved as one data unit. The Max. + re-merge is the maximum number of segments that can form a single + data unit before a new data unit is automatically created. +
+The deep learning model section is used to select the deep + learning model. The drop down menu is used to select the framework the + model is from e.g. Generic model. Note that each model type has a + unique user interface which appears just below the drop down menu - + currently these all look fairly similar.
+All frameworks require a model file to be selected using the + browse button (File icon). A wait icon will appear and the model will + be loaded. If the deep learning model loading is successful then the + filename of the model will appear (e.g. saved_model.pb)
++ Note: when a model is first loaded, the computer must be + connected to the internet as PAMGuard will download the correct + libraries for the computer to open the specific model. On Windows + machine these libraries are found in a hidden folder called ai.djl. + in the user account folder. +
+Once the model has loaded there some unique options depending on + the currently selected framework.
++ A generic model must be set up via the Advanced menu button. +
+
+
+
+ Before a sound segment can be classified it must be converted + into a format suitable for the deep learning model. This is achieved + by a list of transforms which convert a raw sound data into + an appropriate format. Usually this involves converting to a + spectrogram image and then performing a series of noise reductions + and interpolation step. For the generic model users either have to + manually add transforms and input the correct settings for each, or + load a transforms *.pgtr setting file + +
++ The Model Transforms tab in the advanced menu pane allows a + user to set up a set of transforms. The Add transfrom + + button adds a transforms and these can be dragged in order using the + drag handles on the left of each transform. Each transform has + it's own settings pane which can be expanded to show transform + specific settings. The bottom of the advanced settings pane shows a + preview of the data that will be input into the deep learning model, + including the shape of the input data e.g. a 100x50 image. +
+
+
+
+ The Model Settings tab allows the model inputs and outputs to + be defined +
++ The Model Settings tab allows the model input shape and + output shape/classes to be defined. Most models will have metadata on + the input and output data and these can be set by selecting the Use + default model shape and Use default model out switches + respectively. Otherwise, the input and output shape and the output + classes must be defined manually +
+The import and export buttons on the bottom of the advanced + settings pane can be used to export and import settings for the + generic model. This means that users do not have to manually set up + transforms and input and output data whenever settings up a new + PAMGuard data model and allow easier sharing of classifiers amongst + researchers.
++ If using an AnimalSpot or Ketos model then all transforms are + automatically set up. The transforms can be viewed and altered via the + Advanced menu button but in the majority of cases these settings + should not be used. It is advisable to select "Use default + segment length" to change the Window length to the + default for the selected model. Note that this is often necessary for + Ketos models but usually not a requirement for AnimalSpot models. +
+
+
+
+ An AnimalSpot or Ketos model will automatically create a list + of transforms with the appropriate settings. These is no need to use + the advanced pane but it is there in case users wish to change + transform settings for some reason +
+Next: + Running the Deep Learning module
+Output from the deep learning module can be viewed in PAMGuard + viewer mode, or extracted from binary files using MATLAB or R.
+Detections form continuous raw data are shown in the datagram in + the same way as all data streams in PAMGuard.
+The Time base display FX is best way to view detailed data + outputs from the deep learning algorithm. The time base display can + display almost all data types in PAMGuard on a large variety of + different data axis. For example, click detections can be displayed on + an amplitude, bearing, ICI, waveform and/or frequency axis. Deep + learning detections (i.e. data units which have been saved from raw + data using the deep learning detector) can be displayed on the time + base display in the same way as many other detections and in addition, + there is a symbol manager options which allows the deep learning + detections or other detections which have been classified by the deep + learning module to be coloured by prediction class. This means that a + manual analyst can quickly navigate to detections with high prediction + values for a certain class. Hovering over or right clicking on a data + unit in the time display and selecting the information button, will + show the data unit's metadata, including the prediction values for all + output classes from the deep learning model.
+
+
+
+ An example click detection module output coloured by deep + learning annotations. Click detections are annotated with the results + from the deep learning module. The symbol manager in the time base + display can be used to colour the clicks by the prediction for a + selected class +
+Other displays also show outputs from the deep learning module. + Hovering over data units in the click display will, for example, show + deep learning prediction values. The spectrogram will also show deep + learning detections as translucent blue boxes (these must be selected + in the right click menu).
+The easiest way to export to MATLAB is to select the desired + units in the time base display, right click and select the MATLAB + icon. Data units will be exported to a .mat file as list of structures + which is then saved to the clipboard. This file can be saved and then + dragged into MATLAB to open.
+
+ Where it is necessary to further analyse large datasets produced by
+ PAMGuard, there is a MATLAB-PAMGuard library which can directly import
+ the binary files which store PAMGaurd detection data. The library is
+ simple to use with the primary function being
+ loadPAMGuardBinaryFile.m.
+ This will load any binary file type (e.g. clicks, whistles, deep
+ learning detections) and return a list of data structures with the
+ detection data. The structures include annotations where deep learning
+ predictions are stored.
+
Here is a simple example loading up all the deep learning + detections for a right whale classifier.
+
+ % the folder containing PAMGuard binary files
+folder = '/Users/me/right_whale_project_1/PAMBinary/';
+
+ %load all the detections in the folder
+dldetections = loadPamguardBinaryFolder(folder, 'Deep_Learning_Classifier_Raw_Deep_Learning_Classifier_DL_detection_*.pgdf')
+
+
+ The predicitons for each class (in this case the classes are + noise and right whale) are easily accessed in the structure via;
+
+
+ %% access the prediciton form the first detection
+predicitons = dldetections(1).annotations.dlclassification(j).predictions;
+
+
+ The loaded detections can then be plotted by accessing the + waveform data in each structure;
+
+
+% plot all the spectrograms.
+clf
+tiledlayout(5,5)
+for i=1:length(dldetections)
+
+ nexttile
+
+ % generate the data for a spectrgram
+ [s, w, t] = spectrogram(dldetections(i).wave,512, 384,[],sR,'yaxis');
+
+ % create the time and frequency matrices required to plot a surface
+ [X, Y] = meshgrid(t,w);
+ % plot the surface (divide and multiply by 1000 to show milliseconds and kHz respectively)
+ surf(X*1000, Y/1000, 20*log10(abs(s))-140, 'EdgeColor', 'None')
+ view([0,90])
+
+ caxis([70, 140]-140)
+ ylim([0,0.5]);
+ xlabel('')
+ ylabel('')
+
+ if (mod(i,5)==0)
+ c = colorbar;
+ c.Label.String = 'Amplitude (dB)';
+ end
+
+ %x axis only on bottom plots
+ if (i>=20)
+ xlabel('Time (ms)')
+ end
+
+ %y axis only on left most plots
+ if (mod(i-1,5)==0)
+ ylabel('Frequency (kHz)')
+ end
+
+
+
+
+
+ Right whale detections from a deep learning model imported + and then plotted in MATLAB +
+In the same way as MATLAB export, the PAMGuard time base display + and export selected data units directly to an R struct which can be + imported easily into R..
++ R also has a well supported PAMGuard library with like for like + functions compared to the MATLAB library. The PAMBinaries R library + can be found here. +
+Previous: + Running the Deep Learning module
+Next: + Common Bugs and Mistakes
+In real time, the deep learning model runs automatically when + processing starts. A warning will appear if there are issues with the + model and/or it cannot cope with real time speeds.
++ The deep learning module can be re-run on detector data (e.g. + click or clip detections) in PAMGuard viewer mode. Detections + can be reclassified by selecting the Settings > Raw Deep + Learning Classifier > Reclassify detections. Select the data range + in the reprocessing dialog e.g. Loaded Data and select Start. + Detections without a deep learning annotation will have one added and + detections with an existing annotation will have it overwritten. +
+Previous: + Creating and Configuring the Deep Learning module
+Next: + Viewing and Exporting Results
+PAMGuard's deep learning module allows users to deploy a + large variety of deep learning models natively in PAMGuard. It is core + module, fully integrated into PAMGuard's display and data + management system and can be used in real time or for post processing + data. It can therefore be used as a classifier for almost any acoustic + signal and can integrate into multiple types of acoustic analysis + workflows, for example post analysis of recorder data or used as part + of real time localisation workflow.
+ +The deep learning module accepts raw data from different types + of data sources, e.g. from the Sound Acquisition module, clicks and + clips. It segments data into equal sized chunks with a specified + overlap. Each chunk is passed through a set of transforms which + convert the data into a format which is accepted by the specified deep + learning model. These transforms are either manually set up by the + user or, if a specific type of framework has been used to train a deep + learning model, then can be automatically set up by PAMGuard. + Currently there are three implemented frameworks
+
+
+
+ A diagram of how the deep learning module works in PAMGuard. + An input waveform is segmented into chunks. A series of transforms + are applied to each chunk creating the input for the deep learning + model. The transformed chunks are sent to the model. The results from + the model are saved and can be viewed in real time (e.g. mitigation) + or in post processing (e.g. data from SoundTraps). +
++ A generic model allows a user to load any model compatible with the djl (PyTorch (JIT), Tenserflow, ONXX) + library and then manually set up a series of transforms using + PAMGuard's transform library. It is recommended that users use an + existing framework instead of a generic model as these models will + automatically generate the required transforms. +
++ ANIMAL-SPOT + is a deep learning based framework which was initially designed for killer + whale sound detection) in noise heavy underwater recordings (see Bergler + et al. (2019)). It has now been expanded to a be species independent + framework for training acoustic deep learning models using PyTorch and Python. Imported + AnimalSpot models will automatically set up their own data transforms + and output classes. +
++ Ketos is an + acoustic deep learning framework based on Tensorflow and developed by + MERIDIAN. It has excellent + resources and tutorials and Python libraries can be installed easily + via pip. Imported Ketos model will automatically set up their own data + transforms and output classes. +
+Next: + Creating and Configuring the Deep Learning module
+From the File > Add Modules +> Detectors menu, select "ROCCA". +Enter a descriptive name for the new module and press OK.
+ROCCA requires an FFT +engine module +to operate. If no FFT engine module has been loaded, PAMGuard will warn +the user and automatically load one.
+When the ROCCA module is created, it will automatically try to +load a classifier model. +ROCCA will also check to see if an Enounter +Stats file exists. If it does, the user is given the +option to load the contents of the file into memory.
+Note: the Encounter Stats file +is +continually overwritten while ROCCA is running. If, upon startup, the +user +does not load the data into memory, the information in the file will be +lost. Thus if the user does not wish to load the data but +still desires to keep it, the file should be renamed before continuing +with Pamguard.
+Note: the Sound +Acquisition and FFT +Engine modules must be configured before configuring ROCCA.
+From the Detection menu, select "ROCCA Parameters". A new +dialog should appear containing five tabs: Source Data, Contours/Classifier, +Output, Filename Template, +and Notes.
+
+Data Source: where ROCCA should get it's input data from. +Options include an FFT module (select this if using the manual +classifier), a Click +Detector, and a Whistle +and Moan Detector. Multiple sources can be selected. The +whistle and moan detector and/or click detector should be selected if +using the automated classifier.
+FFT Data source: the fft data source to be used. The +channels listed are those currently selected in the FFT +Parameters dialog. ROCCA will save a wav file clip of each +manually selected whistle contour whenever it is classified and added +to the current encounter. Check the channel boxes corresponding to the +channels you wish to save to this clip wav file. Note that this is +different than the channels displayed in the spectrogram window, which +are set in the display +options dialog. Whistles can be selected and contours +extracted from any channel displayed, but the saved whistle clips will +only contain data from the channels selected in the FFT data source +box. So it is possible (though not recommended) to extract and classify +a whistle from Channel 0, but only save the data from Channels 1 and 2.
+Click Detector source: the Click Detector to be used. Both +the click source and the noise source must be specified, along with the +appropriate channels. There are two options for the click source: Clicks +and Tracked Clicks. Selecting Clicks +sends all auto-detected +clicks to the ROCCA module. Selecting Tracked +Clicks sends only those clicks which are assigned to click +trains (see Click +Train Identification and Click +Detector displays +for more details) to ROCCA. The 'Select Click Types' button +allows the +user to select which types of clicks (as classified by the Click +Detector module based on user-supplied settings) to send from the Click +Detector to ROCCA for analysis.
+Noise Data +Samples should be selected for the Click Detector Noise +Source. These noise data samples are automatically collected by the +Click Detector module at intervals which can be set by the user in the +Click Detector Settings dialog window. The noise samples are used to +calculate the RMSNOISE and SNR click variables
+Note: +a Click +Detector Module must first be configured and at least one +Click Classifier defined, for appropriate options to be displayed in +the Click Detector Data Source frame. See the PAMGuard help files for +full details on creating and configuring the Click Detector module.
+Whistle +and Moan source: the Whistle & Moan Detector to be used. This +drop-down box will list all currently configured Whistle & Moan +Detector modules. After +performing its own analysis, the Whistle +& Moan Detector will +send all detected whistles to the ROCCA module. ROCCA will then measure +contour +variables, classify the whistles, add the results to the sidebar and +save the results to output +files, +but no popup Spectrogram window will appear.
+Note: a Whistle +& Moan Detector Module must first be added and +configured for appropriate options to be displayed in the Whistle +& Moan Data Source frame. See the PAMGuard help files for full +details on creating and configuring the Whistle & Moan Detector +module.
+GPS Source: the source for GPS signals. Some encounter +classifiers use latitude and longitude +as classification variables.
+
Whistle +Classifier: select the classifier to be used for whistles. +The available classifier models were created based on the Weka +Random Forest model. A classifier model uses the file extension .model. +To select a classifier model, click the Select Whistle Classifier +button. To not classify whistles at all, click the Clear Whistle Classifier +button. At +the moment the ability to create new classifiers within Pamguard is not +available.
+Click +Classifier: select the classifier to be used for clicks. +The available classifier models were created based on the Weka +Random Forest model. A classifier model uses the file extension .model. +To select a classifier model, click the Select Click Classifier +button. To not classify clicks at all, click the Clear Click Classifier +button. At +the moment the ability to create new classifiers within Pamguard is not +available.
+Encounter +Classifier: select the classifier to be used for acoustic +encounters. +Classifier models are created based on the Weka +Random Forest model. A classifier model uses the file extension .model. +To select a classifier model, click the Select Encounter Classifier +button. To not classify encounters at all, click the Clear Encounter Classifier +button. At +the moment the ability to create new classifiers within Pamguard is not +available.
+Whistle/Click Threshold: the threshold value to use when classifying +individual whistles or clicks. If the percent of trees voting +for the +predicted species in the random forest falls below this threshold, the +whistle or click is considered non-classifiable and is labelled as +‘ambiguous’.
+Encounter Threshold: the threshold value to use when classifying +encounters. If the percent of trees voting for the predicted +species in the random forest falls below this threshold, the encounter +is considered non-classifiable and is labelled as ‘ambiguous’.
+Noise Sensitivity: specify the global noise sensitivity +parameter to use when extracting a +whistle +contour.
+Energy Bin Calc Size: specify the size of the frequency +bin used to calculate the energy around each peak frequency.
+Calculate +Whistle Encounter Stats:select whether or not to calculate ancillary +variables for the detected whistles, for use by the Encounter +Classifier. Calculations may cause memory issues when there are many +(>1000) whistles.
+Calculate Click School Stats:select whether or not to +calculate ancillary variables for the detected clicks, for use by the +Encounter Classifier. Calculations may cause memory issues when there +are many (>1000) clicks. +
+Note that the Whistle, Click and Encounter classifiers +selected +by the +user should all have been trained with the same species list in order +to be compatible with each other.
+Note also +that if either whistle or click encounter stats are not calculated, the +encounter +classification will be based on whistle or click classification results +only. The number of +trees that voted +for each species will be tallied over all whistles and clicks in the +encounter +and the encounter will be classified as the species with +the highest +number of random forest tree votes. Even if an encounter +classifier has been loaded, it will be ignored.
+
+Output Directory: +specify which directory clip wav files, whistle contour points and +whistle contour variable measurements are saved +to. +Note that, with Microsoft Windows operating systems, it is a good idea +to select a directory that does not require administrator privileges to +save to.
+Contour +Stats Save File: +specify the name of the file that classified whistle contour variables +are saved to. The file will be saved to the output directory, specified +above. Each classified whistle is appended to the end of the file when +one of the Save buttons in the Spectrogram Popup window is clicked.
+Encounter Stats Save File: +specify the name of the file that encounter classifications are saved +to. The file will be saved to the output directory, specified above. +Note that in order to use the latest encounter numbers, this file is +overwritten during each save. While this is not a problem as long as +PAMGuard is run continuously, if this file exists when PAMGuard is +first loaded the contents will be lost. If the file exists during start +up, the user is warned and given a chance to load/rename/backup the +existing file.
+
+In addition to the Contour Stats and Encounter Stats save +files, +ROCCA +also saves a whistle clip (wav format) and a list of the contour points +(time and frequency, csv format). These files will be named according +to the template given in the text box on this tab. As part of the name, +the user is able to use any of the following symbols. When the files +are saved, ROCCA will substitute the actual values for the symbol names.
++
| Symbol | +Meaning | ++ | Symbol | +Meaning | +
|---|---|---|---|---|
| f | +name of source | ++ | H | +hour, 24-hour clock | +
| n | +detection number | ++ | h | +hour, 12-hour clock | +
| X | +detection tally/count | ++ | a | +am or pm | +
| t | +channel/track number | ++ | m | +minute | +
| Y | +year, 4 digits | ++ | s | +second | +
| y | +year, 2 digits | ++ | S | +second of the day, 5 digits | +
| M | +month | ++ | d | +tenths of a second | +
| D | +day of the month | ++ | c | +hundredths of a second | +
| J | +day of the year, 3 digits | ++ | i | +thousandths of a second | +
Note that all date/time values are GMT.
+
+This tab provides the user an opportunity to save additional +information about the data. Any number of text boxes can be +used. The information contained in the text boxes will be saved on +every row of the Contour +Parameters +file. In addition, a text file containing standard notes can be loaded. +The contents of the text file will then be available in a drop-down +list for each text box. The format of the text file is one note per +line.
+Note: commas cannot be used in the text boxes or the standard +notes text file.
+ROCCA must be added to the Mark +Observers +list in the spectrogram in order to receive captured data. To do so, +right click on the spectrogram and select Settings. Select the Mark +Observers tab and check the box beside ROCCA. If ROCCA is not listed as +a possible mark observer, it has not been added as a module.
+The whistle contour is automatically extracted from the spectrogram +by stepping through the spectra one time slice at a time and measuring +the peak frequency for each slice within a specific frequency bin. The +upper and lower limits of the search bin are defined by the peak +frequency of the previous time slice +/- the noise sensitivity (as +defined in the Rocca Parameters window). The frequency bin of the first time slice is determined by the user-selected start frequency +/- the noise sensitivity.
+If the contour does not match the underlying whistle, the first step should be to adjust the noise sensitivity.
+ +Decreasing the sensitivity narrows the frequency band +used when searching for the peak frequency in the next time slice. A +smaller band means the extraction algorithm is less likely to jump from +the whistle contour to a nearby noisy peak. However, a smaller band +also means that if the algorithm does jump to a nearby noisy peak, +there is less chance it will be able to jump back to the whistle +contour.
Increasing the sensitivity widens the +frequency band used when searching for the peak frequency in the next +time slice. A wider band increases the chances that an extraction gone +off-track and following noise will be able to jump back to the whistle +contour. However, a wider band also increases the chances of going +off-track in the first place.
 |
+ A +button is provided in the top toolbar to quickly adjust noise +sensitivity. The spectrogram will automatically update with the +recalculated contour each time the sensitivity is changed. |
+
The highpass and lowpass filters limit the contour extraction +algorithm to only function within a specific frequency band. The +highpass filter defines the lower bound, and the lowpass filter defines +the upper bound. Specify a filter by typing in the desired frequency +and hitting <enter>, or hitting the <Set> button and +clicking on the desired frequency in the spectrogram. The filter is +displayed on the spectrogram as a red horizontal line. If the +extraction algorithm finds a peak frequency lower than the highpass +filter specified, the peak frequency will be set to the value of the +highpass filter. Similarly, if the extraction algorithm finds a peak +frequency higher than the lowpass filter specified, the peak frequency +will be set to the value of the lowpass filter.
+The filters can be reset by clicking the <Reset Filters> button.
+ |
+ Individual +contour points can be dragged manually to new positions. In order to +view the points, move the mouse over the spectrogram and press the left +mouse button. Try to move the mouse to a position away from the current +whistle contour, to avoid accidentally dragging a contour point. +Contour points will be displayed as light green dots. |
+
 |
+ Contour +points can only be dragged vertically. That is, the frequency can be +changed but not the time slice. Once the contour point to be moved is +determined, position the mouse over top of the point and press and hold +the mouse button. The contour points will again be displayed as light +green dots, but the point closest to the cursor will have a red circle. +Move the mouse up or down to the desired frequency, and release the +mouse button. |
+
Once a contour point has been moved, it will be locked in the +new position even if the contour is recalculated by adjusting the noise +sensitivity, modifying filters or clicking the <Recalc Contour> button. +In this way, if the contour extraction algorithm has followed noise +instead of the desired whistle, the user can move a point to the +correct position and get the extraction back on track. The contour +point can still be moved manually, and clicking the <Reset Contour> button will unlock all locked points.
+ + + +Previous: +Spectrogram Popup Window
+Next: +Whistle and Encounter Classification
+ +The ROCCA (Real-time Odontocete Call Classification Algorithm) +module is intended to provide a set of measured variables for detected +acoustic events. The variables differ depending on whether the acoustic +detection is a delphinid whistle or click. ROCCA uses these parameters +in conjunction with a user-selected random forest classification model +to classify the whistle or click to species. Three random forest models +are available; one for odontocete species in the northwest Atlantic, +one for species in the temperate Pacific and one for species in the +waters surrounding Hawaii.
+Individual +whistle/click detections and classifications are grouped into +user-defined Encounter +Numbers. An encounter is defined as a set of +whistles and/or clicks that +can all be attributed to one school of odontocetes. Variables +describing the acoustic behavior of the encounter are +measured from the +whistle and click detections for that encounter. Each encounter is +classified based on information from detected whistles, clicks and +ancillary variables using the encounter classifier, or as the +species with the highest number of random forest tree votes if no event +classifier has been selected.
+ROCCA classifies delphinid whistles based on spectrographic +measurements extracted from whistle contours. The contour extraction +algorithm measures +50 different variables for each contour. Whistles can be classified +based on measurements taken manually or based on measurements taken +automatically. Manual classifiers are available for species in the +tropical Pacific Ocean (TropPacWhist.model) and for species in the +northwest Atlantic +(NWAtlWhist.model). Automated whistle +classifiers are available for species in the northwest Atlantic +(NWAtlWhist_auto.model), +the temperate Pacific (TempPacWhist_auto.model) and the waters +surrounding Hawaii (HIWhist_auto.model).
+The manual classifier requires seven main steps: +
+User selects a whistle from the spectrogram display by +drawing a box around it using the cursor
+The whistle is captured by ROCCA and displayed in a new +spectrogram window +window
+The whistle contour is traced either automatically by +ROCCA or +manually using the cursor. The user can manipulate the trace, if +desired
+The time-frequency points are automatically extracted from +the contour
+The contour parameters are automatically measured
+The contour is classified using the currently-loaded +classifier model
+The classified whistle statistics are added to the +specified Encounter in the GUI display and the saved +data files
+ROCCA can also be used in conjunction with the Whistle +& Moan Detector module to measure and classify +whistles detected and extracted automatically.
+ROCCA measures +17 variables from clicks passed to it by the Click +Detector module. Each click is classified to species based on +these variables and the currently loaded classifier model, and the +click statistics are added to the specified Encounter +in the GUI display and the saved data files.
+Classifiers are available for species in the tropical Pacific +Ocean (TropPacClick.model), the northwest Atlantic +(NWAtlClick.model), the temperate Pacific (TempPacClick.model) and the +waters surrounding Hawaii (HIClick.model).
+ROCCA measures +17 variables from the whistles and clicks classified within each +encounter. The encounter is classified to species based on +these variables and the currently loaded classifier model, and the +results are passed to the GUI display and the saved data files. + Note that if no encounter classifier has been specified, the +encounter will be classified based on the species in the encounter with +the highest cumulative percentage of random forest tree votes.
+Classifiers are available for encounters in the tropical Pacific +Ocean (TropPacEnc.model), the northwest Atlantic +(NWAtlEnc.model), the temperate Pacific (TempPacEnc.model) and the +waters surrounding Hawaii (HIEnc.model).
+Oswald, J. N., Rankin, S., Barlow, J., and Lammers, M. O. (2007). +A tool for real-time acoustic species identification of delphinid whistles, +The Journal of the Acoustical Society of America, 122, 587.
+ +ROCCA saves three different files during manual whistle contour +extraction and classification: whistle wav file clip, contour points +and contour variable measurements. During automated click or whistle +analysis, ROCCA only saves the measured variables to the contour +variables file. ROCCA will also saves school stats automatically every +five minutes, +as well as when the <Save Encounter> button is clicked.
+If a database module is being used, ROCCA will also save the +data to two tables: Rocca_Whistle_Stats and Rocca_Encounter_Stats.
+The whistle clip is saved with a wav format to the output directory. +The start and end points of the clip are defined by the start and end +points originally selected by the user in the spectrogram popup. The +channels saved to the clip file are specified in the ROCCA Parameters +window.
+The filename is defined by the user in the ROCCA +Parameters window
+The time/frequency pair for each contour point in the extracted whistle contour is saved in +CSV format in the output +directory. The duty cycle, the energy in a frequency bin +around the peak frequency (as defined in the ROCCA +Parameters window), and the RMS value of the amplitude are +also saved.
+The filename is defined by the user in the ROCCA +Parameters window
+The variables measured from the current whistle contour/click, as +well as +the species classification (if a whistle), are saved in CSV format +in the output +directory. +The information from each whistle/click is appended to the end of the +file and the file is never overwritten. Thus, this file will continue +to collect classification information every time Pamguard/ROCCA is run.
+Other saved information for each whistle includes the sound +source, +the analysis date and time, the encounter number, and any notes included in the ROCCA Parameters +Notes +tab. The end of each row lists the name of the random forest model, the +random forest tree votes for each species and a list of +the species included in the classifier. The species names were added to each row instead of +the header line because the header would be created based on +information from the very first whistle contour analyzed only. If the +classification model is changed for subsequent analysis, the species +list may be different and no longer match the header. By including the +species list in the row, the user is always able to verify which +species were included in the classification algorithm for that +particular whistle contour or click.
+The filename is specified in the ROCCA +Parameters window.
+If a database module is being used, the data will also be +saved to the Rocca_Whistle_Stats table.
+All encounter numbers, with the species classification +break-down for each, are saved as a CSV file in the output directory. +Also included for each encounter number is the overall encounter +duration, the duration of the whistles only, the duration of the clicks +only, the number of whistles/clicks, the minimum/maximum/average time +between whistles/clicks, the number of +whistles/clicks per second, the whistle/click density (the sum of the +individual durations / encounter length), the whistle/clicks overlap +(the total number of seconds that two whistles/clicks overlap), the +cumulative random forest tree vote totals for each species, as well as +a species list and the overall encounter classification (based on the +species with the highest cumulative tree vote total).
+Each time the encounter stats file is saved, either through the +auto-save function or by the user pressing the <Save +Encounter> button, the file is overwritten in order to +update any renamed encounter numbers. Since an encounter number can be +renamed but never deleted, no information will be lost when overwriting +an old file during a single Pamguard session. HOWEVER, if Pamguard is +closed and restarted the file will be overwritten with +blank data and all prior information will be lost. The +file is checked during Pamguard startup, and if it exists the user is +given the opportunity to rename it before it is lost, and/or load the +existing data back into the system.
+Note that when examining a particular encounter number, the +user should refer to the species list at the end of the row instead of +the species listed in the header. The header information is taken from +the first encounter number listed; if subsequent encounter numbers use +a different classification model, the species may change and this +change would not be reflected in the header.
+The filename is specified in the ROCCA +Parameters window.
+If a database module is being used, the data will also be +saved to the Rocca_Encounter_Stats table.
+To manually classify a whistle using ROCCA, the user must +first select the whistle from the scrolling spectrogram display. Move +the cursor to one corner of the whistle, press and hold the mouse +button while dragging the cursor to the opposite corner, and release +the button. A red box will be drawn around the selection, and the time +and frequency of the starting point (upper left corner) and ending +point (lower right corner) of the box are displayed in the ROCCA +sidebar for reference.
+ +
When the mouse button is released, a new window will be opened +containing that portion of the spectrogram selected by the user. The +new window is minimized automatically to allow the user to continue +selecting whistles from the scrolling spectrogram. The user does NOT +need to classify the whistle immediately. The number of captured +whistles is only limited by the amount of memory available on the +computer.
+If an Encounter +Number has not yet been specified, the user will be prompted +for one after the first whistle has been selected.
+Previous: +ROCCA Creation and Configuration
+Next: +Spectrogram Popup Window
+ROCCA assembles the results of individual whistle +classifications +into groups as defined by the user. Each group must be given a name, +the Encounter Number. In addition to +classifying individual +whistle, ROCCA will also classify the Encounter Number +to species. This is known as the Encounter Classification and is +determined by either using the encounter classifier model (if loaded), +or summing the percentage of tree votes for each species over all of +the whistles/clicks in that Encounter Number and selecting the species +with the highest total.
+
+Encounter number: the current encounter number. This is +the encounter number used when a whistle is selected from the +spectrogram display.
+Scroll buttons: scroll through the list of encounter +numbers.
+Classification +results: the individual classification tally for the current encounter +number. The list of possible species is based on the classifier model +currently loaded. The number beside the species name indicates the +number of whistles/clicks that have been classified +as that species.
+Encounter classification: the overall species classification +for the current encounter number.
+Encounter ID: text box allowing user to add notes to +contour output file. This text box is identical to the box found in the +ROCCA +parameters configuration window.
+Known Species: text box allowing user to add notes to +contour output file. This text box is identical to the box found in the +ROCCA +parameters configuration window.
+Rename +Encounter: allows the user to rename the current encounter. Any output +files previously +saved that use the old encounter number in the filename will be renamed +with the new encounter number. Note that the information in +the whistle +contour stats save file +is NOT updated - the user must modify any references to the old +encounter number manually. Also note that the user will not be allowed +to duplicate encounter numbers
+Classify Encounter: classifies the encounter one of two +ways. If an Encounter Classifier model has been loaded +and both whistle and click encounter stats have been calculated, +a random forest classifier is used to classify the encounter based on +the output of the whistle and click classifiers. If an Encounter +Classifier model has not been loaded, or if either the whistle or click +encounter stats are not being calculated, the encounter is classified +as the species with the highest cumulative percentage of votes.
+Save Encounter: +overwrites the current Encounter Stats file (as defined in the ROCCA +Parameters window) with the current list of encounters and +statistics. Encounter statistics are also automatically saved every 5 +minutes.
+New Encounter: create a new encounter number
+Whistle Start: lists the time and frequency of the first +user-selected point on the spectrogram
+Whistle +End: lists the time and frequency of the second user-selected point on +the spectrogram. Note that once the second point is selected, the +portion of the spectrogram is captured in a new popup window.
+Previous: +Whistle and School Classification
+ +Once a whistle has been selected in the main spectrogram +window, a new window opens containing the portion of the spectrogram +selected by the user. The user must click on the starting point of the +whistle, and then the ending point (note that these can be reselected +later). Once the starting and ending points have been defined, ROCCA +will extract and display the whistle contour (shown in yellow).
+
+Window Title: displays the current detection tally. ROCCA +keeps track of how many whistles have been selected in the current +PAMGuard session and displays this information in the window title.
+Zoom In/Out/Reset: changes the zoom level of the +spectrogram.
+Increase/Decrease Brightness: modifies the brightness of +the spectrogram. Note that this only modifies the spectrogram display. + The underlying contour extraction algorithm is not affected.
+Increase/Decrease Contrast: modifies the contrast of the +spectrogram. Note that this only modifies the spectrogram display. + The underlying contour extraction algorithm is not affected.
+Noise Sensitivity spinner: modifies the noise sensitivity +parameter used for contour +extraction. This parameter controls the width of +the frequency band that is used when searching for the peak frequency +in the next time slice (see ‘Adjusting noise sensitivity’). The contour +is automatically recalculated when this value is changed, and the +spectrogram display is updated. Note +that any contour points moved +manually will not be changed when +the noise sensitivity parameter is changed. Note also that the noise +sensitivity parameter does not change the global noise sensitivity +parameter as specified in the Rocca +Parameters window, only the noise sensitivity used in this +spectrogram popup window.
+Spectrogram window: the current spectrogram.
+Select Contour Start/Contour End: allows user to reselect +the starting or ending point of the whistle. Upon selection, the +contour will recalculated automatically.
+Turn Contour Off: toggle the contour display on and off.
+Pick Points: when clicked, erases existing contour trace +and enters 'Selection' Mode. In selection mode the user can manually +select points along the contour by clicking on the spectrogram itself. +The user can select any number of points, but only one frequency per +time bin is allowed. If multiple frequencies are selected within a time +bin, only the first is kept and the rest are ignored. The user can also +hold the mouse button down and drag the mouse along the contour to +quickly select multiple points. When the Pick Points button is pressed +a second time, Selection Mode ends. ROCCA will fill in any missing time +bins using linear interpolation, and then proceed to calculate the +contour variables.
+Highpass/Lowpass/Reset +filters: limits the contour +extraction algorithmso that it functions only within a +specific +frequency band. Specify a filter by either typing in the desired +frequency and hitting <enter>, or hitting the +<Set> button and clicking on the desired frequency in the +spectrogram. The frequency filter is drawn as a horizontal red line on +the spectrogram. The contour is automatically recalculated when these +values are modified, and the spectrogram display is updated. Reset the +filters by clicking the <Reset Filters> button. Note that +any contour points manually +moved will not be changed. Note also that the spectrogram +display is not affected by the filters, only the contour extraction.
+Undo Last Move: return the last contour point that was moved +manually to its previous location.
+Recalc Contour: +recalculate the contour after manually +moving one or more contour points to new positions.
+Reset Contour: +unlock all contour points that have been manually moved.
+Classify/Reclassify: classify the currently-extracted +contour, or reclassify the contour after changes have been made. The +classification is displayed to the left of the button.
+Save as encounter [...]: save the +whistle clip wav file, contour points, and measured contour variables +to the directory +specified in the Rocca +Parameters window using the encounter number that was active +when the whistle was captured in the spectrogram. The encounter number +is shown on the button for reference. The spectrogram popup window is +then closed and the focus returns to the main PAMGuard display. +Classification results will be added to the Rocca Sidebar.
+Save as diff encounter: save the whistle clip wav file, +contour +points, and measured contour variables to the directory specified in +the Rocca +Parameters window, but first query the user as to which encounter number to use. +The spectrogram popup window is then closed and the focus returns to +the main PAMGuard display. Classification results will be +added to the Rocca Sidebar.
+Save WAV only: save the whistle clip wav file to the +directory +specified in the Rocca +Parameters window using the current encounter number (shown +in the window title bar). This option is useful if the user wishes to +classify the whistle later.
+Discard and Exit: discard the current whistle, close the +spectrogram popup window and return to the main Pamguard display +without saving anything.
+Time/Frequency: displays the current time and frequency +location of the +cursor.
+Previous: +Selecting a Whistle
+Next: +Contour Extraction / Manipulation
+ROCCA classifies whistles, clicks and encounters using Random +Forest classifiers. ROCCA currently uses a Random Forest classifier +model based on the open-source statistical software package Weka. +For more information on Random Forests and the WEKA package, the user +is encouraged to refer to the book Data +Mining: Practical Machine Learning Tools and Techniques
+Table 1 lists the 50 variables +measured from each whistle +contour.
+| +Variable Code + | +Variable Name | +Units | +Explanation | +
| FREQBEGSWEEP | +Beginning Sweep | +Categorical variable | +Slope of the beginning sweep (1=positive -1=negative, +0=zero) | +
| FREQBEGUP | +Positive beginning sweep | +Binary variable | +1=beginning slope is positive, 0=beginning slope is +negative | +
| FREQBEGDWN | +Negative beginning sweep | +Binary variable | +1=beginning slope is negative, 0=beginning slope is +positive | +
| FREQENDSWEEP | +Ending sweep | +Categorical variable | +Slope of the beginning sweep (1=positive -1=negative, +0=zero) | +
| FREQENDUP | +Positive ending sweep | +Binary variable | +1=ending slope is positive, 0=ending slope is +negative | +
| FREQENDDWN | +Negative ending sweep | +Binary variable | +1=ending slope is negative, 0=ending slope is +positive | +
| FREQBEG | +Beginning frequency | +Hz | +Beginning frequency | +
| FREQEND | +Ending frequency | +Hz | +Ending frequency | +
| FREQMIN | +Minimum frequency | +Hz | +Minimu frequency | +
| DURATION | +Duration | +Seconds | +Duration of the whistle | +
| FREQRANGE | +Frequency range | +Hz | +Maximum frequency - minimum frequency | +
| FREQMAX | +Maximum frequency | +Hz | +Maximum frequency | +
| FREQMEAN | +Mean frequency | +Hz | +Mean frequency | +
| FREQMEDIAN | +Median frequency | +Hz | +Median frequency | +
| FREQSTDDEV | +Standard deviation of the frequency | +Hz | +Standard deviation of the frequency | +
| FREQSPREAD | +Frequency spread | +Hz | +Difference between the 75th and the 25th percentile of +the frequency | +
| FREQQUARTER1 | +First quarter frequency | +Hz | +Frequency at one-quarter of the duration | +
| FREQQUARTER2 | +Half frequency | +Hz | +Frequency at one-half of the duration | +
| FREQQUARTER3 | +Third quarter frequency | +Hz | +Frequency at three-quarters of the duration | +
| FREQCENTER | +Center frequency | +Hz | +(minimum frequency + (maximum frequency - minimum +frequency)) / 2 | +
| FREQRELBW | +Relative bandwidth | +Hz | +(maximum frequency - minimum frequency)/center frequency | +
| FREQMAXMINRATIO | +Maximum-minimum ratio | +None | +Maximum frequency / minimum frequency | +
| FREQBEGENDRATIO | +Beginning-ending ratio | +None | +Beginning frequency / end frequency | +
| FREQCOFM | +Coefficient of frequency modulation | +None | +Take 20 frequency measurements equally spaced in time, +then subtract each frequency value from the one before it. COFM is the +sum of the absolute values of these differences, all divided by 10,000 | +
| FREQNUMSTEPS | +Number of steps | +None | +10 percent or greater increase or decrease in frequency +over two contour points | +
| NUMINFLECTIONS | +Number of inflection points | +None | +Changes from positive to negative or negative to +positive slope | +
| INFLMAXDELTA | +Maximum delta | +Seconds | +Maximum time between inflection points | +
| INFLMINDELTA | +Minimum delta | +Seconds | +Minimum time between inflection points | +
| INFLMAXMINDELTA | +Maximum-minimum delta ratio | +None | +Maximum delta / minimum delta | +
| INFLMEANDELTA | +Mean delta | +Seconds | +Mean time between inflection points | +
| INFLSTDDEVDELTA | +Standard deviation delta | +Seconds | +Standard deviation of the time between inflection points | +
| INFLMEDIANDELTA | +Median delta | +Seconds | +Median of the time between inflection points | +
| FREQSLOPEMEAN | +Mean slope | +Hz/second | +Overall mean slope | +
| FREQPOSSLOPEMEAN | +Positive slope | +Hz/second | +Mean positive slope | +
| FREQNEGSLOPEMEAN | +Negative slope | +Hz/second | +Mean negative slope | +
| FREQABSSLOPEMEAN | +Absolute slope | +Hz/second | +Mean absolute value of the slope | +
| FRQESLOPERATIO | +Positive-negative slope ratio | +None | +Mean positive slope / mean negative slope | +
| FREQSWEEPUPPERCENT | +Percent positive | +None | +Percent of the whistle that has a positive slope | +
| FREQSWEEPDWNPERCENT | +Percent negative | +None | +Percent of the whistle that has a negative slope | +
| FREQSWEEPFLATPERCENT | +Percent flat | +None | +Percent of the whistle that has a zero slope | +
| NUMSWEEPSUPDWN | +Positive-negative slope | +None | +Number of inflection points that change from positive +slope to negative slope | +
| NUMSWEEPSDWNUP | +Negative-positive slope | +None | +Number of inflection points that change from negative +slope to positive slope | +
| NUMSWEEPSUPFLAT | +Positive-flat slope | +None | +Number of times the slope changes from positive to zero | +
| NUMSWEEPSDWNFLAT | +Negative-flat slope | +None | +Number of times the slope changes from negative to zero | +
| NUMSWEEPSFLATDWN | +Flat-negative slope | +None | +Number of times the slope changes from zero to negative | +
| NUMSWEEPSFLATUP | +Flat-positive slope | +None | +Number of times the slope changes from zero to positive | +
| FREQSTEPUP | +Steps up | +None | +Number of steps that have increasing frequency | +
| FREQSTEPDOWN | +Steps down | +None | +Number of steps that have decreasing frequency | +
| INFLDUR | +Inflection points / duration | +None | +Number of inflection points / duration | +
| STEPDUR | +Steps/duration | +None | +Number of steps / duration | +
To classify a whistle, the vector of variables measured from +that +whistle is analysed with the random forest model, which contains +hundreds of classification trees. Each tree in the forest classifies +the whistle and final classification is based on the species that the +greatest percentage of trees voted for. If the greatest percentage of +tree votes falls below the whistle threshold (as specified in the ROCCA +Parameters window) +, the whistle is classified as Ambiguous.
+Table 2 lists the 17 variables measured from each click.
+ +| Variable Code + | +Variable Name | +Units | +Explanation | +
| DURATION | +Duration | +Seconds | +Duration of the click | +
| FREQPEAK | +Peak frequency | +Hz | +frequency with the highest amplitude | +
| BW3DBLOW | +-3dB bandwidth lower limit | +Hz | +First frequency lower than the peak frequency at which +the amplitude has dropped by 3dB | +
| BW3DBHIGH | +-3dB bandwidth upper limit | +Hz | +First frequency higher than the peak frequency at which +the amplitude has dropped by 3dB | +
| BW3DB | +-3dB bandwidth | +Hz | +BW3DBHIGH - BW3DBLOW | +
| BW10DBLOW | +-10dB bandwidth lower limit | +Hz | +First frequency lower than the peak frequency at which +the amplitude has dropped by 10dB | +
| BW10DBHIGH | +-10dB bandwidth upper limit | +Hz | +First frequency higher than the peak frequency at which +the amplitude has dropped by 10dB | +
| BW10DB | +-10dB bandwidth | +Hz | +BW10DBHIGH - BW10DBLOW | +
| RMSSIGNAL | +Signal RMS | +dB | +Root-mean-square of the click amplitude | +
| RMSNOISE | +Noise RMS | +dB | +Root-mean-square of the noise amplitude | +
| SNR | +Signal-to-noise ratio | +dB | +RMSSIGNAL - RMSNOISE | +
| NCROSSINGS | +Number of zero crossings | +None | +Number of times the waveform crosses zero | +
| SWEEPRATE | +Sweep rate | +kHz/ms | +sweep rate of the zero crossings | +
| MEANTIMEZC* | +Zero crossing mean time | +ms | +mean time between zero crossings | +
| MEDIANTIMEZC* | +Zero crossing median time | +ms | +median time between zero crossings | +
| VARIANCETIMEZC | +Zero crossing variance | +ms2 | +variance of the time between zero crossings | +
| ICI | +Inter-click Interval | +seconds | +Time from the end of one click to the start of the next +click | +
*Mean and median zero crossing times +are not used in the current classifier, but still calculated by the +Rocca algorithms. Rocca will ignore these variables during +classification.
+To classify a click, the vector of variables measured from +that click is analysed with the random forest model, which contains +hundreds of classification trees. Each tree in the forest classifies +the click and final classification is based on the species that the +greatest percentage of trees voted for. If the greatest percentage of +tree votes falls below the click threshold (as specified in the ROCCA +Parameters window) +, the click is classified as Ambiguous.
+Table 3 lists the 17 variables calculated based on whistle and +click detections for each encounter (if +specified by the user in the ROCCA parameters +window):
+ +| Variable Code + | +Variable Name | +Units | +Explanation | +
| Encounter_Duration_s | +Encounter duration | +Seconds | +Duration from the start of the first whistle/click to +the end of the last whistle/click | +
| Number_of_whistles | +Number of whistles | +None | +Number of whistles | +
| Whistle_Duration_s | +Whistle duration | +Seconds | +Duration from the start of the first whistle to the end +of the last whistle | +
| Min_Time_Between_Whistle_Detections_s | +Minimum time between whistles | +Seconds | +Minimum time between whistles | +
| Max_Time_Between_Whistle_Detections_s | +Maximum time between whistles | +Seconds | +Maximum time between whistles | +
| Ave_Time_Between_Whistle_Detections_s | +Average time between whistles | +Seconds | +Average time between whistles | +
| Whistle_Detections_per_Second | +Whistles per second | +Counts/s | +The number of whistles / whistle duration | +
| Whistle_Density | +Whistle density | +None | +Sum of the whistle durations / the encounter duration | +
| Ave_Whistle_Overlap | +Average whistle overlap | +None | +Total duration during which whistles overlap / +encounter duration | +
| Number_of_Clicks | +Number of clicks | +None | +Number of clicks | +
| Click_Duration_s | +Click duration | +Seconds | +Duration from start of first click to end of last click | +
| Min_Time_Between_Click_Detections | +Minimum time between clicks | +Seconds | +Minimum time between clicks | +
| Max_Time_Between_Click_Detections | +Maximum time between clicks | +Seconds | +Maximum time between clicks | +
| Ave_Time_Between_Click_Detections | +Average time between clicks | +Seconds | +Average time between clicks | +
| Click_Detections_per_Second | +Clicks per second | +Counts/s | +Sum of the click durations / encounter duration | +
| Ave_Click_Overlap | +Average click overlap | +None | +Total duration during which clicks overlap / encounter +duration | +
| Lat* | +Latitude | +Deg | +Latitude | +
| Long* | +Longitude | +Deg | +Longitude | +
*Latitude and Longitude are not +measured from the whistle and click data, but taken from the GPS source +as specified in the +Rocca Parameters Window Source tab.
+ +Each encounter +number holds a list of possible species based on the +whistle/click classifier models used. There are two values stored for +each species: the number of times a whistle/click has been classified +to that species (displayed), and a cumulative total of all the +percentage tree votes for the species (not displayed). When a new +whistle/click classification is saved to an encounter number, the count +of the classified species is increased by one and the percentage tree +votes for each species are added to the corresponding cumulative totals.
+The encounter is classified in one of two ways:
+If an encounter classifier has been loaded, the vector of +encounter parameters and the random forest probabilities from the +whistle and click classifiers are analysed with the encounter random +forest and the encounter is classified as the species with the highest +percentage of tree votes.
+2. If no encounter classifier has been selected by the +user, the encounter is classified as the species with the highest +cumulative percentage of tree votes. Note that this may be different +than the species most often classified - the value shown in the sidebar +species list. If the highest cumulative percentage of tree votes falls +below the school threshold (as specified in the ROCCA +Parameters window), the detection is classified as Ambiguous.
+Previous: +Contour Extraction / Manipulation
+ ++ From the Whistle Classifier Settings dialog, select "Collect Training Data" and the dialog + will change to show training data parameters in it's lower half. +
+ +
During the collection of training data, whistles will be extracted from raw audio data and +stored in a file, or set of files on your hard drive ready for +Discriminant Function Training at a later date
+ +Although in principle, the classifier can collect training data in real time (i.e. directly from a +sound card connected to a hydrophone in the water, it is far more likely that you will +be training your classifier based on a set of previously recorded sound files which you +have archived over a period of time.
+Sound files should ideally all be recorded at the same sample rate and have the same number +of channels. If possible, organise your sound files so that you have one file folder +per species and all the species folders are sub folders of a master training data folder as shown below.
+
Organising your data in this way is not essential, but it does mean that processing of all files +can take place as a single operation (e.g. over the weekend)
+ +Set up your + +Sound Acquisition module to analyse data from file folders, set the file folder to be the +root directory containing your folders of files by species and check the option to include sub +folders. Do not check the option to merge contiguous files so that processing stops and starts +at the end of each file.
+
If your data have been organised into folders as described above, the classifier can use the +folder names as species names.
+If your data are not organised in the way described above, then you will need to enter the species name +for the training set you are working on (which should of course now be just of a single species).
+ +Training data are stored in files with the ending .wctd (Whistle Classifier Training Data). +One wctd file will be created for each sound file analysed. Use the Browse button to select the folder you +want these files to be stored in.
+ +Run PAMGUARD. All the files in the directory structure of training data will be processed and .wctd files +created in your output folder. The main classifier display will show distributions of whistle fragment parameter +but will not be performing classification.
+There are of course other ways of organising your training data. For instance, if you wish to add new data to +an already existing training set, it is not necessary to reprocess all the data.
+Once you have created your .wctd files, you will need to run the +Discriminant Function Training + before you can use the +classifier on new data
+ +Previous: +Configuring the Whistle Classifier
+Next: +Discriminant Function Training
+ +The Detection / Whistle Classifier menu +has two sub menus: Settings... +and Discriminant +Function Training...
+ +From the settings menu a dialog will appear, the top half of +which will contain a drop down list of data sources and buttons to +select the operation mode.
+ +
Select the data source. This should be the connected regions +output from a Whistle +and Moan detector.
+ +Select either Run Classifier, in which case new detections from +the Whistle +and Moan detector will be fragmented and the fragments sent for +classification, or Collect +Training Data in which case the contours of detected whistles will be +stored for Discriminant Function Training
+ +Previous: +Whistle Classifier Overview
+Next: +Collecting Training Data
+Classifier output is shown graphically on a tab on the +main PAMGUARD display.
+ + +
The top half of the display shows the distributions of parameters extracted from +each whistle fragment (Note that the negative and positive inflections are not currently +used).
+The bottom half of the display shows the classification history.
+Each time the parameter distributions build up enough data and the +classification runs, the classification probability for each possible species with a +probability > 1% (0.01) is displayed
+The time axis of the display is logarithmic, so recent history (i.e. what's happened in the +last minute) gets as much space as the preceding 10 minutes or the 100 minutes before that. A +total of two hours of data are shown.
+ +If a +Database is being used, each classification result is also written to the +database.
+ + +Previous: +Running the Whistle Classifier
+The Whistle Classifier takes detected whistles from the Whistle +and Moan detector and attempts to classify them to species.
+The Whistle classifier does not attempt to classify individual +detected whistles. Instead it collects information on many whistles and +statistically analyses them as a group to determine species.
+The classifier must be trained with a sample of whistles from each +species. While some standard training sets are available through the PAMGUARD +web site, it is highly likely that whistles of a given species will vary between +regions and sub species and may also evolve over time. The Whistle Classifier therefore +allows you to train it using your own samples of whistles from known species.
+ + +From the File>Add modules>Detectors +menu, or from the pop-up menu on the data model display, select "Whistle +Classifier". Enter a descriptive name for the new detector and press OK.
+ +A major problem in the detection of whistles is that of overlapping whistles, or +whistles which have been broken into parts during the detection process.
+
The two spectrograms in the picture show the same spectrogram data. +The lower panel is overlaid with the output of the Whistle and Moan detector. +Clearly some of the quieter whistles have been missed altogether, while +others have been broken into multiple parts.
+The breaking up of whistles into parts can be very dependent on the local noise +conditions and would not therefore be consistent between encounters with a given species. +A classifier requiring complete whistles would therefore be expected to perform +very poorly.
+The PAMGUARD Whistle Classifier therefore works by taking short fragments of whistles +and accumulates statistics over many fragments. Since the level of "natural" fragmentation due +to noise will vary, all detected whistles are first broken into fragments of the same +length prior to classification. While fragmenting whistles in this way is discarding +potentially useful information, it creates an overall improvement in classifier stability
+For each whistle fragment, three parameters are measured:
+The start frequency
The slope
The curvature
Distributions of these three parameters are built up over time, then once sufficient +fragments have been accumulated, the mean, the standard deviation and the skew (lopsidedness) +of each distribution is measured, giving a total of nine parameters which are used +by the statistical classifier, i.e.
+The mean start frequency
The standard deviation of the distribution of start frequencies
The skew of the mean frequency distribution
The mean slope
etc. ...
Gillespie, D., Caillat, M., Gordon, J., and White, P. (2013). Automatic detection and classification of odontocete whistles, +The Journal of the Acoustical Society of America, 134, 24272437.
+Next: +Configuring the Whistle Classifier
+From the +Whistle Classification settings dialog, +select "Run classifier" as the operation mode and the dialog will look something +like the one below.
+ + +
The classifier will take whistles from the data source, break them +into fragments and accumulate fragments until there are the same +number of fragments as were used during training. It will then +classify the data based on the distributions of extracted parameters, +output the classification result, clear +the distributions and start over
+Sometimes, even if there are no real whistles, a few false detections are occurring +from noise. These will gradually accumulate and cause false classifications. You can +set the Classifier to clear the distributions if the whistle rate drops too low using +the parameters in the "When to Classify" section of the dialog.
+ + +There are two ways of setting the classifier training parameters:
+Either they will have been set when you ran the +Discriminant Function Training
+Or you can load a set of training parameters from a Whistle Classifier Settings +(*.wcsd) file provided to you by someone else.
+To load parameters from a .wcsd file, press the 'Select ...' button and navigate to the +file on your hard drive. the parameters will be loaded into your PAMGUARD configuration, +so you will only need to access the file once.
+The remainder of the dialog shows information about how the training was set up (fragment +length, frequency range, etc.). Since these parameters must be identical when you run the classifier +to parameters used when training the classifier, you are unable to change any of these parameters.
+ + +Previous: +Discriminant Function Training
+Next: +Whistle Classifier Output
+Discriminant Function Training is controlled from the Detection +/ Whistle Classifier / Discriminant Function Training ... menu.
+
+
Before running the training algorithms, you must process raw +audio files for each species to create a training data set as described +in the Collecting +Training Data section. Training data will be in the form of a number of +.wctd files containing extracted whistle contours from the Whistle +and Moan detector
+Select the file folder containing your .wctd files. The files can +all be in the same folder or can be split into sub folders, in which case +you should check the "Select Sub folders" option.
+Limit Frequency Search Range - The frequency range to use.
+Contours outside this range will be discarded.
+This is useful if there is low or high frequency noise in the system which you wish
+to exclude from the training process.
You can also require the classifier to only use whistle contours over a certain number of FFT bins long. Again, this can +be useful if there are short bits of noise in the training data sample.
+When the wctd files were created, the species name (either input +by the user of taken from the folder name of the source audio file) was +written into each file. Species names from the .wctd files are used by +default during the classifier training. However, it is possible to +override the species names in the .wctd files by organising you .wctd +files into sub folders with different names and selecting the "Use +folder names as species names" option.
+This allows you to merge data sets which may have been given +slightly different names by different analyst (for instance, different +people may have labelled training data for Bottlenose dolphin as "BND", +"Bottlenose", "TT", "Tursiops", etc. It also allows you to merge species +into groups, for instance, you might have a new "Small dolphin" category +containing data for both common and striped dolphin.
+ +To run the training, set the following parameters:
+Classifier Type - Two discriminant functions are available, + +Linear Discriminant Analysis +and a +Mahalanobis Distances Classifier.
+ +Fragment Length - How long the fragments of whistle fed +into the classifier should be.
+Section length - how many fragments to accumulate before +extracting parameters from the distribution and running a +classification.
+Minimum probability threshold - sets a minimum probability threshold for classification. If the +classifier probability for the best class falls below this threshold, then the whistle section is marked as +unclassified.
+Number of test bootstraps - The number of randomised +trials to run when testing classifier performance
+Batch Testing of Multiple Values - This button will open an additional dialog which allows you to enter a +range of values for the fragment length, section length and probability threshold. The bootstrap is then carried +out for each set of parameters and the output dumped to a text file. Examination of the text file help to decide on +the optimum values for these parameters.
+ +Press the "Start Training" button and wait while the classifier training process runs.
+Progress will be indicated in the bar at the bottom of the window and also as text output in +the right hand display panel.
+ +The training process produces a number of matrices which will control the classification process. +These are automatically stored into the standard PAMGUARD settings file you are currently using.
+You can also export the classifier settings to a Whistle Classifier Settings (*.wcsd) file +for archiving and easy sharing with other users so that they can set up the same classifier +without requiring access to the training data set.
+ +Previous: +Collecting Training Data
+Next: +Running the Whistle Classifier
++These instructions guide a user on how to configure the "3-D" module in PAMGUARD for estimating range and depth of a source using a long-aperture towed array. At the time of this writing the module has only been tested with synthetic WAV files and not real-time input, and only with a Static and Threading Hydrophone Locator. +
+ +At a minimum the 3D Towed Array module requires an upstream Data acquisition module +and a Click Detection module (labeled Sound in and Click Detector in Figure 1). At present the 3D +module is configured to only work with the Click Detector, and not any Ishmael detectors. +A typical array configuration is illustrated in the following figure, which appears under the Hydrophone display. +At present only two pairs of hydrophones (4 phones total) are used in the module.
+
This figure shows the configuration menu for the Audio Data Acquisition module (SoundIn in Figure 1) which +should be configured to select a synthetic wav file. The wav file has 4 channels, with the hydrophone closest +to the tow vessel being assigned the lowest channel number. +
+ +The Click Detection module has many options, but only the following menu needs to be changed +from the default, as shown in the following figure.
+
The "Source" tab arrangement shown here assigns the first two channels to Group 0 +(thus generating a forward subarray bearing) and the last two channels to Group 1, +(generating the rear subarray bearing).
+ + ++The module assumes that the separation between the two pairs of hydrophones in the array is great enough +that an ambiguity may exist as to how to match a particular detection on the rear subarray with candidate +detections on the forward subarray. This ambiguity is more likely when multiple acoustically active animals are present. +In general, the module also assumes that the array elements are deep enough that surface-reflected paths from pulsive +sounds can be cleanly separated in time from the direct paths. The time delay between a direct and surface-reflected path +will be defined as an "echo time" for the rest of this discussion. The echo time of a detection, along with the acoustic +bearing of the detection, provide a set of features that permit identification of the signal between subarrays.
+ +To match the appropriate signals the program builds a queue of detections for each subarray, and assigns an inter-click +interval (ICI) to each detected click. The ICI of a new detection is computed by searching the queue for a detection that +shares a similar bearing and "echo time" to the present detection. One the ICI is assigned, the program can build a +"linked ICI" list that provides the ICI of the N previous detections that share similar features to the current detection. +This ICI list can then be compared to lists on the forward array to locate the corresponding detection on the forward +array.
+ +
This figure shows the settings menu for the 3-D Towed Array module. The Detector source should be set to 'Clicks', +and all four channels selected. The selection parameters are as follows:.
+ +Minimum ICI needed: This parameter N defines the number of ICI to incorporate into a list for cross-array comparison. +In general the larger the number the less likely a mistake will be made in assigning detections between forward and rear +subarrays.
+ +Maximum multipath time: Surface-reflected multipath is flagged by the fact it must arrive only a short time after a +direct path. This number sets the maximum "echo time" that will be assigned by the system. Generally, this should be set +to twice the hydrophone depth divided by the sound speed.
+ +Maximum Queue Time: Sets the amount of time a particular detection will be retained by the subarray queue, to be +available for ICI matching.
+ +ICI estimation: percent angle error: The percent difference between the bearing of a new detection and a candidate +detection must be less than this number, in order to use the candidate detection to assign an ICI to the new detection.
+ +ICI estimation: echo time error: Same as above, except the error percentage is computed for the echo time. If an echo +time is present, then the bearing and echo time are weighted equally in the decision to link two detections together. +If no echo time is present, then only the bearing error is used.
+ +Use cross-correction to refine TOA: The echo times and relative arrival times between subarrays are computed form the +detection times provided by a Detection Data Unit. To achieve more precision the raw data between detections can be +cross-correlated to increase the precision of the estimate of the relative arrival time. At present only the direct-surface +TOA (echo time) feature is enabled.
+ +Generate 3D positions: If not checked, no 2-D or 3-D positions are computed. This is a debug feature to permit the user +to set up all other modules before attempting to localize.
+ +A pull-down menu permits the user to select five different tracking combinations.
+ +Cross bearings: The simplest tracking algorithm simply uses the ICI analysis to generate bearings from the forward and +rear subarray, and thus estimate slant range. This slant range is plotted as a horizontal range on the map.
+ +TOA only, simple TOA estimate: If echo times are available on both subarrays, then a track can be computed without +having to rely on acoustic bearings. This "TOA only" method is advantageous for situations where the sources are +directly ahead or behind the tow vessel, and where the array cable inclination is not measured and cannot be estimated +accurately. The "simple TOA estimate" simply means that a detection on the rear subarray is matched to a detection on the +forward subarray by simply selecting the detections that have the smallest relative arrival times with respect to each other. +For a single animal the "simple TOA estimate" should work more quickly than a full ICI analysis.
+ +TOA and rear bearing, simple TOA estimate: Same as previous, except that the rear subarray bearing, instead of the +forward subarray echo time, is used to compute position. Best used for sources off the beam of the vessel and situations +where the echo time is not available on the forward subarray. Typical situations where this happens include noise masking +from noisy vessels, and shallow hydrophones on the forward subarray.
+ +TOA only: estimate TOA using ICI Same as TOA only option previously discussed, except that ICI patterns are used to +match detections on the subarrays. Should be used when multiple animals are present.
+ +TOA and rear bearing, estimate TOA using ICI: Same as TOA and rear bearing option discussed above, except that that +ICI patterns are used to match detections on the subarrays. Should be used when multiple animals are present.
+ +
Any 3-D tracking method (TOA option in the Tracking method pull-down menu) will generate a Map image similar to that +shown in this figure. The depth of the source is indicated by the size of the circle and by text printed next to the +circle.The "Cross bearing" output is demonstrated in the following figure.
+
This figure shows Spectrogram and radar plot of simulated 3-D sources on PAMGUARD.
+ +
This figure simulated 3D tracking data for multiple animals as it appears in Click Detector view.
+ + + diff --git a/target/classes/help/detectors/Pam3DHelp/docs/images/3DlocalizerSettings.png b/target/classes/help/detectors/Pam3DHelp/docs/images/3DlocalizerSettings.png new file mode 100644 index 00000000..d013fb8d Binary files /dev/null and b/target/classes/help/detectors/Pam3DHelp/docs/images/3DlocalizerSettings.png differ diff --git a/target/classes/help/detectors/Pam3DHelp/docs/images/400mOutput.png b/target/classes/help/detectors/Pam3DHelp/docs/images/400mOutput.png new file mode 100644 index 00000000..42eabace Binary files /dev/null and b/target/classes/help/detectors/Pam3DHelp/docs/images/400mOutput.png differ diff --git a/target/classes/help/detectors/Pam3DHelp/docs/images/ClickDetectorView.png b/target/classes/help/detectors/Pam3DHelp/docs/images/ClickDetectorView.png new file mode 100644 index 00000000..8bab9fd1 Binary files /dev/null and b/target/classes/help/detectors/Pam3DHelp/docs/images/ClickDetectorView.png differ diff --git a/target/classes/help/detectors/Pam3DHelp/docs/images/CrossBearingOutput.png b/target/classes/help/detectors/Pam3DHelp/docs/images/CrossBearingOutput.png new file mode 100644 index 00000000..fa6cb2c5 Binary files /dev/null and b/target/classes/help/detectors/Pam3DHelp/docs/images/CrossBearingOutput.png differ diff --git a/target/classes/help/detectors/Pam3DHelp/docs/images/DetectionParametersSettings.png b/target/classes/help/detectors/Pam3DHelp/docs/images/DetectionParametersSettings.png new file mode 100644 index 00000000..1a34aff0 Binary files /dev/null and b/target/classes/help/detectors/Pam3DHelp/docs/images/DetectionParametersSettings.png differ diff --git a/target/classes/help/detectors/Pam3DHelp/docs/images/HydrophoneArrayConfiguration.png b/target/classes/help/detectors/Pam3DHelp/docs/images/HydrophoneArrayConfiguration.png new file mode 100644 index 00000000..fa182657 Binary files /dev/null and b/target/classes/help/detectors/Pam3DHelp/docs/images/HydrophoneArrayConfiguration.png differ diff --git a/target/classes/help/detectors/Pam3DHelp/docs/images/RadarPlot3D.png b/target/classes/help/detectors/Pam3DHelp/docs/images/RadarPlot3D.png new file mode 100644 index 00000000..dcdeafd0 Binary files /dev/null and b/target/classes/help/detectors/Pam3DHelp/docs/images/RadarPlot3D.png differ diff --git a/target/classes/help/detectors/Pam3DHelp/docs/images/WAVdataSettings.png b/target/classes/help/detectors/Pam3DHelp/docs/images/WAVdataSettings.png new file mode 100644 index 00000000..4a2fc37f Binary files /dev/null and b/target/classes/help/detectors/Pam3DHelp/docs/images/WAVdataSettings.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/DOCS b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/DOCS new file mode 100644 index 00000000..1188f5d5 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/DOCS differ diff --git a/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/DOCS.TAB b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/DOCS.TAB new file mode 100644 index 00000000..5c98d86b --- /dev/null +++ b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/DOCS.TAB @@ -0,0 +1 @@ +eu_u몺0믻 ꪾ껫꾫ꪪ \ No newline at end of file diff --git a/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/OFFSETS b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/OFFSETS new file mode 100644 index 00000000..57e0ac87 --- /dev/null +++ b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/OFFSETS @@ -0,0 +1 @@ +b <͂`0Y5` \ No newline at end of file diff --git a/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/POSITIONS b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/POSITIONS new file mode 100644 index 00000000..b2555629 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/POSITIONS differ diff --git a/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/SCHEMA b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/SCHEMA new file mode 100644 index 00000000..01876f3b --- /dev/null +++ b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/SCHEMA @@ -0,0 +1,2 @@ +JavaSearch 1.0 +TMAP bs=2048 rt=1 fl=-1 id1=455 id2=1 diff --git a/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/TMAP b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/TMAP new file mode 100644 index 00000000..12e8ce70 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/JavaHelpSearch/TMAP differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_MapOptions.html b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_MapOptions.html new file mode 100644 index 00000000..88a7a7a4 --- /dev/null +++ b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_MapOptions.html @@ -0,0 +1,43 @@ + + + +Click detector map options are accessed from the Click Display>Map Options menu.
+ +These apply only to automatically detected click trains.
+ +Click trains may contain varying levels of information. +Short click trains will only have a bearing to the detected source. +Longer trains that alter bearing by more than a few degrees will also have a calculated range.
+ +Sequences of sperm whale clicks from a single source are generally broken up into shorter trains by the click train detection algorithm.
+ +Click trains with range information are always shown. The shorter and more numerous click trains that do not have range information can rapidly clutter the map.
+By selecting the radio buttons the operator can choose to plot either:
+none of the short click trains,
all of the short click trains,
or only those which are separated from other plotted click trains by a minimum time interval or change in bearing.
If no range information is present, the bearing lines on the map are drawn at a fixed length. +
+
+
+Previous: Click +Detector Side Panel
+ + + + diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_MapOverlays.html b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_MapOverlays.html new file mode 100644 index 00000000..b3b45519 --- /dev/null +++ b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_MapOverlays.html @@ -0,0 +1,68 @@ + + +Data can be overlaid on the PAMGuard +map at three different levels: Clicks, Tracked +Clicks and Tracked Events. +Overlaying all clicks will generally display too much data and can slow +PAMGuard down. However this can be useful if the map options are used +to only +display a few seconds of the most recent data. Tracked Clicks and +Tracked +events will be shown if click trains are manually or automatically +detected +(see Click +Train Identification). Event +localisations will start to +show as soon as two or more clicks are marked or sufficient clicks have +been +automatically assigned to a click train for target motion analysis. If +a +localisation has not been calculated, then just a bearing line to the +first +click in the train will be shown.
+
Clicks can be shown as an overlay on +the spectrogram. +They will appear as small triangles at the top +and bottom of the +display.
+
+
The colour of the triangles can be +the colour of the species +id of a single click, the colour assigned to a click train or a mixture +of both +– using the click train colour if one is assigned, otherwise using the +individual click classification. To control the colours, go to Click +Display>Display Overlays and select the option you require.
+
+
Bearing and amplitude of single clicks or bearing and range of +localised click trains can be shown on the radar +display. As with the spectrogram, the colour of individual +clicks can be set from the Click Display > Overlays menu.
+
+
Previous: Click +Detector Side Panel
+ + \ No newline at end of file diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_basicClassification.html b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_basicClassification.html new file mode 100644 index 00000000..3e44e653 --- /dev/null +++ b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_basicClassification.html @@ -0,0 +1,68 @@ + + + +The Basic click +Classifier is the same as the click classifier in the IFAW RainbowClick +software. The basic classifier is generally adequate for the +classification of high frequency harbour porpoise clicks.
+Clicks are classified according to any or all of 4 different tests. +Each test has a check box to the left of its parameters which can +be used to enable or disable particular tests. All +enabled tests must be passed for a positive classification to result.
+ +Test 1. Energy Band comparison
+The summed acoustic energy in two frequency bands (Test band and Control
+band) is compared. The energy in each band must lie in the ranges
+indicated and the ratio between the energy in the test band must exceed
+that in the control band by the specified number of decibels.
Test 2. Peak Frequency position
+The peak frequency must lie within a certain range. The search for the
+peak frequency need not cover the entire spectrum - for instance, if low
+frequency noise is always present, it will make more sense to start the
+search at a higher frequency as shown in the example, where the search
+is between 20kHz and 250kHz, and the peak frequency must lie in the
+range 100kHz to 150kHz.
Test 3. Peak frequency width
+Sets limits on the width of the spectral peak. The width is defined as
+the minimum amount of spectrum required to sum up to the specified
+percentage of the total click energy.
Test 4. Mean frequency
+Sets limits on the mean frequency of the click energy within the
+specified frequency band.
Test 5. Click length
+Sets limits on the length of the click in milliseconds. The length is
+defined as the minimum length of the data required to sum up to the
+specified percentage of the total click energy.
Acoustic Alarm
+Allows user to select the alarm associated with this click type. The alarms shown in the drop-down list are the ones previously defined in the Acoustic Alarm Settings window. The user is also able to specify a maximum amount of elapsed time between detections, to minimize alarming on spurious clicks and focus on specific inter-click intervals. The alarm will not sound on a click detection if the elapsed time since the previous click detection is greater than this number.
+
+
The 'Species Defaults' button allows the user to use stored +standard settings for beaked whale and harbour porpoise classifiers.
+Previous:Click +Classification
+Next: Advanced Click +Classification
+ +The click classifier with frequency sweep was added to +PAMGUARD +in 2010 to provide a wider choice of species identification parameters, +particularly for the detection of beaked whales.
+Operation is similar to that of the Basic click +Classifier in so much that a number of different tests can be +carried +out on each click and the click will have to satisfy all of those tests +in order to be classified.
+
+In the general options section, enter the species name, a +unique +identification code and select the symbol to be used for this species +on +the click detector display.
+Click detection is generally conducted on more than one +channel. +If this is the case, then the click classifier can be set to either:
+Require positive identification on all channels +individually
+Require positive identification on only one channel
+Use mean parameter values over all channels
+Click waveforms from the click detector are generally longer +than the click itself. This is partly due to the pre and post samples +added to the waveform but can also be caused by the click arriving at +different times on different channels. The addition +of extra waveform data before or after the click has little effect if +the click has a high signal to noise ratio, but for quiet clicks, the +additional data is a significant +source of noise for some parameter measurements. There is therefore an +option to restrict the +length of the data used in the parameter extractions. If this option is +used, then the peak of the waveform envelope is found (see Click Length +below) and an equal amount of wave data taken from each side of the +envelope maximum.
+Generally the click length should be set to a power of 2 (e.g. +128, 256, 512, etc) since the FFT's used in many of the calculations +require data that is an exact power of 2 long. Other values can be +used, in which case +the shortened data will be padded with zeros prior to FFT calculations.
+The first tab "Waveform Options" controls classification +parameters relating to the click waveform
+Select this option if you want to filter the click prior to +parameter extraction. Generally measurements such as +the click length will be more accurate if unnecessary noise is first +filtered from the click
+This option can be used to exclude very quiet of loud clicks. +Quiet clicks in particular tend to cause false classification since +their properties are poorly defined so they tend to mis-classify at +random
+The click length is measured by first calculating the analytic +waveform (or signal envelope) of the click using the Hilbert +transform of the waveform data
+This is then smoothed using a moving +average +filter defined by the user (smoothing parameter in dialog).
+The maximum of the smoothed envelope is then found and the +click +length taken as the length of the data between points either side of +that maximum which remain above the maximum value minus the threshold +(Threshold parameter in dialog).
+The test is passed if the click length lies within the range +set +by the user (Length range parameters in dialog).
+Some species of whale produce frequency modulated clicks, i.e. +the click frequency +changes during the course of the click.
+The power spectrum of a click is an +average of the spectral energy over the duration of the click and is +therefore unable +to show changes in frequency during the course of the click.
+Although it is possible to extract more detailed frequency +information using a +Wigner-Ville transform of the waveform data. These are slow +to compute and therefore +not suitable for real time classification.
+The classifier therefore extracts frequency information by +examining zero crossings of the waveform data.
+A zero crossing is defined as the signal waveform going from a +positive to a negative value or vice-versa. The classifier searches the +waveform for zero crossings only within the region of the click between +the thresholded limits from the click length estimation described above.
+Once zero crossings have been found, the frequency between +each zero crossing is calculated. If there are three or more zero +crossings +(permitting two or more estimates of frequency) the frequency sweep is +calculated by fitting +a linear model of frequency against time.
+Two tests can then be applied to the data. The first is the +total number of zero crossings +which must lie within the range set in the dialog. The second is the +frequency sweep +estimated from the zero crossing data.
+The second tab controls classification parameters extracted +from the clicks spectrum
+
+The energy band test compares the acoustic energy in a test +band +with the energy in two control bands.
+The user should enter the frequency ranges of each band and a +threshold value for each of the control bands. The test is passed if +the +test band energy exceeds each of the control band energies by more than +the threshold values.
+If only one control band is required, set both frequency +limits +of the second control band to zero.
+The peak and mean frequency are measured from the power +spectrum +of the click waveform.
+The peak search and the frequencies over which the mean +frequency is summed can be restricted using the search and integration +range parameters in the dialog.
+The power +spectrum can also be smoothed using a moving +average +filter to remove noisy spikes from the spectral data.
+If the peak frequency test is enabled, the peak frequency +(taken as the highest +point in the smoothed spectral data between the limits of the Search +and Integration +range) must lie between the limits entered in the dialog.
+The width of the spectral peak is measured by first finding +the amplitude of the power spectrum at the peak frequency. The peak +width is taken as the frequency range +of the data either side of that peak which are at an amplitude above +the peak amplitude minus +the threshold (threshold parameter in dialog). The test is passed if +the width of the peak lies within the set range.
+The mean frequency is calculated using
+
+where
i is the range of frequency bins within the +search and integration range
+I is the intensity of the spectrum at each +frequency bin i
+f is the frequency (Hz) at each frequency +bin i
+The test is passed if the mean frequency lies within the set +range.
+The third tab controls other options
+
+You can create an audible alarm by setting an alarm on the tab +and by enabling it on the more general classifiction +panel
+The 'Species Defaults' button allows the user to use stored +standard settings for beaked whale and harbour porpoise classifiers.
+Previous: +Basic Click +Classification
+Next: +Tracking and Click +Train Identification
+
+Alarms can be used to provide an audible signal when certain click types +are detected. The Alarm Options dialog allows the user to create, +modify and delete any number of alarms. The Alarm Options dialog can be +opened from the Click Detection>Audible +Alarm menu.
+The alarm can be a predefined 'beep', or a user-selected wav +file.
+Use the Rename button to rename the current alarm (the alarm +visible in the drop-down box). Use the Remove button to delete the +current alarm. Note that there must always be at least one alarm in the +list - in such a case, this button is not selectable. Use the Add +button to create a new alarm.
+This dialog is only used to create a list of available alarms. +Associating a specific alarm with a specific +click type is done in the Individual +Click Classification dialog.
+
+
Previous: +Tracking and Click Train Identification
+Next: +Click Detector Viewer Functions - Overview
+ \ No newline at end of file diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickClassification.html b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickClassification.html new file mode 100644 index 00000000..3cc504d8 --- /dev/null +++ b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickClassification.html @@ -0,0 +1,86 @@ + + +Individual clicks detected by the click detector can be +classified using one of two different click classifiers. The first, Basic click +Classifier is the same as the click classifier in the IFAW +RainbowClick +software. The basic classifier is generally adequate for the +classification of high frequency harbour porpoise clicks and is +primarily retained for backwards compatibility with the RainbowClick +classifier. The second Classifier +With Frequency Sweep uses additional classification +parameters and is +more suitable for the detection of lower frequency odontocete clicks, +particularly those of beaked whales.
+The classifier is set up from the Click +Detection>Click Classification +menu.
+
+Select the type of click classifier you wish to use from the +drop +down list. This will either be the Basic click +Classifier or the Classifier +With Frequency Sweep.
+You must also check the 'Run classification online' +box if you +want clicks to be processed as they are detected.
+You should check the 'Discard unclassified clicks' +box if you +want clicks which do not pass any of the classification criteria to be +discarded. Use this feature with great caution and only +when you are confident that the classifiers are working well for the +clicks that you do want.
+The click classification dialog contains a list of defined +click +types.
+If more than one type is defined, then each click is tested +against each type in sequence and the click is classified as belonging +to the first type with a matching set of classification criteria.
+If the click does not match the criteria of any of the +classifiers, then it is unclassified.
+Use the New, Edit and Delete buttons to add, modify and remove +items from the list.
+If an audible alarm has been associated with this click type, +checking/unchecking the alarm column will enable/disable it. Alarms can +be associated with click types in the Individual Click Classification +dialog (press the Edit button to open the dialog).
+Each click is checked against the different click types in +sequence. As soon as one set of criteria is matched, the classifier +will +stop searching other click types. It is therefore sometimes important +to +arrange the different types in a particular order. Use the Up and Down +buttons to move different click types up and down in the list.
+Individual species classifiers can be enabled or disabled, for +example if you wish to temporarily stop checking for a particular click +type.
+Classified clicks can also be discarded. For example, if there +was a particular noise source causing false triggers of the click +detector (e.g. a depth sounder), it may be possible to set up a +classifier for those detections and immediately discard them.
+If either the New or the Edit button is pressed, the +Individual +Click Classification dialog will be displayed. The behaviour of this +dialog will +depend on the type of classifier selected.
+Previous: Click +Detector Graphic +Overlays
+Next: +Basic Click Classification
+The click detector is used to detect transient signals, + primarily from odontocete species such as sperm whales, beaked whales + and harbour porpoises.
++ From the File>Add modules>Detectors menu, or + from the pop-up menu on the data model display, select 'Click + Detector'. Enter a descriptive name for the new detector (e.g. sperm + whale detector, beaked whale detector, etc) and press Ok. +
++ Go to Click Detection>Detection Parameters + to configure the click detector. +
+
+ + The click detector requires a source of raw data before it can + operate. This may come directly from a Sound + Acquisition module (e.g. a sound card or a National Instruments + board) or from processed data such as the output from a Decimator + or Filter. +
+Select an appropriate input source from the drop down list on + the click detector Detection Parameters menu,
+Use the channel grouping controls to arrange the data channels + into groups.
+Channels in the same group are analysed together so that if one + channel in a group is triggered, all channels in that group are + read-out together to create a detected click.
+The click detector works best if data are analysed in pairs of + channels. It can then use the time delay within each pair to calculate + a bearing. If multiple pairs of hydrophones are used, these bearings + can be crossed to estimate source locations.
+(Click detector output .clk files can also be further analysed + with RainbowClick software if the channels are arranged in pairs).
+If you only have a pair of hydrophones, then select either 'One + group' or 'User groups' and set the group numbers to be the same.
+If you have multiple pairs of hydrophones, select 'User groups' + and arrange the group numbers so that each group contains two channels + as shown above.
+If you select 'no grouping' each channel will be analysed + totally independently. There are currently no PAMGUARD functions which + can re-group these single channel clicks for source localisation.
+ +The data flow through the click detector is shown below
+
+ The filters and trigger decision parameters can all be adjusted + by the user to be optimal for a particular species; and for the + background noise conditions from a particular vessel and operating + area. Setting many of these parameters is an expert procedure and + requires both experience and a thorough understanding of the types of + sound being detected.
+You will see in the figure above that two filters are used; a + digital prefilter and a digital trigger filter. Two filters are + required for the following reason. For optimal detection efficiency, + the trigger only receives data in the frequency band in which the + animal is making sound. However, classifiers that assign clicks to a + particular species will require data from more parts of the spectrum. + For instance, when detecting harbour porpoises which produce narrow + band clicks between 100 and 150kHz, the trigger filter is set to a + band pass filter covering only that frequency range. The pre-filter + however is set to a high pass filter at 20kHz. The clip data therefore + contains data in the spectrum between 20kHz and 250kHz, which is used + by the classifier to distinguish between narrow band porpoise clicks + and broad band clicks from other sources.
++ Both filters can be configured. Go to Click + Detection>Digital pre Filter... or Digital + trigger filter... respectively. Both filters configured using the Filter Design panel. +
+The trigger automatically makes a measure of background noise + and then compares the signal level to the noise level. When the signal + level reaches a certain threshold above the noise level a click clip + is started. When the signal level falls to below the threshold for + more than a set number of bins, the click clip ends and the clip is + sent to the localisation and classification modules.
+ ++ Trigger parameters are set in the Triggers tab of the Click + Detection>Detection Parameters menu: +
+
+
+ Individual channels can be 'turned off' in the trigger by + un-checking the appropriate check boxes. Note however, that if a + deactivated channel is part of a group, that channel will still be + read if another channel in that group triggers. This feature can be + used to reduce false triggers if one channel develops a noise problem. +
++ The noise level N at sample i is measured using +
+
+
+ + and the signal level S is measured using +
+
+
+ + where αN is either the long filter + parameter when no click is active (i.e. the signal is below threshold) + or the Long Filter 2 parameter when the signal is above + threshold. αS is the Short filter + parameter. A click is started / stopped when the ratio S/N goes above + / below the Threshold parameter. +
+
+ The click only ends when all chosen channels have been below + threshold for the number of samples specified by "Min Click + Separation" .
+The maximum length of a click is set such that click clips are + limited to a maximum number of samples.
+When a clip is created, a number of extra samples are added to + the clip before the first and last samples to rise above threshold and + after the last sample to be above threshold (pre sample and post + sample in the dialog).
+TEXT
+
+ 
+
+ TEXT
+
+
+
+ TEXT
+
+ + Next: Click + Detector Displays +
+Data display and an interactive Graphical User Interface are +fundamental to the workings of the click detector. Clicks from many +species are often quite indistinct, especially when detected in noise +and at the limits of detectability. Visually, it is often easy for an +operator to pick out click trains on the display which consist of lines +of regularly spaced clicks on consistent, slowly changing bearings.
+ +The click detector has a bespoke display panel containing a number +of different displays for looking both at click trains and at +individual clicks. It also displays information in the PAMGuard side +panel and can overlay information on the map and other standard +displays.
++
+
Previous: Click +Detector Overview
+ + +
++The side panel displays a running tally of the number of clicks and +click events that have occurred. Also displayed is the name of the +alarm that is currently sounding (or No Alarm Sounding, +as shown above, if there is no alarm at the moment).
+Pressing the Test Alarm button will sound each of the +currently defined alarms, one at a time, with a short pause in between.
++ +
Next: +Click Detector Graphic Overlays
+ \ No newline at end of file diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickStorageOptions.html b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickStorageOptions.html new file mode 100644 index 00000000..03b796e8 --- /dev/null +++ b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickStorageOptions.html @@ -0,0 +1,50 @@ + + + +
Individual clicks may be written to the PAMGUARD database.
+Be warned though that writing to the database can be slow and can seriously +affect overall PAMGUARD performance
++The click detector also stores click data in a format compatible with +the IFAW RainbowClick software. This allows RainbowClick can be used +for offline data analysis. Offline analysis is currently not as well +developed in PAMGUARD as it is in Rainbowclick. +
++For the files to be compatible with RainbowClick, the click detector must be +configured to analyse pairs of channels. +If you have multiple pairs of hydrophones you should use RainbowClick version 4.06.0000 +or higher. +
+To enable RainbowClick compatible file storage check the 'Create RainbowClick File(s)' check box. +
+Use the browse button and edit box to set the output directory for your data. +
+Use the File Initials text field to set a number of characters to be +used at the start of the file name. The remainder of the name is +constructed automatically with the date and time at the start of the +file. +
+To avoid single files becoming too large, use the 'File Length' edit box to set a maximum length for each file. +
+Previous: Tracking and Click +Train Identification
+ + + \ No newline at end of file diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickTabPanelDisplays.html b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickTabPanelDisplays.html new file mode 100644 index 00000000..eaaa591a --- /dev/null +++ b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickTabPanelDisplays.html @@ -0,0 +1,221 @@ + + +The click detector display contains four main sub windows, +although it is possible to have more than one instance of the main +bearing / time display if desired. Two optional displays, IDI Histogram +and Wigner Plot, are also available by selecting Click +Display>Add Display in the toolbar +menu.
+
+
Right clicking on the bearing / time display brings up a +pop-up +menu from which you can configure the display.
+
+Each detected click is shown as a circle or ellipse on the +scrolling display. The display options, available by right clicking on +the display, can be used to select the parameter to display on the +vertical axis: bearing, amplitude or inter-click-interval. Note that +inter-click intervals will only be shown in the automatic click train +identifier is running.
+The example shows 20s of data with three sperm whales +currently +slightly ahead of the hydrophone array.
+The duration of the display may be adjusted using the right +hand +(vertical) slide bar.
+The horizontal slide bar is disabled during data acquisition.
+Click trains identified by eye may be tracked manually.
+To track manually, press the default mouse button anywhere on +the +display. While the mouse is held down, the display will stop scrolling +allowing you to position the mouse above a particular click. Release +the +mouse over a click and that click will be 'tracked'.
+Tracked clicks may be overlaid on the map display and also on +radar type displays.
+If the same operation is performed using the right mouse +button, +then a pop-up menu appears and the operator is asked to assign clicks +to +numbered groups. Clicks within the same tracking group are assumed to +be +from the same source. PAMGUARD then uses a least squares fit to +estimate +the position of the source based on the most likely crossing point of +the bearing lines for each tracked group.
+If a location has been successfully calculated, it can be +displayed on the map and radar displays.
+If the automatic click train identifier is running, clicks +will +be coloured when they are assigned to a click train. As with manual +tracking, PAMGUARD will use a least squares fit to estimate the +position +of the source based on the most likely crossing point of the bearing +lines.
+As with manual tracking, automatic click trains are displayed +on +the map, either as bering lines (when no position has been calculated) +or as a bearing line and point if a position has been calculated.
+The waveform of each click is displayed as it is detected.
+The power spectrum of each click is displayed as it is +detected.
+The trigger window shows the amplitude of the signal on each +channel as a decaying histogram. The vertical red line represents the +trigger threshold set in the detection parameters dialog (cross +reference).
+Level meters for each channel are also shown on the right hand +side of the trigger window.
+Display options for windows on the tab panel are accessed from +the Click Display>Display Settings +menu or by right clicking on the +display.
+
+The axis panel (shown above) shows the same basic three +options +for the vertical axis that can be selected from the pop-up menu. It +also +allows you to select limits for the vertical axis when ICI or Amplitude +are displayed. The number of horizontal grid lines may also be set +(note +that this is stored separately for the three types of vertical axis).
+
+The size at which each click is displayed can also be set. +Clicks +sizes will scale between the lower and upper bounds based on their +amplitude and duration.
+
+If the +click classifier is running it is possible to select which +types of +clicks get displayed.
++
+The IDI (Inter-Detection Interval) Histogram Display provides +a visual interpretation of the inter-detection interval on two +different scales. The display uses a horizontal split-pane to present +the data in both a high-resolution (left pane) and low-resolution +(right pane) format. The relative proportion of the panes can be +changed by dragging the center divider to the right or to the left. +
+The vertical axis is the elapsed time since the acoustic data +collection was started, and is common to the two panes. The units are +minutes. Each row in a pane represents a histogram of data accumulated +over the course of a certain time period (the time bin), +as defined by the IDI Display parameters (see below). In the image +above, the time bin is 1 second. This means a histogram is generated +every second from the IDI data that has been compiled over the last +second, and displayed on the screen.
+Each pane has it's own horizontal axis. Each column represents +a range of IDI values, where the size of the range is defined by the +IDI Display parameters (see below). In the image above, the IDI bin +size is 1 ms for the high-resolution pane and 5 ms for the +low-resolution pane. The highest value bin is 70 ms for the +high-resolution pane and 700 ms for the low-resolution pane. Taking the +low-resolution pane as an example, the first bin would count the number +of inter-dection invertvals that fall between 1 ms and 5 ms, the second +bin would count the number of inter-dection intervals that fall between +6 ms and 10 ms, etc.
+Each row/column combination, therefore, is a cell that +represents the number of inter-detection intervals counted in a +specific IDI range over a specific time period. The color of each cell +represents the magnitude of that count, with black indicating 0 and red +indicating a maximum value as defined by the IDI Display parameters +(see below). In the image above, the maximum counts in the +high-resolution pane is 20 and the maximum counts in the low-resolution +pane is 50.
+When a click is detected, the inter-detection interval is +calculated as the elapsed time since the previous click detection (in +milliseconds). The IDI bin with a range spanning that data point is +determined, and the count within that bin is incremented by one. When +the time bin has elapsed, the counts in each IDI bin are converted to a +color and displayed on the screen as a new row at the bottom of the +pane. Each previous row is moved up by 1 to make room. The row at the +top of the pane is discarded.
+When repositioning/tiling the window or resizing the split +panes, the display may on occasion not update properly. In such a +circumstance, simply adjust the size of the window slightly in order to +force a redraw.
++
The IDI-Display Parameters Dialog can be accessed by +right-clicking on the display window and selecting Plot Options. 3 +parameters can be specified for both the high-resolution and +low-resolution histograms:
+Bin Scale: the size of each bin in the horizontal scale, +in milliseconds
+Max Value: the value of the highest bin in the scale, in +milliseconds. In the above image for the low-resolution histogram, a +bin size of 5 ms and a maximum value of 700 ms means there are (700/5=) +140 bins with ranges 1-5ms, 6-10ms, 11-15ms ... 691-695ms, 696-700ms.
+Max Counts: the highest number of counts in a bin, +corresponding to the color red
+The two time parameters are:
+Bin Scale: the size of each time bin over which the +histogram data is compiled, in seconds
+Max Value: the maximum amount of time shown on the chart, +in minutes. In the above image, 1 minute of data with 1 second bins +means a maximum of 60 histograms displayed at a time.
+The histogram data can also be captured in a csv file, the +name and location of which is specifed by the user. The first column in +each row is the time of the click detection. Each column thereafter +contains the counts found in a histogram bin - first the bins in the +high-resolution histogram, followed by the bins in the low-resolution +histogram. The values in the header row represent the upper limit of +the bins (ie. for bin 1-5ms the header displays a 5, for bin 6-10ms the +header displays a 10, etc).
+The user should use caution when saving data, as the process +is processor-intensive and will slow down other program functions.
++
+
Previous: +Click +Detector Displays
+Next: +Click Detector Side Panel
+
To automatically detect click trains, check the Run Click Train Id.
+ +Click trains are sequences of clicks on a consistent bearing with a consistent inter click interval. This system is currently optimised for sperm whale click train identification. +
+If a click train reaches sufficient length and the bearing change is adequate, target motion analysis is used to automatically calculate a range and bearing to the sound source. +
+Bearings and ranges to click trains can be overlaid on the PAMGuard map. +
Previous: Click Classification
+ + + + diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickTrainLocalization.html b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickTrainLocalization.html new file mode 100644 index 00000000..a0a4a414 --- /dev/null +++ b/target/classes/help/detectors/clickDetectorHelp/docs/ClickDetector_clickTrainLocalization.html @@ -0,0 +1,99 @@ + + +A common method for tracking animals, particularly sperm +whales, is to use Target Motion Analysis + +or TMA. TMA works by measuring bearings to a sound source from multiple +locations along a track-line. The crossing points of the bearings +indicates the location of the tracked sound source.
There are two ways of linking clicks together to form click trains when +using PAMGuard in ‘normal’ mode, i.e. analysing data in real time. On +the click detector bearing time display, clicks assigned to a train are +shown in colour, depending on the options selected from the displays +settings menu.
+
+The most effective method of click train identification is for +the operator to manually select clicks from the click detector bearing +time display which they believe come from the same animal. To track +clicks manually, right click anywhere on the bearing time display, +scrolling will then pause and you can then release the mouse over the +click you wish to mark. A small popup menu will appear with a single +option to create a New Click Train
Wait a while until the angle to that click train has changed and mark +another one in the same way. This time, the menu will have the options +of adding the click to the existing click train, or creating a new +click train.
If you ware tracking multiple animals, then start a New Click Train.
++PAMGuard can attempt to mark Click Trains automatically. To enable +automatic click train identification go to Click Detection > +Click Train Identification
Clicks are associated if there is a regular Inter Click +Interval (ICI) and the clicks are on a slowly and steadily changing +bearing. In the control section set the minimum number of clicks for a +train to be created, the minimum angle for Target Motion Analysis (TMA) +to be run and in the minimum interval between location and database +updates. This last parameter is important since the localisation +calculations can take 100’s of milliseconds, so repeating them every +time a click is added to a click train can cause PAMGuard to run too +slowly.
+ICI changes controls the minimum and maximum allowable ICI and +the change ratio governs how much the ICI can change for a new click to +be added to an existing click train. For example, if the currently +measured ICI is 1.0s and the change ratio is 1.2, then the ICI to the +next click can be anything between 1/1.2 = 0.83s and 1.2s.
+Angle changes is the maximum angular deviation allowed +for the next click. As a click train is starting, this is the angle +difference between clicks. Once a train has enough clicks for a +localisation, it’s the angle off from that localisation point.
+
If you make a mistake tracking manually or if you think the +automatic train identification has made a mistake, click on the click +that’s been assigned incorrectly and a slightly different menu appears +giving four options.
+
+It is very common for the automatic click train identification +algorithm to break up an obvious click train into many smaller ones. +This happened when there are pauses or changes in click rate. +Reassigning all clicks in a train is a handy way of correcting these +errors in order to generate long click trains which will yield accurate +localisations.
+
Click train information is written to the PAMGuard database using +the same database tables used for offline data analysis. This means +that any event marking which took place in real time will be available +for further offline analysis. Two database tables are used: The “events +table” contains one record of information per click train, the second +“clicks table” contains a record for each click in each event. To +maintain compatibility with earlier versions, the two database tables +are called Click_Detector_OfflineEvents and +Click_Detector_OfflineClicks (the name Click_Detector_ in these table +names will change to whatever the name of the click detector created in +the PAMGuard configuration you are using and if you have multiple click +detectors, multiple tables with different names will be created.)
+Previous: Advanced Click Classification
+ + \ No newline at end of file diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/AmplNotSet.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/AmplNotSet.png new file mode 100644 index 00000000..77096485 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/AmplNotSet.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/AmplitudeFilter.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/AmplitudeFilter.png new file mode 100644 index 00000000..7dca2832 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/AmplitudeFilter.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/BasicClickType.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/BasicClickType.png new file mode 100644 index 00000000..0feeff50 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/BasicClickType.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/BetterClickType.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/BetterClickType.png new file mode 100644 index 00000000..6be6f78a Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/BetterClickType.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/Binary.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/Binary.png new file mode 100644 index 00000000..f7fe0314 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/Binary.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/BinaryDataMapping.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/BinaryDataMapping.png new file mode 100644 index 00000000..53e91b38 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/BinaryDataMapping.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDelay.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDelay.png new file mode 100644 index 00000000..70875c16 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDelay.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDisplayParameters1.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDisplayParameters1.png new file mode 100644 index 00000000..458a4741 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDisplayParameters1.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDisplayParameters2.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDisplayParameters2.png new file mode 100644 index 00000000..09637cd1 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDisplayParameters2.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDisplayParameters3.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDisplayParameters3.png new file mode 100644 index 00000000..72288bb9 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickDisplayParameters3.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickMapOptions.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickMapOptions.png new file mode 100644 index 00000000..78231dc9 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickMapOptions.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickOnRadar.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickOnRadar.png new file mode 100644 index 00000000..bde8ca78 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickOnRadar.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickOverlayOptions.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickOverlayOptions.png new file mode 100644 index 00000000..f5e78735 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickOverlayOptions.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickProcessing.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickProcessing.png new file mode 100644 index 00000000..9295ca47 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickProcessing.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTrain.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTrain.png new file mode 100644 index 00000000..ac43839e Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTrain.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTrainId.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTrainId.png new file mode 100644 index 00000000..d173c2e9 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTrainId.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickType.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickType.png new file mode 100644 index 00000000..76ad9a93 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickType.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTypeWithAlarm.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTypeWithAlarm.png new file mode 100644 index 00000000..1b7e5b79 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTypeWithAlarm.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTypes.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTypes.png new file mode 100644 index 00000000..d648a1ae Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTypes.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTypesWithAlarm.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTypesWithAlarm.png new file mode 100644 index 00000000..9a3714a2 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClickTypesWithAlarm.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ClicksOnSpectrogram.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClicksOnSpectrogram.png new file mode 100644 index 00000000..3be75e21 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ClicksOnSpectrogram.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ConvertingRainbowClickFiles.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ConvertingRainbowClickFiles.png new file mode 100644 index 00000000..24c0bbde Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ConvertingRainbowClickFiles.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/CreateNewEvent.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/CreateNewEvent.png new file mode 100644 index 00000000..0034e614 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/CreateNewEvent.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/DataFlow.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/DataFlow.png new file mode 100644 index 00000000..6cd41bf1 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/DataFlow.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/DetectionParameters-length.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/DetectionParameters-length.png new file mode 100644 index 00000000..c009c758 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/DetectionParameters-length.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/DetectionParameters-trigger.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/DetectionParameters-trigger.png new file mode 100644 index 00000000..ed0d0f14 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/DetectionParameters-trigger.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/EchoDetection.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/EchoDetection.png new file mode 100644 index 00000000..9cf59442 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/EchoDetection.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/EventList.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/EventList.png new file mode 100644 index 00000000..00b9da85 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/EventList.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/Events.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/Events.png new file mode 100644 index 00000000..e7e32c8f Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/Events.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/Events_1.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/Events_1.png new file mode 100644 index 00000000..80539e28 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/Events_1.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/FFT_filtersettings.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/FFT_filtersettings.png new file mode 100644 index 00000000..bc227c0c Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/FFT_filtersettings.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/GPStable.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/GPStable.png new file mode 100644 index 00000000..77a52519 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/GPStable.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/IDI-Display.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/IDI-Display.png new file mode 100644 index 00000000..b899550b Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/IDI-Display.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/IDI_params.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/IDI_params.png new file mode 100644 index 00000000..2bfb66d1 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/IDI_params.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/LabelClick_1.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/LabelClick_1.png new file mode 100644 index 00000000..a7d06c3a Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/LabelClick_1.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/LabelMultipleClicks.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/LabelMultipleClicks.png new file mode 100644 index 00000000..27479117 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/LabelMultipleClicks.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/LocaliseanMap.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/LocaliseanMap.png new file mode 100644 index 00000000..97f4a45c Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/LocaliseanMap.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/Lookup.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/Lookup.png new file mode 100644 index 00000000..af102074 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/Lookup.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/MapClickEvents.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/MapClickEvents.png new file mode 100644 index 00000000..e9633646 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/MapClickEvents.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkClick1.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkClick1.png new file mode 100644 index 00000000..2ef81d54 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkClick1.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkClick2.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkClick2.png new file mode 100644 index 00000000..29c2ceda Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkClick2.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkClickCorrect2.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkClickCorrect2.png new file mode 100644 index 00000000..7e9e74a5 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkClickCorrect2.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkingAnEvent.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkingAnEvent.png new file mode 100644 index 00000000..37eaed7b Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkingAnEvent.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkingAnEvent_1.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkingAnEvent_1.png new file mode 100644 index 00000000..87c094c9 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/MarkingAnEvent_1.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/MeanFrequency.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/MeanFrequency.png new file mode 100644 index 00000000..2a9ba591 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/MeanFrequency.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/NoDatabaseMessage.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/NoDatabaseMessage.png new file mode 100644 index 00000000..0e3ad33b Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/NoDatabaseMessage.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/NoSettingsBegin.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/NoSettingsBegin.png new file mode 100644 index 00000000..6ff7e9b5 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/NoSettingsBegin.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/RCDisplay.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/RCDisplay.png new file mode 100644 index 00000000..ed15edce Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/RCDisplay.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/RCDisplayWithSperm.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/RCDisplayWithSperm.png new file mode 100644 index 00000000..38b9b268 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/RCDisplayWithSperm.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/RCDisplayWithSperm2.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/RCDisplayWithSperm2.png new file mode 100644 index 00000000..15dfc961 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/RCDisplayWithSperm2.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/Reanalyse.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/Reanalyse.png new file mode 100644 index 00000000..680e2edc Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/Reanalyse.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/Settings Loaded.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/Settings Loaded.png new file mode 100644 index 00000000..8a742f24 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/Settings Loaded.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ShowAmplitudeFilter.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ShowAmplitudeFilter.png new file mode 100644 index 00000000..248379f6 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ShowAmplitudeFilter.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ShowEvents.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ShowEvents.png new file mode 100644 index 00000000..be227da8 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ShowEvents.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/ShowEvents2.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/ShowEvents2.png new file mode 100644 index 00000000..8138ec0f Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/ShowEvents2.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/Show_data_count.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/Show_data_count.png new file mode 100644 index 00000000..0de530bc Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/Show_data_count.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/Show_datagram.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/Show_datagram.png new file mode 100644 index 00000000..76e5d5d6 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/Show_datagram.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/SquareSelectionTool.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/SquareSelectionTool.png new file mode 100644 index 00000000..5a6465a1 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/SquareSelectionTool.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifier2016.PNG b/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifier2016.PNG new file mode 100644 index 00000000..be0c568c Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifier2016.PNG differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifierTab1.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifierTab1.png new file mode 100644 index 00000000..3d518fe2 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifierTab1.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifierTab2.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifierTab2.png new file mode 100644 index 00000000..23643df1 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifierTab2.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifierTab3.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifierTab3.png new file mode 100644 index 00000000..9107a32f Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/SweepClassifierTab3.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/Thumbs.db b/target/classes/help/detectors/clickDetectorHelp/docs/images/Thumbs.db new file mode 100644 index 00000000..1cf8170b Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/Thumbs.db differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/alarm_options.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/alarm_options.png new file mode 100644 index 00000000..ae9969bc Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/alarm_options.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/clickStorage.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/clickStorage.png new file mode 100644 index 00000000..477e861e Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/clickStorage.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/database.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/database.png new file mode 100644 index 00000000..8ab371b2 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/database.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_delays.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_delays.png new file mode 100644 index 00000000..c4c18b73 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_delays.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_echoes.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_echoes.png new file mode 100644 index 00000000..6206730d Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_echoes.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_noise.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_noise.png new file mode 100644 index 00000000..0108bcb2 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_noise.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_source.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_source.png new file mode 100644 index 00000000..bb3243f1 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/detection_parameters_source.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/noiseLevelEquation.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/noiseLevelEquation.png new file mode 100644 index 00000000..1187404f Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/noiseLevelEquation.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/sendToRocca.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/sendToRocca.png new file mode 100644 index 00000000..ab377a69 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/sendToRocca.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/sidepanel_no_alarm.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/sidepanel_no_alarm.png new file mode 100644 index 00000000..2dc7c93e Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/sidepanel_no_alarm.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/signalLevelEquation.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/signalLevelEquation.png new file mode 100644 index 00000000..f52e9511 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/signalLevelEquation.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/images/toolbar_selection.png b/target/classes/help/detectors/clickDetectorHelp/docs/images/toolbar_selection.png new file mode 100644 index 00000000..777ae229 Binary files /dev/null and b/target/classes/help/detectors/clickDetectorHelp/docs/images/toolbar_selection.png differ diff --git a/target/classes/help/detectors/clickDetectorHelp/docs/offline_AddingGPSData.html b/target/classes/help/detectors/clickDetectorHelp/docs/offline_AddingGPSData.html new file mode 100644 index 00000000..08e39c4e --- /dev/null +++ b/target/classes/help/detectors/clickDetectorHelp/docs/offline_AddingGPSData.html @@ -0,0 +1,40 @@ + + + +
+The gpsData table in PamGuard has a specific format which must be copied for offline analysis.
+
+
+UTC
+UTCMilliseconds
+PCLocalTime
+GpsDate
+PCTime
+GPSTime
+Latitude
+Longitude
+SpeedType
+Heading
+HeadingType
+TrueHeading
+MagneticHeading
+MagneticVariation
+GPSError
+DataStatus
You have to add or imprt the gpsData table into your database for the offline analysis. If you followed the steps described in creating binaries offline, +you still need to add the GPS processing module File>Add module...>Maps and Mapping>GPS processing first time you open up Pamguard Viewer. +Also if you want to have a map you also need to add the module File>Add module...>Maps and Mapping>Map. You need to close Pamguard Viewer after you added these modules, and open it up again so it can load the GPS data.
+If you've used Rainbow Click or older versions of Pamguard you +may have click data saved in .clk files. +Pamguard requires binary files to display click data in the viewer mode +however has the functionality to batch convert .clk files to binary +format.
+Select Click Detection > Batch +Convert .clk to .pgdf files. This will bring +up the following window.
+
+Select the location of your .clk files and the location you +want to save the new Binary file to, then click 'Start'.
+Previous: Click Viewer Overview
+ +
+The Pamguard viewer click detector has the ability to allow manual
+marking of events. Events usually consist of a group of clicks
+associated with one acoustic encounter of a particular species. Event
+information is saved to the database and in certain situations, such as
+when using towed arrays, can be used to localise an animals position.
+
+Creating an Event
+
+
+To mark an event bring up the bearing/amplitude time display (in the
+Click Detector tab). The Figure shows a porpoise click train which
+needs to be marked and stored as an event. Note that the bearing time
+display is very similar to the online version
+just that instead of the trigger window you get a Wigner
+plot as default setting.
+
+
To see the classified clicks better (in this case porpoise +clicks - the red triangles) you can untick the box at the top of the +window 'Unclassified clicks'. +The bearing time display will now only show the classified clicks +(depending on your settings you have more options i.e. echos, other +species, etc.). Right click on a click and select 'Label +click...'.
+
This will bring up the event dialogue box. Here you can create +a new event by selecting the 'New Event' button or +add the click to an existing event by selecting any event from the +Event list.
+
When creating a new event the species/event type can be +selected from the drop down menu. To add a new species/event type to +the database simply right click on the drop down menu and select 'Edit +list'.
+
In the Lookup Editor window select 'Add Item' +and create a Code, Text and Symbol for your new species/event type. +Press ok. +Now you can select your new Event type/species from the drop down list +in the click event dialogue (previous figure). +The Estimated number of animals and the comment are optional but always +useful to fill in. (Note: Dont worry about the event number, Pamguard +creates an ID automatically.)
+
Multiple clicks can be selected using the advanced area +selection tool. Double click on the bearing/amplitude time display. +This will bring up a dotted line which you can use to draw around a +group of clicks. By joining up the ends of the dotted line the selected +area should appear grey.
+
All the clicks within this grey area can be added to an event +by right clicking inside the grey area and selecting 'Label +Clicks' or use the key short cut 'Ctrl+L'. +Note that there are also other options available such as removing +clicks from a certain event etc. So if you made a mistake, dont +panick. +Other useful tools for marking an event include the amplitude +selector and +zoom +selection.
+
Following the described steps your event is saved. You can now
+localise it with target
+motion analysis.
+
+
+All events are saved in the database. To get an overview about your
+events go to 'Click Detection' and then 'Show
+events'.
Depending on your selection you see all events in your data +set or only the ones which are in the current period. Right click on an +event and you have the option for editing, deleting or going to the +event. +This comes in handy when you want to move between events.
+
Events which contain clicks with bearing information can be +viewed in the map tab- simply right click and select 'Click +Detector, Tracked Clicks'. +If using a towed array events can be localised using the target +motion analysis module. +Localisation information will also be displayed on the map.
+
You can also send Events to Rocca +for click analysis. Go to 'Click Detection' and +then 'Rocca Measurement'. +A new window will open up displaying all of the currently defined +events. Select the events to analyse, and then click 'Analyze +Selection'
+
Previous: Navigating through Data
+ +The Pamguard viewer mode allows navigation through large data +sets. The data +map can be used to look at large volumes of data over long +periods of time. Possible areas of interest can be found by using the +datagram and click counter in the appropiate data density graphs (i.e. +click detector-clicks). You can switch between the views by right +clicking on the display.
+
If an area of interest is found right click on the data map
+and select 'center data here' or 'start
+data here'. This will load the clicks at this time into the
+bearing time display. Here individual clicks can be selected, viewed
+and added to an
+event.
+
+See Viewer
+Overview for more details on bearing time display navigation.
Previous: +Importing Rainbow Click Files
+ +An offline analysis functionality, which is similar to that +in the IFAW RainbowClick software, +is available in PAMGUARD. To use this functionality, click detector +data must be available +in the binary +storage format and PAMGUARD must be running in Viewer +Mode.
+The click detector viewer mode provides several powerful tools +for data analysis: +
+The data map +allows for rapid navigation and visualisation of large data sets.
+Events can be manually +marked and saved to a database.
+Data collected using towed arrays can be localised using target +motion analysis.
+
+To begin using the offline click viewer you must have a set of binary
+files and a database.
+If this is NOT the case, you have to create
+binaries offline (i.e. after you have collected you data in
+the field).
+Ideally the database will have been created whilst collecting data. It
+should then contain GPS co-ordinates, a list of the binary files,
+settings information etc.
+When you open up PamguardViewer the first option is to select the
+database.
+
+
By selecting this database, viewer will load automatically the +corresponding binary-, settings- and data files but sometimes it gets +the directory path wrong (especially if your data is on an external +hard drive and you plugged it in and out frequently). +Just double check if the binary storage options are correct (Note: In +this case the drive is wrong).
+
The programme will then load the data and create the data map +which can take a couple of minutes if you are opening up the data for +the first time. +Use the data map for navigation. +Now you start to manually +mark events.
+
If no database is available then a a new one must be created. +Open Pamguard viewer and select a blank database. A message will appear.
+
Select 'OK'. A dialogue asking you to +select binary files will then appear. Select the path to your processed +binary files and click 'OK'. The following window should then appear. +(Note that your binary files must contain .psfx files. +These should be automatically created when binary files are created.)
+
Right click on the small red triangle and select 'load +settings from....'. Clicks should then be loaded from the +binary files and a datamap created.
+
Selecting the Click Detector tab should bring up the clicks
+contained in the binary files. If GPS data needs to be added a new
+table must be manually created in the database. The table must be named
+
+''gpsData' and should be in a specific format (Adding
+GPS Data offline).
+
+
+
+
+Next: Importing Rainbow Click files
+Sometimes your initial click parameter settings need changing. There is an option in Viewer to reanalyse click types which will change the corresponding binary files. +Go to Click Detection>Reanalyse click types....
+ +
+The click reprocessing window will open giving you various options to proceed. First you need to decide which data you would like to reclassify. +The options are: Loaded data, all data or new data. To reprocess all data is time consuming so if you try out different parameter settings use the option of loaded data as it is much quicker. +Once you are content with your new settings you can apply it to the whole data set.
+In the case of offline tasks which change database entries (not all do), checking the Delete old database entries checkbox will ensure old entries are deleted and duplicates are not made.
+
+This brings you to the click classification. +Here you can change either the click parameters or add a new classification.
+ +This opens the Echo Detection window. Here you can change the parameters for echo classification. MORE JAMIE?
+
+This opens the delay measurement window. Here you can alter the setting of how click delays are calculated.
+
+
+
+
+
+You can choose either of the two options, both or none.
+
+
Option 1: Filter data before measurement
+
This option has the following settings:
+
+
+
+
+Option 2: Use wave form envelope. EXPLAIN??
+MORE JAMIE.
This option allows zou to recalculate click bearings. JAMIE MORE.
+
+
You can run all 4 reclassification options at once or tick the ones which are suitable for the analysis. Press 'Start' to beginn the recalculation process.
+You can see how far advanced the recaclulation process is in the progress bar. During re-processing the cancel button will change to a 'Stop' button and when the process is finished it will change to a 'Close' button.
+When recalculating large data sets the Close button might not appear after the last file. Just press Stop instead.
Sometimes your initial click parameter settings need changing.
+There is an option in Viewer to reclassify click types which will
+change the corresponding binary files.
+Go to 'Click Detection' and click 'Reanalyse
+click types'.
+
+
+
+
+
+The click reprocessing window will open giving you various options to
+proceed. First you need to decide which data you would like to
+reclassify.
+The options are: Loaded data, all data or new data. To reprocess all
+data is time consuming so if you try out different parameter settings
+use the option of loaded data as it is much quicker.
+Once you are content with your new settings you can apply it to the
+whole data set. JAMIE: WHAT DOES the DELETE OLD DATABASE ENTRIES DO?
+
+
+
+
+
+The parameters you can change are:
+
This brings you to the click +classification. +Here you can change either the click parameters or add a new +classification.
+This opens the Echo Detection window. Here you can change the +parameters for echo classification.
+
+This opens the delay measurement window. Here you can alter
+the setting of how click delays are calculated.
+
+
+
+
+
+You can choose either of the two options, both or none.
+
+Option 1: Filter data before measurement
+
+This option has the following settings:
+
+
+
+
+
+Option 2: Use wave form envelope. This takes the
+Hilbert Transform of the wave and uses this to calculate time delays
+instead of the true waveform. This is useful for spectraly pure signals
+which have characteristic wave envelopes, such as Harbour Porpoise
+clicks.
This option allows you to recalculate click bearings. These
+may have changed due to altering the spacing between hydrophone
+elements or perhaps you have recalculated the click delays, hence the
+bearings will have changed.
+
+
+You can run all 4 reclassification options at once or tick the ones
+which are suitable for the analysis. Press 'Start'
+to beginn the recalculation process.
+You can see how far advanced the recaclulation process is in the
+progress bar. During re-processing the cancel button will change to a 'Stop'
+button and when the process is finished it will change to a 'Close'
+button.
+When recalculating large data sets the Close button might not appear
+after the last file. Just press Stop instead.
Next: Offline Click Analysis Tools
+
+There are a few tools which are useful whilst marking
+an event or
+working with the click detector in Viewer
+Mode.
+
+The amplitude selector is effectivly a filter. It will only show you
+the clicks after a certain decibel threshold. This becomes useful if
+your data shows extensive background noise.
+
+
+
You can also enhance a click event by applying the amplitude +selector as it makes the click train usually cleaner, which will +improve Target +Motion Analysis. The amplitude selector can be activated by a +right click on the bearing time display selecting 'Show +amplitude selector'.
+
A window for the amplitude selector will open showing an +amplitude histogram and some descriptive statistics from the loaded +data. The default setting for minimum amplitude is set to zero. Go to +the field and put a sensible number in judging by the histogram and +tick the box 'Display only clicks of set amplitude'. +A red line appears in the histogram which you can drag with the mouse +which changes the amplitude threshold. The clicks shown in the bearing +time display change accordingly. +When the amplitude selector is active a message appears at the bottom +of the bearing time display which reads how many clicks are not +displayed and the amplitude threshold currently set.
+
There are different ways to zoom. A simple rectangular area of +clicks can be selected by clicking on the bearing time display and +dragging the mouse. A black square will apear which you can zoom into +with a double click.
+
You can also use the advanced area selection tool (the one
+where it gets grey) for more complex click sections. Same principle
+applies. Alternatively to the double click to zoom you can also right
+click and select 'Zoom in'.
+Right click and select 'Zoom right out' to return
+to the full click display.
+
+
+
Previous: +Reclassifying Clicks
+ ++ Before creating a GPL module, you will need a + Sound + Acquisition module and an FFT + (Spectrogram) Engine. If these do not already exist you will be + prompted to create them when you add the GPL Module. In the File Menu, + go to Detectors / Generalised Power Law Detector and the module will + be added to your PAMGuard configuration. +
+Note that the GPL detector is most useful for the detection of low frequency baleen whale sounds. If your raw + data are + high frequency, then consider adding a Decimator + module between the Sound Acquisition and FFT modules to + lower the frequency of the data.
+ +Open the GPL detector dialog from the main Settings menu and select the FFT data source and indicate which + channels + you want the detector to operate on. The detector will operate independently on each selected channel.
+Note the frequency and time resolutions of the FFT data which are displayed in the dialog. If these are not + suitable, then + make adjustments in the FFT module before returning to the GPL configuration.
+ +
The GPL detector uses advanced signal processing methods to estimate a median background noise which is then subtracted + from the data. The Whitening Time Period is the time over which this background is measured. + When processing starts, it can take up to two of these whitening periods for the initial background measurement to + stabilise. For this reason, data are often processed in blocks, so the software can scan back and forth within the same + block of data to make the background measurement, then search for detections.
+ +
Blocked Processing
+ In this mode, data are read in in blocks of the length of the whitening period, the background is measured on that block
+ of data, and then detections made within the same block. This works well for offline processing of duty cycled recordings.
+ However, when processing data in real time, no detections will be visible to the user until the end of each block, and the
+ detections may scroll off the screen before you've had a chance to look at them!
Block First
+ In this mode, the first block of data is processed exactly as for Blocked Processing. After that, the system then
+ switches to continuous processing, where the background is continually updated based on the data within the preceding
+ whitening period. After the initial block, this provides smoother displays than Blocked Processing. Output should be
+ very similar, however the background measurement at a moment in time will be slightly different, so results may vary slightly.
+ This mode could be used either for real time processing or for offline processing of recorded data.
Block First
+ In this mode, there is no blocking of data and all background assessments are made on preceding data. This mode is therefore NOT
+ suitable for offline processing of recordings, since detection will not be possible within the first two whitening time periods of
+ each file. However, for long term real time monitoring, if you're not too fussed about the first minutes of data, it would be
+ possible to use this processing mode.