Click Train Detector Help

This commit is contained in:
Douglas Gillespie 2022-09-21 08:57:19 +01:00
parent f34dc08a90
commit 3a2f4912e9
13 changed files with 123 additions and 93 deletions

View File

@ -146,6 +146,11 @@ public class ClickTrainControl extends PamControlledUnit implements PamSettings
* Click info manager- handles information from the algorithms. * Click info manager- handles information from the algorithms.
*/ */
private CTAlgorithmInfoManager clAlgorithmInfoManager; private CTAlgorithmInfoManager clAlgorithmInfoManager;
/**
* Help point which can be referenced form dialogs, etc.
*/
public static final String helpPoint = "detectors.ClickTrainDetector.docs.ClickTrainDetector";
/** /**
* Constructor for the ClickTrainControl. * Constructor for the ClickTrainControl.

View File

@ -587,6 +587,11 @@ public class ClickTrainAlgorithmPaneFX extends SettingsPane<ClickTrainParams> {
public void paneInitialized() { public void paneInitialized() {
} }
@Override
public String getHelpPoint() {
return ClickTrainControl.helpPoint;
}
} }

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

View File

@ -1,2 +1,2 @@
JavaSearch 1.0 JavaSearch 1.0
TMAP bs=2048 rt=1 fl=-1 id1=6559 id2=1 TMAP bs=2048 rt=1 fl=-1 id1=6661 id2=1

Binary file not shown.

View File

@ -442,6 +442,8 @@
<mapID target="localisation.bearingLocaliser.docs.BL_Settings" url="localisation/bearingLocaliser/docs/BL_Settings.html"/> <mapID target="localisation.bearingLocaliser.docs.BL_Settings" url="localisation/bearingLocaliser/docs/BL_Settings.html"/>
<mapID target="detectors.ClickTrainDetector.docs.ClickTrainDetector" url="detectors/ClickTrainDetector/docs/ClickTrainDetector.html"/>
<mapID target="sound_processing.FiltersHelp.Docs.Filters_filters" url="sound_processing/FiltersHelp/Docs/Filters_filters.html"/> <mapID target="sound_processing.FiltersHelp.Docs.Filters_filters" url="sound_processing/FiltersHelp/Docs/Filters_filters.html"/>
<mapID target="localisation.bearingLocaliser.docs.BL_Output" url="localisation/bearingLocaliser/docs/BL_Output.html"/> <mapID target="localisation.bearingLocaliser.docs.BL_Output" url="localisation/bearingLocaliser/docs/BL_Output.html"/>

View File

@ -1,7 +1,8 @@
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!--generated by JHelpDev Version: 0.63, 14 May 2008, see jhelpdev.sourceforge.net--><!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN" "http://java.sun.com/products/javahelp/helpset_2_0.dtd"> <!--generated by JHelpDev Version: 0.63, 14 May 2008, see jhelpdev.sourceforge.net--><!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN" "http://java.sun.com/products/javahelp/helpset_2_0.dtd">
<helpset version="1.0"> <helpset version="1.0">
@ -17,7 +18,8 @@
<title>Help </title> <title>Help </title>
@ -33,7 +35,8 @@
<maps> <maps>
@ -51,7 +54,8 @@
<homeID> <homeID>
top top
</homeID> </homeID>
@ -67,7 +71,8 @@ top
<mapref location="Map.jhm"/> <mapref location="Map.jhm"/>
@ -83,7 +88,8 @@ top
</maps> </maps>
@ -99,7 +105,8 @@ top
<view mergetype="javax.help.UniteAppendMerge"> <view mergetype="javax.help.UniteAppendMerge">
@ -117,7 +124,8 @@ top
<name> <name>
TOC TOC
</name> </name>
@ -135,7 +143,8 @@ TOC
<label> <label>
TOC TOC
</label> </label>
@ -153,7 +162,8 @@ TOC
<type> <type>
javax.help.TOCView javax.help.TOCView
</type> </type>
@ -171,7 +181,8 @@ javax.help.TOCView
<data> <data>
PAMGUARDTOC.xml PAMGUARDTOC.xml
</data> </data>
@ -187,7 +198,8 @@ PAMGUARDTOC.xml
</view> </view>
@ -203,7 +215,8 @@ PAMGUARDTOC.xml
<view> <view>
@ -221,7 +234,8 @@ PAMGUARDTOC.xml
<name> <name>
Index Index
</name> </name>
@ -239,7 +253,8 @@ Index
<label> <label>
Index Index
</label> </label>
@ -257,7 +272,8 @@ Index
<type> <type>
javax.help.IndexView javax.help.IndexView
</type> </type>
@ -275,7 +291,8 @@ javax.help.IndexView
<data> <data>
PAMGUARDIndex.xml PAMGUARDIndex.xml
</data> </data>
@ -291,7 +308,8 @@ PAMGUARDIndex.xml
</view> </view>
@ -307,7 +325,8 @@ PAMGUARDIndex.xml
<view> <view>
@ -325,7 +344,8 @@ PAMGUARDIndex.xml
<name> <name>
Search Search
</name> </name>
@ -343,7 +363,8 @@ Search
<label> <label>
Search Search
</label> </label>
@ -361,7 +382,8 @@ Search
<type> <type>
javax.help.SearchView javax.help.SearchView
</type> </type>
@ -379,7 +401,8 @@ javax.help.SearchView
<data engine="com.sun.java.help.search.DefaultSearchEngine"> <data engine="com.sun.java.help.search.DefaultSearchEngine">
JavaHelpSearch JavaHelpSearch
</data> </data>
@ -395,7 +418,8 @@ JavaHelpSearch
</view> </view>

View File

@ -6,7 +6,7 @@
<project> <project>
PAMGUARD PAMGUARD
</project> </project>
<projectdir>C:\PamguardCode2021\PamGuard NOAA2\src\help</projectdir> <projectdir>C:\Users\dg50\source\repos\PAMGuardDG\src\help</projectdir>
<startpage> <startpage>
index.html index.html
</startpage> </startpage>

View File

@ -481,6 +481,10 @@
<tocitem text="Localisation " target="detectors.gpl.docs.localisation" image="topic"/> <tocitem text="Localisation " target="detectors.gpl.docs.localisation" image="topic"/>
</tocitem> </tocitem>
<tocitem text="Click Train Detector " target="detectors.ClickTrainDetector.docs.ClickTrainDetector">
<tocitem text="Overview " target="detectors.ClickTrainDetector.docs.ClickTrainDetector" image="topic"/>
</tocitem>
</tocitem> </tocitem>
<tocitem text="Classifiers "> <tocitem text="Classifiers ">
<tocitem text="Whistle Classifier "> <tocitem text="Whistle Classifier ">

View File

@ -6,7 +6,6 @@
</head> </head>
<body> <body>
<h1 id="click-train-detector">Click Train Detector</h1> <h1 id="click-train-detector">Click Train Detector</h1>
<h2 id="overview">Overview</h2> <h2 id="overview">Overview</h2>
<p>When a toothed whale, bat or other echolocator uses echolocation <p>When a toothed whale, bat or other echolocator uses echolocation
@ -33,24 +32,24 @@
with multiple types of acoustic data, from CPOD detections to single with multiple types of acoustic data, from CPOD detections to single
channel and multi-channel hydrophone recordings.</p> channel and multi-channel hydrophone recordings.</p>
<h2 id="how-it-works">How it works</h2> <h2 id="how-it-works">How it works</h2>
<p>PAMGuard's click train detector utilises both a detection and <p>PAMGuards click train detector utilises both a detection and
classification stage to extract click trains from recordings.</p> classification stage to extract click trains from recordings.</p>
<p>The detection stage is currently based on a multi hypothesis <p>The detection stage is currently based on a multi hypothesis
tracking (MHT) algorithm. This algorithm considers all possible tracking (MHT) algorithm. This algorithm considers all possible
combinations of transient detections creating a large hypothesis combinations of transient detections creating a large hypothesis
matrix which holds potential click trains. As more clicks are added to matrix which holds potential click trains. As more clicks are added to
the hypothesis matrix it grows exponentially and so, to prevent a the hypothesis matrix it grows exponentially and so, to prevent a
computer running out memory, it is regularly <em>pruned</em> to keep only computer running out memory, it is regularly “pruned” to keep only the
the most likely click trains over time. The assigned likelihood of a most likely click trains over time. The assigned likelihood of a click
click train is based on number of properties which can be defined in train is based on number of properties which can be defined in by the
by the user. For example, a user might select, ICI, Amplitude and user. For example, a user might select, ICI, Amplitude and Correlation
Correlation as variables to score click trains; this would mean that as variables to score click trains; this would mean that combinations
combinations of clicks with slowly changing ICI, amplitude and of clicks with slowly changing ICI, amplitude and waveforms would be
waveforms would be favoured by the algorithm and stay in the favoured by the algorithm and stay in the hypothesis matrix. Other
hypothesis matrix. Other properties such as bearing, click length and properties such as bearing, click length and peak frequency can also
peak frequency can also be selected. A graphical explanation of the be selected. A graphical explanation of the click train detection
click train detection algorithm is shown in Figure 1 and a more algorithm is shown in Figure 1 and a more detailed explanation of the
detailed explanation of the be found in Macaulay (2019).</p> be found in Macaulay (2019).</p>
<p align="center"> <p align="center">
<img width="930" height="900" src="resources/mht_diagram.png"> <img width="930" height="900" src="resources/mht_diagram.png">
</p> </p>
@ -67,18 +66,18 @@
pruned. After a minimum of Npmin clicks (in this case 4) each track pruned. After a minimum of Npmin clicks (in this case 4) each track
hypothesis (possible click train) is assigned a &Chi;<sup>2</sup> score. hypothesis (possible click train) is assigned a &Chi;<sup>2</sup> score.
The track hypothesis with lowest score (defined by larger coloured The track hypothesis with lowest score (defined by larger coloured
circles) has it's branch traced back Np (in this case 3) clicks. circles) has its branch traced back Np (in this case 3) clicks. Any
Any track hypothesis which do not include the click Np steps back are track hypothesis which do not include the click Np steps back are
pruned (defined by the double lines). Clicks which share no click pruned (defined by the double lines). Clicks which share no click
associations with the first track hypothesis are then pruned and the associations with the first track hypothesis are then pruned and the
process repeats until all clicks are part of a track or a maximum process repeats until all clicks are part of a track or a maximum
number of tracks have been considered (in this example there are two number of tracks have been considered (in this example there are two
tracks). The algorithm then moves to the next click, adds it to the tracks). The algorithm then moves to the next click, adds it to the
hypothesis matrix, assigns &Chi;<sup>2</sup> scores and traces the hypothesis matrix, assigns &Chi;<sup>2</sup> scores and traces the lowest
lowest &Chi;<sup>2</sup> branch Np steps back, pruning the hypothesis &Chi;<sup>2</sup> branch Np steps back, pruning the hypothesis matrix
matrix again; the process repeats until the last click. Note that again; the process repeats until the last click. Note that there is
there is always a track hypothesis with no associated clicks (i.e. always a track hypothesis with no associated clicks (i.e. the
the bottom-most branch where no clicks belong to a click train). If a bottom-most branch where no clicks belong to a click train). If a
track hypothesis is confirmed and thus removed from the hypothesis track hypothesis is confirmed and thus removed from the hypothesis
matrix, then this track can be used to start another click train matrix, then this track can be used to start another click train
</em> </em>
@ -98,12 +97,12 @@
correlation of the average spectrum of the click train with a correlation of the average spectrum of the click train with a
predefined spectral template.</p> predefined spectral template.</p>
<p>A click train which has been both detected and classified is <p>A click train which has been both detected and classified is
saved to PAMGuard's database and can be reclassified in PAMGuard's saved to PAMGuards database and can be reclassified in PAMGuards
viewer mode.</p> viewer mode.</p>
<h2 id="configuring-the-click-train-detector">Configuring the <h2 id="configuring-the-click-train-detector">Configuring the
click train detector</h2> click train detector</h2>
<p>The primary settings to configure can be split into MHT Kernel <p>The primary settings to configure can be split into MHT Kernel
and &Chi;<sup>2</sup> settings, these are all set in the primary click train and &Chi;^2 settings these are all set in the primary click train
detector dialog as shown in Figure 2.</p> detector dialog as shown in Figure 2.</p>
<p align="center"> <p align="center">
<img width="850" height="700" src="resources/detection_pane.png"> <img width="850" height="700" src="resources/detection_pane.png">
@ -119,8 +118,8 @@
important because they influence speed (a larger number of possible important because they influence speed (a larger number of possible
click trains in memory is more processor intensive) and the quality of click trains in memory is more processor intensive) and the quality of
the detections (the larger the number of possibilities the more likely the detections (the larger the number of possibilities the more likely
that <em>true</em> click trains are contained in the hypothesis matrix). that “true” click trains are contained in the hypothesis matrix). The
The specific settings are;</p> specific settings are;</p>
<p> <p>
<strong><em>Prune-back</em></strong>: The hypothesis matrix needs <strong><em>Prune-back</em></strong>: The hypothesis matrix needs
pruned so that it does not grow exponentially and cause memory issues. pruned so that it does not grow exponentially and cause memory issues.
@ -152,7 +151,7 @@
<p> <p>
<strong><em>Max no. trains</em></strong>: This is a maximum allowed <strong><em>Max no. trains</em></strong>: This is a maximum allowed
number of trains in the hypothesis mix. Note this refers to the number number of trains in the hypothesis mix. Note this refers to the number
of trains which can survive pruning - the actual number of potential of trains which can survive pruning the actual number of potential
click trains in the hypothesis mix will be much larger. Generally, click trains in the hypothesis mix will be much larger. Generally,
just via pruning, the hypothesis matrix will keep itself below the max just via pruning, the hypothesis matrix will keep itself below the max
no. trains, however, in certain situations it can grow too large and no. trains, however, in certain situations it can grow too large and
@ -165,8 +164,8 @@
</h3> </h3>
<p> <p>
&Chi;<sup>2</sup> is a measure of the likelihood that a click train is &Chi;<sup>2</sup> is a measure of the likelihood that a click train is
from a (usually) biological source. The higher the &Chi;<sup>2</sup> from a (usually) biological source. The higher the &Chi;<sup>2</sup> value
value the lower the quality of a click train. the lower the quality of a click train.
</p> </p>
<p> <p>
The &Chi;<sup>2</sup> model used in the click train detector considers The &Chi;<sup>2</sup> model used in the click train detector considers
@ -198,8 +197,8 @@
influence on the calculation of &Chi;<sup>2</sup> and decreasing means influence on the calculation of &Chi;<sup>2</sup> and decreasing means
that the descriptor has a larger influence on &Chi;<sup>2</sup>. In some that the descriptor has a larger influence on &Chi;<sup>2</sup>. In some
cases, clicks can be so close together that the variance is tiny and cases, clicks can be so close together that the variance is tiny and
thus &Chi;<sup>2</sup> becomes huge e.g. during buzzes. A minimum thus &Chi;<sup>2</sup> becomes huge e.g. during buzzes. A minimum variance
variance value (<em>qt<sub>i</sub></em>) prevents the variance <em>(max¡(q<sub>i</sub> value (<em>qt<sub>i</sub></em>) prevents the variance <em>(max(q<sub>i</sub>
(t<sub>(k+1)</sub>-t<sub>k</sub> ),qt<sub>i</sub> )<sup>2</sup>) (t<sub>(k+1)</sub>-t<sub>k</sub> ),qt<sub>i</sub> )<sup>2</sup>)
</em> from falling below very low values. </em> from falling below very low values.
</p> </p>
@ -229,7 +228,7 @@
between detections. between detections.
</p> </p>
<p> <p>
<strong><em>Amplitude:</em></strong> the amplitude in dB re 1&mu;Pa pp. <strong><em>Amplitude:</em></strong> the amplitude in dB re 1/muPa pp.
The algorithm looks for slowly changing amplitude values. Note that The algorithm looks for slowly changing amplitude values. Note that
the algorithm is comparing the change in change in amplitude so that the algorithm is comparing the change in change in amplitude so that
the click train algorithm is not biased against large but consistent the click train algorithm is not biased against large but consistent
@ -312,14 +311,14 @@
<strong><em>Long track bonus:</em></strong> add a bonus factor for <strong><em>Long track bonus:</em></strong> add a bonus factor for
longer click trains to prevent fragmentation. This is the total length longer click trains to prevent fragmentation. This is the total length
of the click train in seconds divided by the total hypothesis matrix of the click train in seconds divided by the total hypothesis matrix
time in seconds L which is then multiplied so that &Chi;<sup>2</sup> = time in seconds L which is then multiplied so that &Chi;<sup>2</sup> = (&Chi;<sup>2</sup>*L)<sup>LT</sup>
(&Chi;<sup>2</sup>*L)<sup>LT</sup> where LT is the long track bonus. where LT is the long track bonus.
</p> </p>
<p> <p>
<strong><em>Coast penalty:</em></strong> add a penalty for <strong><em>Coast penalty:</em></strong> add a penalty for “coasting”
'coasting' i.e. when an expected click, based on ICI, is not i.e. when an expected click, based on ICI, is not present in the click
present in the click train. This penalty is multiplied by the number train. This penalty is multiplied by the number of coasts i.e. the
of coasts i.e. the likely number of missed clicks based on ICI likely number of missed clicks based on ICI
</p> </p>
<p> <p>
<strong><em>New Track Penalty:</em></strong> if a track hypothesis is <strong><em>New Track Penalty:</em></strong> if a track hypothesis is
@ -361,10 +360,10 @@
&Chi;<sup>2</sup> threshold classifier &Chi;<sup>2</sup> threshold classifier
</h3> </h3>
<p> <p>
The click train is classified if it's overall &Chi;<sup>2</sup> value The click train is classified if its overall &Chi;<sup>2</sup> value is
is lower than the set &Chi;<sup>2</sup> Threshold and it has more than lower than the set &Chi;<sup>2</sup> Threshold and it has more than Min.
Min. Clicks and the time between the first and last click is greater Clicks and the time between the first and last click is greater than
than Min. Time Min. Time
</p> </p>
<h3 id="idi-classifier">IDI Classifier</h3> <h3 id="idi-classifier">IDI Classifier</h3>
<p>The click train is classified if the median/mean and standard <p>The click train is classified if the median/mean and standard
@ -374,11 +373,11 @@
<p>The click train is classified if the average spectra of the <p>The click train is classified if the average spectra of the
click train has a correlation value above Spectrum Correlation click train has a correlation value above Spectrum Correlation
Threshold with a user defined spectral template. The template can be Threshold with a user defined spectral template. The template can be
set using the button on the top right of the spectrum plot – a set using the button on the top right of the spectrum plot a default
default spectrum can be loaded or a spectrum can be loaded from a .mat spectrum can be loaded or a spectrum can be loaded from a .mat or .csv
or .csv file. A csv file should have the first row as the spectrum and file. A csv file should have the first row as the spectrum and first
first column of the second row the sample rate. A .mat file should be column of the second row the sample rate. A .mat file should be a
a single saved structure with sR (sample rate) and spectrum (array of single saved structure with sR (sample rate) and spectrum (array of
spectrum values) fields.</p> spectrum values) fields.</p>
<h3 id="bearing-classifier">Bearing Classifier</h3> <h3 id="bearing-classifier">Bearing Classifier</h3>
<p>The click train is classified if minimum and maximum bearing <p>The click train is classified if minimum and maximum bearing
@ -389,7 +388,7 @@
<h2 id="parametrising-the-classifier">Parametrising the classifier</h2> <h2 id="parametrising-the-classifier">Parametrising the classifier</h2>
<p>Each classifier has a set of metadata that are added to click <p>Each classifier has a set of metadata that are added to click
trains. This can be accessed through the tooltip or right click menus trains. This can be accessed through the tooltip or right click menus
in various displays. For example, in the Time Base Display FX hover in various displays. For example, in the Time Base Display Fx hover
the mouse over a click train or bring the pop menu with a right click. the mouse over a click train or bring the pop menu with a right click.
Parameters such as the spectral correlation value, IDI and bearing Parameters such as the spectral correlation value, IDI and bearing
information etc are displayed which allows users to get an idea of information etc are displayed which allows users to get an idea of
@ -464,23 +463,23 @@
are localised.</em> are localised.</em>
</p> </p>
<p>In viewer mode, add the module and then go to Settings&gt;Click <p>In viewer mode, add the module and then go to Settings&gt;Click
Train Detector &gt; Reanalyse click trains.This will bring up Train Detector &gt; Reanalyse click trains.This will bring up
PAMGuard's generic data reprocessing dialog with two settings, Click PAMGuards generic data reprocessing dialog with two settings, Click
Train Detector or Click Train Classifier. The Click Train Detector Train Detector or Click Train Classifier. The Click Train Detector
option will run the detection and classification algorithm again. The option will run the detection and classification algorithm again. The
Click Train Classifier will only run the classification algorithm on Click Train Classifier will only run the classification algorithm on
existing detected click trains (much faster). Note that users can existing detected click trains (much faster). Note that users can
select how much data to reprocess in the Data dropdown menu. All select how much data to reprocess in the Data dropdown menu All Data
Data means the entire dataset will be reprocessed, Loaded Data means means the entire dataset will be reprocessed, Loaded Data means just
just the current data loaded in the display (all scrollable data), the current data loaded in the display (all scrollable data), Select
Select Data allows the user to define two time limits between which Data allows the user to define two time limits between which all data
all data is reprocessed.</p> is reprocessed.</p>
<h2 id="visualising-results">Visualising Results</h2> <h2 id="visualising-results">Visualising Results</h2>
<p>The results from the click train detector can be visualised in a <p>The results from the click train detector can be visualised in a
variety of displays in PAMGuard.</p> variety of displays in PAMGuard.</p>
<h3 id="click-bearing-time-display">Click bearing time display</h3> <h3 id="click-bearing-time-display">Click bearing time display</h3>
<p>By default, clicks trains will be shown in the Click Detector <p>By default, clicks trains will be shown in the Click Detector
Module's in built bearing time display. Different click trains are Modules in built bearing time display. Different click trains are
represented as different colours. Note that you must right click on represented as different colours. Note that you must right click on
the display and select Colour by Click Trains</p> the display and select Colour by Click Trains</p>
<p align="center"> <p align="center">
@ -492,31 +491,22 @@
bearing time display. Different colours correspond to different click bearing time display. Different colours correspond to different click
trains.</em> trains.</em>
</p> </p>
<h3 id="time-display-fx">Time Display FX</h3> <h3 id="time-display-fx">Time Display Fx</h3>
<p>The Time Display FX is a more modern display which allows any <p>The Time Display Fx is a more modern display which allows any
time-based data to be plotted together on a large variety of y-axis time-based data to be plotted together on a large variety of y-axis
(e.g., frequency, bearing, amplitude etc.). Click trains will be (e.g., frequency, bearing, amplitude etc.). Click trains will be
plotted on the time-based display by adding Click detections to the plotted on the time-based display by adding Click detections to the
display and then using the right</p> display and then using the right</p>
<p align="center"> <p align="center">
<img width="940" height="500" src="resources/clicktrain_TDFX.png"> <img width="940" height="500" src="resources/clicktrain_TDFx.png">
</p> </p>
<p> <p>
<em>Click train data displayed in the time display FX. Users can <em>Click train data displayed in the time display Fx. Users can
right click on click trains to view average spectra and waterfall right click on click trains to view average spectra and waterfall
spectrograms (shown here in top right).</em> spectrograms (shown here in top right).</em>
</p> </p>
<p CLASS="previousLink">
<a href=""></a>
</p>
<p CLASS="nextLink">
<a href="ClickDetector_clickDetectorDisplays.html">Next: Click
Detector Displays </a>
</p>
<br>
<br>
</body> </body>
</html> </html>