2.1 Detections objects | kaltoa: Kalman Filtered Time-of-Arrival Positioning

2.1 `Detections` objects

The heart of kaltoa is the Detections object (see ?Detections). Along with detections data for a given receiver, this also holds useful metadata for the receiver’s position and sync-tags.

Below is a typical table of raw detection data we’ll use to build a Detections object.

head(example)

##                 timestamp detect_id     type
## 1 2021-05-08T18:00:09.427     62074      PPM
## 2 2021-05-08T18:00:38.772     62042      PPM
## 3 2021-05-08T18:00:48.244     62584      PPM
## 4 2021-05-08T18:01:03.878  PPM_SELF PPM_SELF
## 5 2021-05-08T18:02:21.749     62368      PPM
## 6 2021-05-08T18:05:23.948     62074      PPM

First, we’ll convert our detection ISO dates-time strings into a more handy format.

# Convert times into numeric values
detect_time <- iso2DetectionTime(example$timestamp, tz = "CET")
# Preview detection times
head(detect_time)

## Time zone: CET
##                second millisecond
## 1 2021-05-08 18:00:09         427
## 2 2021-05-08 18:00:38         772
## 3 2021-05-08 18:00:48         244
## 4 2021-05-08 18:01:03         878
## 5 2021-05-08 18:02:21         749
## 6 2021-05-08 18:05:23         948

Here, the column titled second holds POSIX times — the number of seconds since 1970-01-01. The tz option lets you specify what timezone the time stamps were recorded in.

Now we’ll put this into a Detections object.

detect <- Detections(
  detect_times = detect_time,
  detect_id = example$detect_id, # Vector of detection IDs
  x = 481472,   # Easting (m)
  y = 6243509,  # Northing (m)
  depth = 3,    # Depth (m)
  emit_id = "62041", # Sync-tag detection ID
  name = "1",   # Name of this receiver
  type = example$type,  # Type of detection (PPM or HR)
  sync_emissions = example$type %in% c("PPM_SELF", "HR_SELF"))

head(detect)

## Telemetry Detections
## Name: 1
## Sync-tag ID: 62041
## Depth: 3
## Coords: (481472 m, 6243509 m)
## Sync tag emissions: 144
## Detections: 651
## First detection on: 2021-05-08 18:00:09
## Last detection on: 2021-05-09 05:59:56
## Time zone: CET
##                second millisecond detect_id     type sync_emission
## 1 2021-05-08 18:00:09         427     62074      PPM         FALSE
## 2 2021-05-08 18:00:38         772     62042      PPM         FALSE
## 3 2021-05-08 18:00:48         244     62584      PPM         FALSE
## 4 2021-05-08 18:01:03         878  PPM_SELF PPM_SELF          TRUE
## 5 2021-05-08 18:02:21         749     62368      PPM         FALSE
## 6 2021-05-08 18:05:23         948     62074      PPM         FALSE

kaltoa uses sync-tags to align the receiver clocks in a telemetry array. That is, stationary tags embedded into the receivers with known emission times. The argument sync_emissions tells kaltoa which rows represent sync-tag emissions. That is, detections of that receivers own sync-tag. We have the supplementary type column to distinguish between the types of tags detected/emitted when composite tags are used.

Finally the generic summary function gives you an overview of what tags were detected when.

summary(detect)

## Detections Summary (name: 1)
## Time zone: CET
##  detect_id               first                last period (h) count
##   PPM_SELF 2021-05-08 18:01:03 2021-05-09 05:58:01 11.9494444   144
##      62042 2021-05-08 18:00:38 2021-05-09 05:56:37 11.9330556   118
##      62074 2021-05-08 18:00:09 2021-05-09 05:59:56 11.9963889   117
##      62368 2021-05-08 18:02:21 2021-05-09 05:55:31 11.8861111   117
##      62581 2021-05-08 18:06:05 2021-05-09 05:55:42 11.8269444   112
##      62584 2021-05-08 18:00:48 2021-05-09 05:52:23 11.8597222   110
##   HR-53883 2021-05-08 20:41:34 2021-05-08 21:03:53  0.3719444    67
##  PPM-53883 2021-05-08 20:57:29 2021-05-08 21:04:35  0.1183333    10