nordic-dev.net/PAMGuard
nordic-dev.net/PAMGuard
2
0
Fork 0
mirror of https://github.com/PAMGuard/PAMGuard.git synced 2024-11-22 07:02:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

split Tethys help files into smaller chunks

Browse Source
This commit is contained in:
Marie 2024-01-26 19:56:45 -08:00
parent 88be6ffe2e
commit 810ec67077
8 changed files with 732 additions and 526 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
src/help/utilities/tethys/docs/calibrations.html Normal file
View File

@ -0,0 +1,147 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<link href="../../../pamHelpStylesheet.css" type="text/css"
rel="STYLESHEET">
<title>Instrument Calibration Information</title>
<style type="text/css">
img.wrap {
float: left
}
img.wrapright {
float: right
}
img {
float: right;
}
</style>
</head>
<body>
<h1>Instrument calibration information</h1>
<p>
Most of the calibration data is taken from the array manager and
from the sound acquisition module. However, PAMGuard will ask a
few questions about HOW the instrument was calibrated, when it was
done and who is responsible.
</p>
<p>
There are two dialogs associated with calibration. The first
asks for a calibration method and has the following fields:
</p>
<ul>
<li>
Method: Must be one of the following options:
<ul>
<li>Reference hydrophone</li>
<li>Manufacturer’s specification</li>
<li>Piston phone</li>
<li>Other calibrated source</li>
<li>Unknown</li>
</ul>
</li>
<li>
Serial number: Hydrophone serial number
</li>
<li>
Quality: Quality assurance value:
<ul>
<li> unverified: The calibration has not been verified </li>
<li> valid: The calibration has been validated as per the quality assurance process </li>
<li> invalid: The calibration was found to be invalid during quality assurance </li>
</ul>
</li>
<li>
QA Comment: Textual description of the quality assurance
process.
</li>
<li>
Calibration method: Textual description of the Method.
</li>
</ul>
<p>
The second calibrations dialog asks for:
</p>
<ul>
<li>
Calibration date: Date the calibration was performed.
</li>
<li>
Update frequency: Must be one of the following:
<ul>
<li>
as-needed: No updates are planned, but if a change is needed the calibration will be updated (defaul)t
</li>
<li>
unplanned: There are no plans to ever update the record.
</li>
<li>
yearly: A yearly review will be conducted to ensure that the record is valid.
</li>
</ul>
</li>
<li>
Technical Person / Data Manager: These two types of data have
the same fields and detail who was responsible for the
calibration and who is responsible for maintaining the record
of the calibration. In many cases, this may be the same
person and copy buttons allow the fields to be duplicated.
<ul>
<li>
Name: Responsible party’s naem
</li>
<li>
Organisation: Organisation to which the party reports
</li>
<li>
Position: Responsible party’s title
</li>
<li>
Email: Email contact information
</li>
</ul>
</li>
</ul>
<p>
Fill in as much information as you can!
If the export is successful, a record will show for each
hydrophone (or sensor) in your instrument array in the
calibration information table:
</p>
<div>
<img src="./images/calibration_information.png" class=".center"
alt="Panel with information about instrument calibration"/>
</div>
<br>
<br>
<p class="prevLink"><a href="tethys_module.html">Previous: Module overview
<p class="nextLink"><a href="deployments.html">Next: Instrument deployments
</a></p>
<br>
</body>
</html>

121
src/help/utilities/tethys/docs/connection.html Normal file
View File

