Instrument calibration information
+ ++ 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. +
++ There are two dialogs associated with calibration. The first + asks for a calibration method and has the following fields: +
+ +-
+
-
+ Method: Must be one of the following options:
+
-
+
- Reference hydrophone +
- Manufacturer’s specification +
- Piston phone +
- Other calibrated source +
- Unknown +
+
+ - + Serial number: Hydrophone serial number + + +
-
+ Quality: Quality assurance value:
+
-
+
- unverified: The calibration has not been verified +
- valid: The calibration has been validated as per the quality assurance process +
- invalid: The calibration was found to be invalid during quality assurance +
+
+ - + QA Comment: Textual description of the quality assurance + process. + + + +
- + Calibration method: Textual description of the Method. + +
+ The second calibrations dialog asks for: +
+ +-
+
- + Calibration date: Date the calibration was performed. + + +
-
+ Update frequency: Must be one of the following:
+
-
+
- + as-needed: No updates are planned, but if a change is needed the calibration will be updated (defaul)t + +
- + unplanned: There are no plans to ever update the record. + +
- + yearly: A yearly review will be conducted to ensure that the record is valid. + +
+
+ -
+ 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.
+
+
-
+
- + Name: Responsible party’s naem + +
- + Organisation: Organisation to which the party reports + +
- + Position: Responsible party’s title + +
- + Email: Email contact information + +
+
+
+ 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: +
+ +
+ +
+
Previous: Module overview
+ Next: Instrument deployments
+
+ Make sure you have a Tethys Server running. The PAMGuard interface will
+ only work with Tethys
+ 3 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.
+
+ 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://.
+
+ 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).
+
+ 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:
+
+ 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.
+
+ 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.
+
+
+ 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.
+
+ 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.
+
+ PAMGuard will examine the
+ PAMGuard
+ database
+ and
+ binary Store to determine what records should be generated for
+ your instrumentation.
+
+ 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.
+
+ The figure below shows an example of ad-hoc recording periods
+ identified by PAMGuard:
+
+ 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."
+
+ 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.
+
+ 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:
+
+ The next page of the dialog asks whether you would like to
+ export a single deployment document or multiple deployments.
+ todo: add more detail here
+
+ Finally, you are prompted to provide optional textual descriptions of:
+
+
+
+
+
diff --git a/src/help/utilities/tethys/docs/connection.html b/src/help/utilities/tethys/docs/connection.html
new file mode 100644
index 00000000..7dc8b75e
--- /dev/null
+++ b/src/help/utilities/tethys/docs/connection.html
@@ -0,0 +1,121 @@
+
+
+
+
+ Connection and Project Details
+
+ Tethys Server
+
+
+
+
+
+ Project and Instrument Information
+
+
+
+
+
+
+
+
diff --git a/src/help/utilities/tethys/docs/deployments.html b/src/help/utilities/tethys/docs/deployments.html
new file mode 100644
index 00000000..afde0149
--- /dev/null
+++ b/src/help/utilities/tethys/docs/deployments.html
@@ -0,0 +1,143 @@
+
+
+
+
+
+Deployments
+
+ 
+
+
+
+
+
+
+ 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.
+
+
+ + +
+ Next: Detections & Localizations +
+ + diff --git a/src/help/utilities/tethys/docs/detect_localize.html b/src/help/utilities/tethys/docs/detect_localize.html new file mode 100644 index 00000000..a79be4e5 --- /dev/null +++ b/src/help/utilities/tethys/docs/detect_localize.html @@ -0,0 +1,161 @@ + + + + + +Exporting Detections/Localizations (PAMGuard data blocks)
+ ++ 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 + + data model viewer + help for an example of how PAMGuard might be configured. +
+ +Species information
+ ++ 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 + translation of events + 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. +
+ +Selecting data blocks for import
+ ++ 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. +
+ +
+ + 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. +
+ +
+ + 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. + +
+ +Exporting data blocks
+ ++ 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. +
+ +
+ + 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. +
+ ++ 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: +
+ +-
+
- + None - Do not report any of parameters used to produce these + detections. This option is not recommended 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. + +
- Data selector only - not sure what this is +
- + 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. + +
- + 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. + +
+ 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. + + Would it make more sense to export when the user presses + Finish (or change the Finish button Export)? +
+ + + ++ Translating species to + taxonomic serial numbers (species encoding) +
+ + + diff --git a/src/help/utilities/tethys/docs/images/data_blocks.png b/src/help/utilities/tethys/docs/images/data_blocks.png new file mode 100644 index 00000000..ee80ccff Binary files /dev/null and b/src/help/utilities/tethys/docs/images/data_blocks.png differ diff --git a/src/help/utilities/tethys/docs/images/species_codes.png b/src/help/utilities/tethys/docs/images/species_codes.png new file mode 100644 index 00000000..db8ce2ae Binary files /dev/null and b/src/help/utilities/tethys/docs/images/species_codes.png differ diff --git a/src/help/utilities/tethys/docs/images/species_search.png b/src/help/utilities/tethys/docs/images/species_search.png new file mode 100644 index 00000000..73b2c36f Binary files /dev/null and b/src/help/utilities/tethys/docs/images/species_search.png differ diff --git a/src/help/utilities/tethys/docs/images/stream_algo_info.png b/src/help/utilities/tethys/docs/images/stream_algo_info.png new file mode 100644 index 00000000..d9480428 Binary files /dev/null and b/src/help/utilities/tethys/docs/images/stream_algo_info.png differ diff --git a/src/help/utilities/tethys/docs/tethys_module.html b/src/help/utilities/tethys/docs/tethys_module.html new file mode 100644 index 00000000..e21ce748 --- /dev/null +++ b/src/help/utilities/tethys/docs/tethys_module.html @@ -0,0 +1,92 @@ + + + +Tethys Module Overview
+ ++ It is assumed that you are familiar with PAMGuard and have some + knowledge about Tethys. + Documentation + and tutorials + are available at the Tethys + web site. +
+ +Launch PAMGuard in viewer mode
++ Tethys export is only available in + PAMGuard + Viewer mode + and is used to archive project data to a centralised + database. It is NOT a replacement for the + existing PAMGuard + database. Open the PAMGuard database that you wish to use + in viewer mode. +
+ +PAMGuard Tethys Module
+ ++ Add a Tethys module to PAMGuard from the File / Add Modules / + Utilities menu. A new tab panel will show the Tethys interface +
+ +
+ + 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. +
+ ++ The Tethys module consists of several panels: +
+-
+
- + Connection and Project Details - + Specifies the location of the Tethys server and metadata about + the project. + +
- Data Export - There are several panes that are responsible
+ for exporting information about instrument deployments, their
+ calibrations, and what they detected/localized.
+
-
+
- + Instrument calibration + information + + +
- + Recording periods + and deployments information. + + +
- + Detections and + localizations. A final panel next to this one lists + exported detection/localization documents. + +
+
+
+
+ +
Next: Connection + & Project Details
++ + diff --git a/src/help/utilities/tethys/docs/tethys_overview.html b/src/help/utilities/tethys/docs/tethys_overview.html index 9419fe10..6e9e6515 100644 --- a/src/help/utilities/tethys/docs/tethys_overview.html +++ b/src/help/utilities/tethys/docs/tethys_overview.html @@ -21,48 +21,68 @@ img { -
Tethys Interface
-Overview
+Tethys Interface
+ +Overview
-
- 
-
- - Tethys 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. - -
-PAMGuard is compatible with Tethys 3.0 or above, released early in 2024.
-The Tethys database is not a replacement for the existing - PAMGuard Database. - 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 is compatible + with Tethys 3.0 or + later. + Tethys 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. +
+ + ++ The Tethys database is not a replacement for the existing + PAMGuard + Database. 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. +
-Before using the module in PAMGuard, you should install the Tethys Server, which runs under - Windows. - Instructions for installing the Tethys Server can be found here.
- ++ 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. + Instructions + for installing the Tethys Server can be found here.
+ +-
- - - Next: Quick Start - -
-
-
+
+ Module help: +
+-
+
- The Tethys module (start here) +
- The Connecting to Tethys +
- The Instrument calibrations +
- The Instrument deployments +
- The Detections & Localizations +
- Guide to specifying species names +