PAMGuard/Tethys 2025 workshops

When Tethys is installed, documentation can be found locally in the documentation folder contained in the folder where Tethys was installed. Documentation can also be accessed here.

User documentation

  • Introductory videos are available on the tutorials page.
  • Web Client – Provides documentation for how to query Tethys through a web browser and export data to Matlab, R, and XML. Note that the web client also has a facility for importing data that was a recent addition into the current release and has not yet been documented. From the web client menu, select import data. You will need to select a source map which indicates how data will be mapped from your data source (database, spreadsheet, CSV) to Tethys fields. See the web client manual for details on how to create a source map if you need a new one. You will then need to specify the type of data collection, and how taxa are encoded. The second step is to specify your data source. You specify the database or file type, and the name of the source. If using a database, you will need to specify additional information such as characteristics of the database server and account information. For file import, just drag and drop the file into the file area. If your document has additional data that requires attachments (e.g., a spectrogram image), these files must be dragged and dropped to the attachments area. Finally, click “Start upload.”
  • Data Explorer – Interactive exploration of your data. Point and click interface, no need to wrtie queries.
  • Matlab cookbook – Recipes to get the reader started using Tethys using the Matlab client. Also see the dbDemo.m script in the downloaded software.
  • R client – Documentation of software to query Tethys from the R programming language.
  • Java client – Documentation of software to query Tethys from Java.
  • User manual – Large manual with details on installing, administering, and using Tethys.

Understanding how we represent data

  • Roch et al. (2016), Management of acoustic metadata for bioacoustics lays out many of the guiding principles of the data that we retain.
  • Our standards work has a narrative explanation of our data, explaining what we retain and why. Note that the standard is evolving and may differ from what is in the current distribution.

Tethys XML schemata are used as a concrete implementation of our data ontology. It is assumed that serious users of the database will spend sometime becoming familar with the Tethys data model. An introduction to understanding schemata in general is available in the Tethys user manual. In addition, the draft standards documents contain a scenario section that explains how data are represented generally, without considering the specifics of an XML representation.
Tethys stores data in a native XML database. In general, users of Tethys do not need to learn languages to query XML databases, and the client programs extract most of the details away from the user.

For people who with a deeper understanding of XQuery, XPath, and XML Schemata, we suggest consulting the following texts:

  • for XML Schema: Walmsley, P. (2002). Definitive XML Schema. Upper Saddle River, NJ: Prentice Hall PTR.
  • for XQuery and XPath: Walmsley, P. (2006). XQuery. Farnham, UK: O’Reilly

Schemat are stored in the database directories: database-name/lib/schema/*.xsd and are best viewed with a schema viewer such as OxygenXML. A less interactive version of the schemata can be viewed here.

Technical documents for developers

  • Nilus – Support for generating Tethys compatible output from detection, classification, and localization algorithms. Many users will not need to use Nilus. If your data can be mapped in a relatively straight-forward manner from your fields to Tethys, consider the data source map creation tool in the web client. For more complicated workflows, Nilus lets users control every aspect of creating Tethys-compliant XML that can be directly submitted to the database. The Nilus manual is written for algorithm developers that wish to develop Tethys ready output as opposed to using Tethys’s import interface. In addition to the manual, application programming interface documents are available.
  • Encrypted data transmission – Tethys can serve data over secure socket layer, a data transport method commonly used in web commerce such as banking. Using Tethys requires obtaining a certificate and public/private key pair, this document explains how to configure Tethys to use certificate based authentication and encryption.
  • The RESTful web services document describes the protocol for client programs to communicate with Tethys web servers.