@ -0,0 +1,121 @@
<html>
<head>
<LINK href="../../../pamHelpStylesheet.css" type="text/css"
rel="STYLESHEET">
<title>Tethys Connection and Project Details </title>
</head>
<body>
<h1> Connection and Project Details </h1>
<p>
Make sure you have a <a href = "tethys_server.html">Tethys Server</a> running. The PAMGuard interface will
only work with <a href="https://tethys.sdsu.edu/tethys3/">Tethys
3</a> or later. The section below specifies how to set the
address of Tethys server address as well as determine if
PAMGuard can communicate successfully with Tethys. (The top
panel will be orange if communication is not working.
</p>
<h2>Tethys Server</h2>
<p>
The Tethys Server field next to the picture of the goddess Tethys
indicates the address of the Tehtys server. To change this field,
click on the gear icon. You will be prompted to provide a computer
address (URL) and a port. The address should start with http://
followed by the machine name or internet protocol address unless
the Tethys server has been configured to use an encrypted
connection. In this case, start the address with https://.
</p>
<p>
By default, PAMGuard will use http://localhost:9779 which
assumes that your Tethys server is running on the same computer as
PAMGuard and that it expects communication on port 9779, the
default port (administrators may change this).
</p>
<p>
If PAMGuard can communicate with the Tethys server, the
Connection and Project panel will be light grey. If
communication is not possible, the panel will be colored
orange. Likely causes for communication failure are:
</p>
<ul>
<li>
The server address or port is incorrect.
</li>
<li>
Tethys has not been started on the server machine. One of the
main reasons that we see this is when the administrator has
not configured Tethys to run automatically as a service. In
that case, when a machine reboots (e.g., for automatic
operaing system updates) the server will not start
automatically. The Tethys manual explains how to configure
Tethys as a service that starts automatically when the machine
boots.
</li>
<li>
Firewall rules do not permit traffic between the machine
executing PAMGuard and the one hosting Tethys on the selected
port. If you do not have adminstrative privileges, you will
need to contact your support team for help.
</li>
</ul>
<h2>Project and Instrument Information</h2>
<p>
Projects are names used by Tethys to help track work that should
be considered together, such as a series of deployments designed
to answer a specific question or funded under a specific
grant. If you do not already have a project defined in your
PAMGuard database, you can click the "New Project" button in the
"Connection and Project details" section of the Tethys
module. This will start a dialog that asks for a case-sensitive
project name and a geographic region. The geographic region is
for convenience, PAMGuard and Tethys track information by
longitude and latitude, but sometimes it is helpful to query for
information with respect to a geographic name such as Channel
Islands National Marine Sanctuary.
</p>
<p>
The array instrumentation is selected from a drop-down menu next
to the Instruments label. A dropdown menu next to the label
“Instruments” shows the list of hydrophone arrays. These are
likely to have been previously established prior to starting
analysis of your data by using the menu Settings -> Hydrophone
Array.
</p>
<p>
If you are a long-time user of PAMGuard, you will notice
additional fields are required for instrumentation: Instrument
Type and Instrument Id. The type indicates what type of
instrument is being used and may be generic such as a mooring or
array or denote a specific instrument such as a HARP, Rock
Hopper, SoundTrap, etc. The Id is a unique identifier for the
instrument such as a serial number. Note that if you are using
an older PAMGuard database, you may see a blank entry in the
instruments list as these new fields will not have been
populated. Press new/edit to access the instrument settings
from the Tethys module page.
</p>
<br>
<br>
<p class="prevLink"><a href="tethys_module.html">Previous:
Tethys module</a></p>
<p class="nextLink"><a href="calibrations.html">Next: Instrument calibrations</a></p>
<br>
</body>

143
src/help/utilities/tethys/docs/deployments.html Normal file
View File

@ -0,0 +1,143 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<link href="../../../pamHelpStylesheet.css" type="text/css"
rel="STYLESHEET">
<title>Deployments</title>
<style type="text/css">
img.wrap {
float: left
}
img.wrapright {
float: right
}
img {
float: right;
}
</style>
</head>
<body>
<h1>Deployments</h1>
<p>
Tethys uses deployment records to register information about
when instruments have been deployed as well as their
characteristics. Examples of characteristics that are recorded
include sample rate and the number of quantization bits,
description of duty cycles (if applicable), hydrophone geometry,
and enough details to be able find calibration data for specific
hydrophones.
</p>
<p>
PAMGuard will examine the
<a href="../../generalDatabaseHelp/docs/database_database.html">PAMGuard
database</a>
and <a href="../../BinaryStore/docs/binarystore_overview.html">
binary Store</a> to determine what records should be generated for
your instrumentation.
</p>
<p>
Where data were collected continuously or on a regular duty
cycle, PAMGuard will create a single deployment record. If data
were collected on a more "ad-hoc" basis, where the instrument
has been deployed multiple times or has irregular recording,
PAMGuard will generate a deployment record for each period of
recording.
</p>
<p>
The figure below shows an example of ad-hoc recording periods
identified by PAMGuard:
</p>
<div>
<img src="./images/deploymentspanel.png" class=".center"
alt="Panel showing recording times/deployments for this PAMGuard database"/>
</div>
<p>
Occasionally, there may be short recording periods (e.g. while
you were testing kit on deck) that you do not want to export. Use
the select checkbox to pick all of the rows that you wish to
export, or right click on the table and "Select All."
</p>
<p>
When one or more deployment records are selected, the
"Export..." button will become available. Selecting the export
button will start a dialog that asks for additional information
about the deployments and then write records to Tethys.
</p>
<p>
The first page of the dialog asks for the project and geographic
region which will be automatically populated if they have been
previously specified. In addition, the following fields are
requested:
</p>
<ul>
<li>Cruise name - Optional name of the deployment cruise</li>
<li>Site - Case-sensitive name for the deployment site,
e.g. "Tanner Banks" or a letter designation "T". This can
provide a simple way to identify multiple deployments at the
same general location.
</li>
<li>Responsible Party - A set of fields describing who was
responsible for the deployment and how they may be
contacted.
</li>
</ul>
<p>
The next page of the dialog asks whether you would like to
export a single deployment document or multiple deployments.
<strong>todo: add more detail here</strong>
</p>
<p>
Finally, you are prompted to provide optional textual descriptions of:
<ul>
<li> Objectives - What were your objectives when deploying the
instrument? Example: Determine population estimates for
critically endangered populations of vaquita (<em>Phocoena
sinus</em>).
</li>
<li> Abstract - A textual description of the deployment.
Example: A set of high frequency recorders were deployed across the
northern portion of the Sea of Cortez in the historical range
of the vaquita (<em>Phocoena sinus</em>). These recordings will
support detection and density estimation efforts.
</li>
<li>
Method - A description of the methods used. Example:
Small boat deployment of bottom moored SoundTrap recorders
with acoustic releases.
</li>
</ul>
Press Finish to export the records. Once the
document(s) have been successuflly exported, the document name
associated with each recording period will be shown in the
Tethys Deployment column.
</p>
<br></br>
<br></br>
<p class="prevLink">
<a href="calibrations.html">Previous: Calibrations</a>
</p>
<p class="nextLink">
<a href="detect_localize.html">Next: Detections & Localizations</a>
</p>
</body>
</html>

161
src/help/utilities/tethys/docs/detect_localize.html Normal file
View File

@ -0,0 +1,161 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<link href="../../../pamHelpStylesheet.css" type="text/css"
rel="STYLESHEET">
<title>Detections/Localizations</title>
<style type="text/css">
img.wrap {
float: left
}
img.wrapright {
float: right
}
img {
float: right;
}
</style>
</head>
<body>
<h1>Exporting Detections/Localizations (PAMGuard data blocks)</h1>
<p>
The bottom left panel of the Tethys module shows a list of
different types of PAMGuard data that can be exported. The data
in this list correspond to the various PAMGuard modules that have
been configured. See the
<a href="../../../overview/PamMasterHelp/docs/modelViewer.html">
data model viewer</a>
help for an example of how PAMGuard might be configured.
</p>
<h2>Species information</h2>
<p>
Some of these data represent detections of specific species or
phenomena that must be translated to Tethys. A context menu
(right-click on most computers) will show the option "Species
info..." that will allow you to specify the
<a href="./tethys_speciescodes.html">translation of events</a>
to species identifiers and call/sound types. If you try to export
without having done this, the species info dialog will be started
automatically prior to export.
</p>
<h2>Selecting data blocks for import</h2>
<p>
In the sample data blocks below, four modules have been
configured, but only one of them has been run. Column "N Pam
Data" indicates the number of data records that have been
produced, and "PAMGuard Time" tells us when the data were
processed. "Tethys Documents" indicates how many Tethys records
have been produced, and should be 0 until the data are exported.
</p>
<div>
<img src="./images/data_blocks.png" class=".center"
alt="List of results showing detections and other module processing events"/>
</div>
<p>
Select the data blocks to be exported by clicking on them.
Multiple lines can be selected by using keyboard modifiers such as
holding the shift while clicking to select all data blocks between
the last clicked block and where you click. Holding the alternate
(ALT) key will allow selection or de-selection of a single item
without affecting the selection state of other blocks.
<p>
<p>
<em>
SUGGESTION: It looks like we have to highlight these by clicking
on them. As we use select boxes for recording periods, we might
want to do the same thing here... We might want to rename
N PAM Datas to N PAM Data as data are already plural.
</em>
</p>
<h2> Exporting data blocks </h2>
<p>
Once the data blocks have been selected, press export. A series
of dialogs will guide you through the export process. The first
set of dialogs simply display a summary of information about what
will be exported.
</p>
<div>
<img src="./images/stream_algo_info.png" class=".center"
alt="List of details describing the mechanism, parameters, and version of modules used in processing"/>
</div>
<p>
There is nothing to change in this summary. Press Next once you
have reviewed it. The second panel allows specification of your
objectives, abstract, and method. Many modules will have
pre-populated the method for you. While it is recommended to populate
the objectives and abstract, these fields are optional.
</p>
<p>
Press Next to proceed to the next step of the dialog. You will be asked
what details you wish to store within the parameters that were used to
produce these data. Your must select one of the following:
</p>
<ul>
<li>
None - Do not report any of parameters used to produce these
detections. This option is <strong>not recommended</strong> as
it severely limits your ability to reproduce your results at a
later date or know whether or not the results of different
studies can be used together.
</li>
<li> Data selector only - <strong>not sure what this is</strong> </li>
<li>
Module only - Report the parameters that were set with this
module. Only parameters associated with the specific module
will be reported. Examples include score and duration thresholds
as well as any other type of criterion used to determine whether
or not an event is associated with a specific phenomenon or species.
</li>
<li>
Full process chain (default) - This is the most verbose option. It includes the module
parameters as well as anything else that is part of the signal processing chain that leads
to the module. As an example, a module only setting would not report the parameters that were
used to generate a spectrogram that was presented to a module for classification, but the
full process chain would record these details as well. Use this option will dramatically
increase the potential to reproduce your results, but it will generate a large amount of data
about the signal processing chain, much of which might not be useful.
</li>
</ul>
<p>
The final page of the dialog has an "Export data" button. Press
this to export the data. The system will begin generating the
Tethys document and the "Export data" button will be relabeled "Export complete"
once it is done. At this point, you can press "Finish" to close
the dialog.
<em>Would it make more sense to export when the user presses
Finish (or change the Finish button Export)?</em>
</p>
<p class="prevLink">
<a href="deployments.html">Previous: Deployments</a>
</p>
<p class="nextLink">
<a href="./tethys_speciescodes.html">Translating species to
taxonomic serial numbers</a> (species encoding)
</p>
</body>
</html>

92
src/help/utilities/tethys/docs/tethys_module.html Normal file
View File

@ -0,0 +1,92 @@
<html>
<head>
<LINK href="../../../pamHelpStylesheet.css" type="text/css"
rel="STYLESHEET">
<title>Tethys Module Overview</title>
</head>
<body>
<h1>Tethys Module Overview</h1>
<p>
It is assumed that you are familiar with PAMGuard and have some
knowledge about Tethys.
<a href="https://tethys.sdsu.edu/documentation">Documentation</a>
and <a href="https://tethys.sdsu.edu/tutorials/">tutorials</a>
are available at the Tethys
<a href="https://tethys.sdsu.edu">web site</a>.
</p>
<h1>Launch PAMGuard in viewer mode</h1>
<p>
Tethys export is only available in
<a href="../../../overview/PamMasterHelp/docs/viewerMode.html">PAMGuard
Viewer mode</a>
and is used to archive project data to a centralised
database. It is NOT a replacement for the
existing <a href="../../generalDatabaseHelp/docs/database_database.html">PAMGuard
database</a>. Open the PAMGuard database that you wish to use
in viewer mode.
</p>
<h1>PAMGuard Tethys Module</h1>
<p>
Add a Tethys module to PAMGuard from the File / Add Modules /
Utilities menu. A new tab panel will show the Tethys interface
</p>
<div>
<img src = "./images/TethysGUI_1.png" class=".center"/>
</div>
<p>
The tab shows a number of panes for the connection to the server
and the various types of data that will be output to the
database. Some of these panes summarize information on what's in
the current PAMGuard dataset (consisting of your PAMGuard
database and binary store), others may be empty until you start
to export to Tethys.
</p>
<p>
The Tethys module consists of several panels:
</p>
<ul>
<li>
<a href="connection.html">Connection and Project Details</a> -
Specifies the location of the Tethys server and metadata about
the project.
</li>
<br>
<li>Data Export - There are several panes that are responsible
for exporting information about instrument deployments, their
calibrations, and what they detected/localized.
<ul>
<li>
Instrument <a href="calibrations.html">calibration</a>
information
</li>
<li>
Recording periods
and <a href="deployments.html">deployments</a> information.
</li>
<li>
<a href="detect_localize.html">Detections and
localizations</a>. A final panel next to this one lists
exported detection/localization documents.
</li>
</ul>
</li>
</ul>
<br>
<br>
<p class="prevLink"><a href="tethys_overview.html">Previous: Overview</a></p>
<p class="nextLink"><a href="connection.html">Next: Connection
& Project Details</a></p>
<br>
</body>
</html>

73
src/help/utilities/tethys/docs/tethys_overview.html
View File

@ -22,47 +22,66 @@ img {
</head>
<body>
<h1>Tethys Interface</h1>
<p></p>
<h2>Overview</h2>
<div>
<img SRC="images/Tethys-200.png" alt="Tethys mosaic"
style="float: right; margin 10px;"
style="float: right; margin 10px;"/>
</div>
<p>
PAMGuard is compatible
with <a href="https://tethys.sdsu.edu/tethys3/">Tethys 3.0</a> or
later.
<a href="https://tethys.sdsu.edu/">Tethys</a> is a freely
available open source temporal-spatial database for metadata related
to acoustic recordings. The database is intended to house the metadata
from marine mammal detection and localization studies, allowing the
user to perform meta analyses or to aggregate data from many
experimental efforts based on a common attribute. This resulting
database can then be queried based on time, space, or any desired
attribute and the results can be integrated with external datasets
such as NASA's Ocean Color, lunar illumination, etc. in a consistent
manner. While Tethys is designed primarily for acoustic metadata from
marine mammals, the design is general enough to permit use in other
areas as well.
</p>
<p>PAMGuard is compatible with <a href="https://tethys.sdsu.edu/tethys3/">Tethys 3.0</a> or above, released early in 2024. </p>
<p>The Tethys database is not a replacement for the existing
<a href="../../generalDatabaseHelp/docs/database_database.html">PAMGuard Database.</a>
Where the PAMGuard database only contains data from a single instrument or cruise, the Tethys
database contains data from many cruises and projects and can be used to hold a summary of all data
from a lab or organisation.
available open source temporal-spatial database for metadata
related to acoustic recordings. The database is intended to house
the metadata from marine mammal detection and localization
studies, allowing the user to perform meta analyses or to
aggregate data from many experimental efforts based on a common
attribute. This resulting database can then be queried based on
time, space, or any desired attribute and the results can be
integrated with external datasets such as NASA's Ocean Color,
lunar illumination, etc. in a consistent manner. While Tethys is
designed primarily for acoustic metadata from marine mammals, the
design is general enough to permit use in other areas as well.
</p>
<p>Before using the module in PAMGuard, you should install the Tethys Server, which runs under
Windows. <a href="https://tethys.sdsu.edu/install/">
Instructions for installing the Tethys Server can be found here.</a></p>
<p>
The Tethys database is not a replacement for the existing
<a href="../../generalDatabaseHelp/docs/database_database.html">PAMGuard
Database.</a> Where the PAMGuard database only contains data from
a single instrument or cruise, the Tethys database contains data
from many cruises and projects and can be used to hold a summary
of all data from a lab or organisation. PAMGuard's Tethys module
provides an interface for exporting detailed or summary
information about acoustic detections to the Tethys database.
</p>
<p>
Before using the module in PAMGuard, you should install the Tethys
Server. While clients that communicate with Tethys can run on a
variety of computer operating systems, there are a small number of
dependencies on Microsoft technologies that require the server to
be installed on a Microsoft Windows machine.
<a href="https://tethys.sdsu.edu/install/"> Instructions
for installing the Tethys Server can be found here.</a></p>
<br><br>
<a href="tethys_quickstart.html">Next: Quick Start</a>
<p>
Module help:
</p>
<br>
<ol>
<li> The <a href="tethys_module.html">Tethys module</a> (start here)</li>
<li> The <a href="connection.html">Connecting to Tethys</a> </li>
<li> The <a href="calibrations.html">Instrument calibrations</a> </li>
<li> The <a href="deployments.html">Instrument deployments</a> </li>
<li> The <a href="detect_localize.html">Detections & Localizations</a> </li>
<li> Guide to specifying <a href="tethys_speciescodes.html">species names</li>
</ol>
</body>

487
src/help/utilities/tethys/docs/tethys_quickstart.html
View File

@ -1,487 +0,0 @@
<html>
<head>
<LINK href="../../../pamHelpStylesheet.css" type="text/css"
rel="STYLESHEET">
<title>Tethys</title>
</head>
<body>
<h1>Tethys Quick Start</h1>
<p>This 'Quick Start' guide is aimed at people who are already familiar with both Tethys and PAMGuard</p>
<p>The Tethys database is only used in
<a href="../../../overview/PamMasterHelp/docs/viewerMode.html">PAMGUard Viewer mode</a> and is only used to archive project data to a single
centralised database.
It is NOT a replacement for the existing <a href="../../generalDatabaseHelp/docs/database_database.html">PAMGuard database</a>.</p>
<h1>PAMGuard Tethys Module</h1>
<p>Launch PAMGuard in Viewer Mode with an existing set of data.</p>
<p>Add a Tethys module to PAMGuard from the File / Add Modules / Utilities menu. </p>
<p>A new tab panel will show the Tethys interface</p>
<center><img src = "./images/TethysGUI_1.png" width="100%" height="auto"></center>
<p>The tab shows a number of panels for the connection to the server and the various types
of data that will be output to the database. Some of these should summary information on what's in the
current PAMGuard dataset (consisting of your PAMGuard database and binary store), others may be empty until you start to
export to Tethys. </p>
<h2> Connection and Project Details </h2>
<p>
Make sure you have a <a href = "tethys_server.html">Tethys Server</a> running. The PAMGuard interface will
only work with <a href="https://tethys.sdsu.edu/tethys3/">Tethys
3</a> or later. The section below specifies how to set the
address of Tethys server address as well as determine if
PAMGuard can communicate successfully with Tethys. (The top
panel will be orange if communication is not working.
</p>
<h3>Tethys Server</h3>
<p>
The Tethys Server field next to the picture of the goddess Tethys
indicates the address of the Tehtys server. To change this field,
click on the gear icon. You will be prompted to provide a computer
address (URL) and a port. The address should start with http://
followed by the machine name or internet protocol address unless
the Tethys server has been configured to use an encrypted
connection. In this case, start the address with https://.
</p>
<p>
By default, PAMGuard will use http://localhost:9779 which
assumes that your Tethys server is running on the same computer as
PAMGuard and that it expects communication on port 9779, the
default port (administrators may change this).
</p>
<p>
If PAMGuard can communicate with the Tethys server, the
Connection and Project panel will be light grey. If
communication is not possible, the panel will be colored
orange. Likely causes for communication failure are:
</p>
<ul>
<li>
The server address or port is incorrect.
</li>
<li>
Tethys has not been started on the server machine. One of the
main reasons that we see this is when the administrator has
not configured Tethys to run automatically as a service. In
that case, when a machine reboots (e.g., for automatic
operaing system updates) the server will not start
automatically. The Tethys manual explains how to configure
Tethys as a service that starts automatically when the machine
boots.
</li>
<li>
Firewall rules do not permit traffic between the machine
executing PAMGuard and the one hosting Tethys on the selected
port. If you do not have adminstrative privileges, you will
need to contact your support team for help.
</li>
</ul>
<h3>Project and Instrument Information</h3>
<p>
Projects are names used by Tethys to help track work that should
be considered together, such as a series of deployments designed
to answer a specific question or funded under a specific
grant. If you do not already have a project defined in your
PAMGuard database, you can click the "New Project" button in the
"Connection and Project details" section of the Tethys
module. This will start a dialog that asks for a case-sensitive
project name and a geographic region. The geographic region is
for convenience, PAMGuard and Tethys track information by
longitude and latitude, but sometimes it is helpful to query for
information with respect to a geographic name such as Channel
Islands National Marine Sanctuary.
</p>
<p>
The array instrumentation is selected from a drop-down menu next
to the Instruments label. A dropdown menu next to the label
“Instruments” shows the list of hydrophone arrays. These are
likely to have been previously established prior to starting
analysis of your data by using the menu Settings -> Hydrophone
Array.
</p>
<p>
If you are a long-time user of PAMGuard, you will notice
additional fields are required for instrumentation: Instrument
Type and Instrument Id. The type indicates what type of
instrument is being used and may be generic such as a mooring or
array or denote a specific instrument such as a HARP, Rock
Hopper, SoundTrap, etc. The Id is a unique identifier for the
instrument such as a serial number. Note that if you are using
an older PAMGuard database, you may see a blank entry in the
instruments list as these new fields will not have been
populated. Press new/edit to access the instrument settings
from the Tethys module page.
</p>
<h2>Data Export</h2>
<p>
It is best to export data in the sequence the panels are laid out in on the PAMGuard display:
</p>
<ol>
<li>
Instrument calibration information: exports to the Tethys Calibrations
</li>
<li>
Recording periods and deployment information: exports to Tethys Deployments
</li>
<li>
PAMGuard data blocks: exports to Tethys Detections and/or Localizations.
</li>
</ol>
<h3>Instrument calibration information</h3>
<p>
Most of the calibration data is taken from the array manager and
from the sound acquisition module. However, PAMGuard will ask a
few questions about HOW the instrument was calibrated, when it
was done and who is responsible.
</p>
<p>
There are two dialogs associated with calibration. The first
asks for a calibration method and has the following fields:
</p>
<ul>
<li>
Method: Must be one of the following options:
<ul>
<li>Reference hydrophone</li>
<li>Manufacturer’s specification</li>
<li>Piston phone</li>
<li>Other calibrated source</li>
<li>Unknown</li>
</ul>
</li>
<li>
Serial number: Hydrophone serial number
</li>
<li>
Quality: Quality assurance value:
<ul>
<li> unverified: The calibration has not been verified </li>
<li> valid: The calibration has been validated as per the quality assurance process </li>
<li> invalid: The calibration was found to be invalid during quality assurance </li>
</ul>
</li>
<li>
QA Comment: Textual description of the quality assurance
process.
</li>
<li>
Calibration method: Textual description of the Method.
</li>
</ul>
<p>
The second calibrations dialog asks for:
</p>
<ul>
<li>
Calibration date: Date the calibration was performed.
</li>
<li>
Update frequency: Must be one of the following:
<ul>
<li>
as-needed: No updates are planned, but if a change is needed the calibration will be updated (defaul)t
</li>
<li>
unplanned: There are no plans to ever update the record.
</li>
<li>
yearly: A yearly review will be conducted to ensure that the record is valid.
</li>
</ul>
</li>
<li>
Technical Person / Data Manager: These two types of data have
the same fields and detail who was responsible for the
calibration and who is responsible for maintaining the record
of the calibration. In many cases, this may be the same
person and copy buttons allow the fields to be duplicated.
<ul>
<li>
Name: Responsible party’s naem
</li>
<li>
Organisation: Organisation to which the party reports
</li>
<li>
Position: Responsible party’s title
</li>
<li>
Email: Email contact information
</li>
</ul>
</li>
</ul>
<p>
Fill in as much information as you can!
If the export is successful, a record will show for each
hydrophone (or sensor) in your instrument array in the
calibration information table:
</p>
<div>
<img src="./images/calibration_information.png" class=".center"
alt="Panel with information about instrument calibration"/>
</div>
<h3>Deployments</h3>
<p>
Tethys uses deployment records to register information about
when instruments have been deployed as well as their
characteristics. Examples of characteristics that are recorded
include sample rate and the number of quantization bits,
description of duty cycles (if applicable), hydrophone geometry,
and enough details to be able find calibration data for specific
hydrophones.
</p>
<p>
PAMGuard will examine the
<a href="../../generalDatabaseHelp/docs/database_database.html">PAMGuard
database</a>
and <a href="../../BinaryStore/docs/binarystore_overview.html">
binary Store</a> to determine what records should be generated for
your instrumentation.
</p>
<p>
Where data were collected continuously or on a regular duty
cycle, PAMGuard will create a single deployment record. If data
were collected on a more "ad-hoc" basis, where the instrument has
been deployed multiple times or has irregular recording, PAMGuard
will generate a deployment record for each period of recording.
</p>
<p>
The figure below shows an example of ad-hoc recording periods
identified by PAMGuard:
</p>
<div>
<img src="./images/deploymentspanel.png" class=".center"
alt="Panel showing recording times/deployments for this PAMGuard database"/>
</div>
<p>
Occasionally, there may be short recording periods (e.g. while
you were testing kit on deck) that you do not want to export. Use
the select checkbox to pick all of the rows that you wish to
export, or right click on the table and "Select All."
</p>
<p>
When one or more deployment records are selected, the
"Export..." button will become available. Selecting the export
button will start a dialog that asks for additional information
about the deployments and then write records to Tethys.
</p>
<p>
The first page of the dialog asks for the project and geographic
region which will be automatically populated if they have been
previously specified. In addition, the following fields are
requested:
</p>
<ul>
<li>Cruise name - Optional name of the deployment cruise</li>
<li>Site - Case-sensitive name for the deployment site,
e.g. "Tanner Banks" or a letter designation "T". This can
provide a simple way to identify multiple deployments at the
same general location.
</li>
<li>Responsible Party - A set of fields describing who was
responsible for the deployment and how they may be
contacted.
</li>
</ul>
<p>
The next page of the dialog asks whether you would like to
export a single deployment document or multiple deployments.
<strong>todo: add more detail here</strong>
</p>
<p>
Finally, you are prompted to provide optional textual descriptions of:
<ul>
<li> Objectives - What were your objectives when deploying the
instrument? Example: Determine population estimates for
critically endangered populations of vaquita (<em>Phocoena
sinus</em>).
</li>
<li> Abstract - A textual description of the deployment.
Example: A set of high frequency recorders were deployed across the
northern portion of the Sea of Cortez in the historical range
of the vaquita (<em>Phocoena sinus</em>). These recordings will
support detection and density estimation efforts.
</li>
<li>
Method - A description of the methods used. Example:
Small boat deployment of bottom moored SoundTrap recorders
with acoustic releases.
</li>
</ul>
Press Finish to export the records. Once the
document(s) have been successuflly exported, the document name
associated with each recording period will be shown in the
Tethys Deployment column.
</p>
<h3>PAMGuard data blocks</h3>
<p>
The bottom left panel shows a list of different types of
PAMGuard data that can be exported. The data in this list
correspond to the various PAMGuard modules that have been
configured. See the
<a href="../../../overview/PamMasterHelp/docs/modelViewer.html">
data model viewer</a>
help for an example of how PAMGuard might be configured.
</p>
<h4>Species information</h4>
<p>
Some of these data represent detections of specific species or
phenomena that must be translated to Tethys. A context menu
(right-click on most computers) will show the option "Species
info..." that will allow you to specify the
<a href="./tethys_speciescodes.html">translation of events</a>
to species identifiers and call/sound types. If you try to export
without having done this, the species info dialog will be started
automatically prior to export.
</p>
<h4>Selecting data blocks for import</h4>
<p>
In the sample data blocks below, four modules have been
configured, but only one of them has been run. Column "N Pam
Data" indicates the number of data records that have been
produced, and "PAMGuard Time" tells us when the data were
processed. "Tethys Documents" indicates how many Tethys records
have been produced, and should be 0 until the data are exported.
</p>
<div>
<img src="./images/data_blocks.png" class=".center"
alt="List of results showing detections and other module processing events"/>
</div>
<p>
Select the data blocks to be exported by clicking on them.
Multiple lines can be selected by using keyboard modifiers such as
holding the shift while clicking to select all data blocks between
the last clicked block and where you click. Holding the alternate
(ALT) key will allow selection or de-selection of a single item
without affecting the selection state of other blocks.
<p>
<p>
<em>
SUGGESTION: It looks like we have to highlight these by clicking
on them. As we use select boxes for recording periods, we might
want to do the same thing here... We might want to rename
N PAM Datas to N PAM Data as data are already plural.
</em>
</p>
<h4> Exporting data blocks </h4>
<p>
Once the data blocks have been selected, press export. A series
of dialogs will guide you through the export process. The first
set of dialogs simply display a summary of information about what
will be exported.
</p>
<div>
<img src="./images/stream_algo_info.png" class=".center"
alt="List of details describing the mechanism, parameters, and version of modules used in processing"/>
</div>
<p>
There is nothing to change in this summary. Press Next once you
have reviewed it. The second panel allows specification of your
objectives, abstract, and method. Many modules will have
pre-populated the method for you. While it is recommended to populate
the objectives and abstract, these fields are optional.
<strong> Need to make them optional, currently mandatory. </strong>
</p>
<p>
Press Next to proceed to the next step of the dialog. You will be asked
what details you wish to store within the parameters that were used to
produce these data. Your must select one of the following:
</p>
<ul>
<li> None - Do not report any of parameters used to produce these detections (not recommended) </li>
<li> Data selector only - <strong>not sure what this is</strong> </li>
<li>
Module only - Report the parameters that were set with this
module. Only parameters associated with the specific module
will be reported. Examples include score and duration thresholds
as well as any other type of criterion used to determine whether
or not an event is associated with a specific phenomenon or species.
</li>
<li>
Full process chain (default) - This is the most verbose option. It includes the module
parameters as well as anything else that is part of the signal processing chain that leads
to the module. As an example, a module only setting would not report the parameters that were
used to generate a spectrogram that was presented to a module for classification, but the
full process chain would record these details as well. Use this option will dramatically
increase the potential to reproduce your results, but it will generate a large amount of data
about the signal processing chain, much of which might not be useful.
</li>
</ul>
<p>
The final page of the dialog has an "Export data" button. Press
this to export the data. The system will begin generating the
Tethys document and the "Export data" button will be relabeled "Export complete"
once it is done. At this point, you can press "Finish" to close the dialog.
</p>
<strong>We'll need to have a conversation about exporting, I don't see the summaries and my attempt to export 613 events wrote out an XML document with the effort specified, but no detections. </strong>
<br>
<br>
<p class="prevLink"><a href="tethys_overview.html">Previous: Overview</a></p>
<p class="nextLink"><a href="tethys_server.html">Next: Tethys Server</a></p>
<br>
<br>
<br>
</body>
</html>

10
src/help/utilities/tethys/docs/tethys_speciescodes.html
View File

@ -179,4 +179,14 @@
</p>
<br></br>
<br></br>
<p class="prevLink">
<a href="detect_localize.html">Previous: Detections & Localizations</a>
</p>
<p class="nextLink">
<a href="tethys_overview.html">Returrn to overview</a>
</p>
</body>