Annotation Database Entity Documentation

The database is large, complex and relational with a lot of entities describing many facets of ROV operations, measurements and observations, as well as user authentication, shared resources (e.g., taxonomy), etc.

Notes About Specific Entities

These notes about specific entities complement the generated documentation below.

rov.dive and rov.transect

Dives represent the span of time during which an ROV, submersible or drop camera is in the water, but may also represent the time during which the instruments are operating. In cases when the instrument data are contained entirely within the time span logged by the operator, the times are recorded unchanged. When the instrument data extend beyond the recorded times of the dive, they may be extended. Occasionally, the operator will record an erroneous time, or omit a time altogether. The instrument times can help to reconstruct this history. Dives also relate to important configuration information, objectives, crew and operational notes.

Transects are defined by their start and end times, contained entirely within dives and do not cross the boundaries between dives. They do not have any related entities and function mainly as accounting items. However, they are extremely important in the analysis of observations and measurements collected during the dive. For example, if one is calculating the density of a particular population of organisms, one must know the precise geographic extent of the region. Transects accomplish this and store objectives and operational notes.

In instances where the times of transects are not recorded, or lost, they can sometimes be reconstructed from status events in the observation record (e.g., a VideoMiner database may have transect start/end events). Otherwise, they are not recorded at all. Ideally, transect records are present and their start and end times are recorded without modification, so long as they are reasonable (i.e., the end time occurs after the start time).

Documentation

Database entity documentation is generated from the production database by the script, db_generate_docs.py. The script outputs a file whose contents can be copied into this page after the <!-- BEGIN GENERATED CONTENT --> tag.

Documentation resides in the database itself, in the form of comments on the relations and columns. Documentations can be created by executing SQL statements in the form,

   COMMENT ON SHCEMA [schema] IS 'This is a schema comment.'
   COMMENT ON TABLE [schema].[table name] IS 'This is a table comment.'
   COMMENT ON COLUMN [schema].[table name].[column name] IS 'This is a column comment.'

Comments are managed using DDL, as described on the Database Upgrades page.

Note: this page is auto-generated from the documentation comments in the actual database. Do not edit it directly.